WAN 2.5 API QuickstartがWaveSpeedAIに登場：認証、パラメータ、リクエスト例

こんにちは、Doraです。元々、今週はWaveSpeed上のWAN 2.5 APIを試そうと思っていませんでした。小さな不便さがそこに導きました。草稿用に一貫性のあるいくつかの画像バリエーションが必要でしたが、いつもの道具は、クリックが多すぎるか、その道具自身のために賢すぎるかのどちらかでした。退屈で信頼できる、スクリプト化可能で、バージョン管理でき、簡単にロールバックできるものが必要でした。

それで、ドキュメントを開き、お茶を淹れ、小さなスクリプトを組み立てました。これは、2026年1月にテストした私の見つけたことで、磨きなしです。「機能」についてというより、一度それらが導入されると仕事をより軽く感じさせた部分についてです。

API概要

最新のAI APIに触れたことがあるなら、WaveSpeedのWAN 2.5への取り組みは馴染みあるものに感じるでしょう。HTTPで入力、JSONで出力。プロンプト（時々は画像も）を送信すると、完成した成果物またはポーリング可能なジョブIDが返されます。

コードを書く前に注視した基本的な詳細がいくつかあります。

バージョン管理: WAN 2.5は異なるバージョンとして公開されており、これは再現性に重要です。私は「最新」エイリアスではなく、URLの明示的なバージョンパスを使用しました。この小さな選択は、将来の私を静かな動作変化から救います。
モード: 一部のワークロードは同期的（小さく、速い）で、他は非同期ジョブとしてスピンオフします。より高解像度の生成またはバッチ作業を行う場合は、ステータスエンドポイントまたはWebhookでの非同期フローを期待してください。
形式: JSON応答は通常、ステータス、アセットURLまたはbase64ペイロード、およびいくつかのメタデータ（シード、ステップ、タイミング）を含みます。後で見た目を再現したいときのために、メタデータを保持します。
制限: 画像サイズ、ステップ数、同時実行数には上限があります。デフォルトは草稿に十分でしたが、解像度を上げようとしたら天井に当たりました。レート制限については以下を参照してください。

簡潔に言えば、RESTに慣れていれば、簡単な道のりです。コツは、退屈な部分（キー、パラメータ、リトライ）をいくつか正しく設定して、それらを忘れることです。

このシンプルさは、私たちがWaveSpeedを構築した方法の一部です。WAN 2.5（と他のモデル）がスクリプト化可能で、バージョン管理でき、最高の意味で退屈に感じてほしかったのです。これを自分で組み立てている場合、ここで探索できます。

認証とキー

WaveSpeedダッシュボードでWaveSpeed APIキーを生成し、環境変数に落とし込みました。派手なことはありませんが、ファイル全体でシークレットを追い求めることを避けました。

WaveSpeedのアカウント設定からキーを取得します。あなたの組織/プロジェクトに紐付けられています。
ローカルに環境変数として保存します。WAVESPEED_API_KEY。開発用には.envファイルを使い、実行用にはCIのシークレットストアを使いました。
ヘッダーでBearer認証を使用します。Authorization: Bearer $WAVESPEED_API_KEY。
キーをローテーションする場合は、トラフィック量の少ない時間帯に行うのが良いです。タイミングされたローテーションが長いジョブを中断したときに、静かな方法でこれを学びました。

チームがスコープ付きキーを必要とする場合は、ダッシュボード設定を確認してください。オートメーションに紐付けられたものすべてについて、最小権限の道を好みます。1つの小さな摩擦は、複数のマシンから実行している場合、ホストまたはサービスでキーを明確にラベル付けすることです。後で使用法を監査するときに役立ちます。

必須パラメータ

正確な名前はエンドポイントによって異なる場合がありますが、WaveSpeedのWan 2.5に使用した最小限の形状は次のとおりです。これらを骨組みとして扱い、アカウントの公式ドキュメントでフィールド名を確認してください。

model: これを明示的にwan-2.5に設定しました（またはあなたのプランの最も正確な文字列に）。更新全体で動作を安定させます。
input: プロンプト文字列。短く具体的に保ちました。WANは形容詞のスープより、明確でシンプルな表現に良く応答する傾向があります。
mode or task: 画像生成対バリエーション/アップスケール。ソース画像を渡す場合、これは重要です。
output: デフォルトで画像URLを求めました。Base64はありますが、URLはメモリに優しいです。

モデルを明示的に設定するのを忘れたとき、適切なデフォルトが得られましたが、結果は実行全体で微妙にシフトしました。間違っていませんが、再現可能ではありません。バージョンをロックすることでそのぐらつきが取り除かれました。

オプショナルパラメータ

ここに実際の制御があります。初日には数個だけ触りました。

seed: 見た目が気に入ったら、これをオンにします。バリエーションのバイブを安定させます。
steps: より高いステップは詳細を押し上げる可能性がありますが、時間とクレジットの代償を伴います。小さな増分（例えば、24 → 32）でバンプして、返品を見守りました。
guidance or cfg_scale: プロンプトへの厳密さを強化します。高すぎるとぎこちなくなります。
size or resolution: ここでコストがジャンプします。小さくドラフトし、その後ターゲットサイズでファイナルを再実行しました。
image: バリエーション用に、ソース画像URLを渡すか、アップロードします。サポートされている場合は、強度パラメータとペアにします。
safety or moderation flags: ワークフローが本当にカスタム処理を必要としない限り、それらをオンにしておきます。
user or metadata: リクエストIDまたはプロジェクトタグを追加して、後でログで実行をトレースします。

小さな観察: 2つのノブを同時に変更することは、何が役立ったかを判断するのが難しくなります。1回の実行につき1つのことを変更し、コメントに注記を保持しました。昔ながらですが、機能しました。

リクエストパターンサンプル

3つの簡単な形状を試しました。クイックcurl、小さなPythonスクリプト、非同期のバックグラウンドジョブです。

同期ドラフト（curl）

これは、他に何かを配線する前に、キーとプロンプトの健全性をチェックするのに十分でした。

エンドポイント例、アカウントと地域のドキュメントの正確なパスを確認してください。

POST https://api.wavespeed.ai/wan/v2.5/generations

ヘッダー:

Authorization: Bearer $WAVESPEED_API_KEY
Content-Type: application/json

ボディ（最小限）:

{
  "model": "wan-2.5",
  "input": "quiet studio light, sketch on kraft paper",
  "output": { "format": "url" }
}

私が見守ったことは:

結果とメタデータを含む200 → あなたは良好です。
ジョブIDを含む202 → 非同期フローに切り替えます。
4xx → ペイロードまたは認証で何かが間違っています。

小さなPythonヘルパー

ヘッダー、タイムアウト、およびjsonを処理するための小さな関数を書きました。それはURLを返すか、クリーンな例外を発生させました。何も魔法的ではなく、二度と考える必要のない種類のラッパーです。

実用的なビット:

短い接続タイムアウトとやや長い読み取りタイムアウトを設定します。
リトライとジッターで429を処理します。
各実行のシード、ステップ、およびサイズをログに記録します。

非同期フロー（ジョブ）

より大きな画像またはバッチの場合、202とジョブIDが得られました。ループは簡単でした。

POSTジョブ、

数秒ごとにGET /jobs/{id}をポーリング、
ターミナル状態（成功/失敗）で停止、
アセットURLを取得します。

スタックがWebhookが好きな場合、WaveSpeedもコールバックを公開しています。初期設定中に1つの移動部分を少なくするために、ポーリングでスタックしました。

エラーコード

私はエディターの隣に小さなマップを保持しました。期待していたより早く報いを受けました。

400 Bad Request: 通常、フィールド名またはタイプの不一致。一度サイズを文字列で送信しましたが、オブジェクトではありませんでした。修正は、落ち着いて、メッセージを読むと一度に明白でした。
401 Unauthorized: キーが欠落しているか、不正な形式です。Bearer ヘッダーと末尾のスペースをチェックしてください。
403 Forbidden: キーは存在していますが、エンドポイントまたはモデルティアのスコープが不足しています。
404 Not Found: 不正なエンドポイントパスまたはジョブIDが期限切れ。
409 Conflict: すでに決定したジョブを更新するときに、これを見ることがあります。再度ポーリング、押し続けないでください。
429 Too Many Requests: 1分あたりまたは組織あたりの制限を超えています。指数関数的リトライでバックオフしてください。
500/503 Server Errors: 私のテストではレアですが、計画してください。短いリトライループは私のスクリプトを落ち着かせました。

役に立った小さな習慣: エラーコードとリクエストID（存在する場合）をログにバブルアップしました。何か奇妙なことが起こったとき、サポートはそのIDを使用してそれをトレースできます。

レート制限

非同期を怠けた後、レート制限にぶつかりました。やりやすく、避けやすいです。

何が機能したのか:

ヘッダーを尊重する: 多くのエンドポイントはレートヘッダーを返します（例えば、残り、リセット時間）。ヘッダー名は異なる場合がありますが、ドキュメントをチェックしてください。しかし、それらは読む価値があります。
トークンバケットまたはシンプルなキューを使用します。バースト代わりに、小さく、一定の滴へスクリプトを制限しました。システムはより簡単に呼吸でき、そう私もしました。
ドラフトとファイナルを分離します。ドラフトは小さく速く実行できます。ファイナルはバックグラウンドで1つずつ実行できます。
繰り返しをキャッシュします。プロンプトをテストしている場合、同じ呼び出しを焼かないように、前の結果を数分間保持します。

また、非常にプレーンなバックオフも構築しました。ベース遅延1秒、各429で倍にすると、30秒上限と最大4回の再試行が可能です。それはせかせかしておらず、サービスへの犬パイルを避けました。

コストガードレール

これは私の主な心配でした。画像作業はお茶を淹れている間、背景でクレジットをかじることができます。

初日に設定した保護がいくつかあります。

ダッシュボード予算キャップ: 月額上限とメール警告をそれより少し下に設定しました。チームがキーを共有している場合、警告はループを早期にキャッチするのに役立ちます。
リクエストごとの上限: 上限オーバーライドフラグを渡さない限り、サイズとステップを上限の下で強制しました。「おっと、4Kすべて」から私を救いました。
ドラフト優先ワークフロー: 小さいプレビュー（低解像度、より少ないステップ）を実行し、キーパーのみをアップスケールします。これは初日の午後の半分以上で支出を削減しました。
シード規律: 好きな方向を見つけたら、シードを修正し、1回に1つのパラメータを変更しました。より少ないブラインド実行、より意図的なものです。
コスト付きログ: レスポンスに信用またはティーク使用フィールドが含まれている場合（いくつかのエンドポイント）、保存します。そうでない場合は、解像度とステップに基づいて推定し、見積もりであることに注記します。

また、スクリプトにソフトキルスイッチを置きました。その日の使用量が閾値を超えた場合、新しいジョブは一時停止され、Slackにメッセージを投稿しました。エレガントではありませんが、制約について正直です。

これは最初の時間を節約しませんでした。それは注意を節約しました。数回の実行の後、ガードレールは背景に退き、メーターの代わりに仕事を考えることができました。