WAN 2.7 APIクイックスタート on WaveSpeed (2026)

やあ、みなさん。Doraです。ずっと先延ばしにしていました。WAN 2.7がリリースされました。これを必要とするプロジェクトがあって、「落ち着いたら組み込もう」と自分に言い聞かせていました。それはたいてい間違った判断です。バージョンの命名を乗り越えてしまえば、APIのインターフェースは直感的です。そして摩擦のほとんどは、序盤に下したひとつかふたつの判断から生まれ、それが後続のすべてに静かに影響を及ぼします。

これはフィーチャーショーケースではありません。初日に実際に必要だったことを書いています。

プラットフォーム上のWAN 2.7：モデルIDと利用可能性

コードを1行も書く前に、モデル文字列の確認だけで10分かかりました。当たり前のことに聞こえますが、WANには人をつまずかせる命名パターンがあります — wan2.5-i2v、wan2.6-i2v、wan2.7-flf2v — 古いIDを使うと、役立つエラーメッセージなしにきれいな404が返ってきます。

モデルカタログが最初に確認すべき場所です。 動画生成セクションに移動し、バージョン2.7でフィルタリングして、正確なモデルID文字列をコピーします。記憶から入力しないでください。

利用可能なタイミングも重要です。WAN 2.7は2026年3月に、意味のある新機能セットとともにリリースされました — ファースト/ラストフレーム制御、3×3グリッドの画像から動画への合成、最大5つの動画リファレンス、そして命令ベースの編集です。Alibaba Cloud Model Studioの動画生成概要によると、新しいWANバージョンのホスト型推論エンドポイントは通常、公式リリースから数日以内に公開されます — ただし常に同じ日とは限らないので、時間的制約のあるものを構築する前にプラットフォームのステータスページを確認してください。

認証とAPIキーのセットアップ

この部分は簡単です。APIキーはBearerトークンとしてAuthorizationヘッダーに入れます。 ベースURLは、アカウント設定時に選択したリージョン（シンガポール、バージニア、または中国本土向けの北京）に従います。リージョンをまたいだ呼び出しは失敗します。大きなエラーではなく、予期していなければ20分を無駄にする認証エラーとして現れます。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

最初からやっていること：APIキーを環境変数に保存し、ローカルのテストスクリプトであってもハードコードしない。流出したキーは、望まない請求の驚きをもたらします。

ベースURLの構造は、IETF RFC 9110（HTTPセマンティクス）で定義された標準的なREST規約に従います。モダンなAI APIを扱ったことがあれば、馴染み深く感じるでしょう — JSONを入力してJSONが返ってきて、ステータスコードは期待通りに動作します。

コアリクエストパラメータ

ここで少し立ち止まることをお勧めします。必須パラメータは少ない — モデルID、プロンプト、入力タイプ — ですが、オプションのものが出力品質を予想以上に左右します。

必須：

model — カタログで確認した正確なモデル文字列
prompt — テキストによる説明。動画の場合、長さより具体性が重要
入力：I2V用のimage_urlまたはT2V用のテキストのみ

オプションだが実用的に重要：

resolution — "480P"、"720P"、"1080P"を受け付ける。WAN 2.7は15秒までのネイティブ1080P出力をサポート
duration — 2〜15秒。長いクリップはコストが高く処理に時間がかかる
seed — 良い出力が見つかったらロックすること。 実行間で結果を再現可能にする唯一のパラメータ
negative_prompt — フリッカー、ブラー、モーションアーティファクトの抑制に有効

公式ドキュメントリリース時に確認すべきWAN 2.7固有のパラメータ：

first_frame_url + last_frame_url — FLF2V（ファーストアンドラストフレーム）モード用
image_grid — より豊かなI2V構成のための9グリッド入力構造
edit_instruction — 既存動画への自然言語による編集

最後の3つは2.7の新機能です。パラメータ名はプレビューから一般公開の間に変わる可能性があります。公式APIリファレンスが権威ある情報源です — 暫定的なパラメータ名で構築する場合は自己責任で行ってください。

最初のリクエストパターン

テキストから動画（最小構成）

response = VideoSynthesis.async_call(
    model="wan2.7-t2v",      # リリース時に正確な文字列を確認
    prompt="A slow dolly shot through a foggy pine forest at dawn.",
    resolution="720P",
    duration=5,
    seed=42
)
task_id = response.output.task_id

標準的な画像から動画

response = VideoSynthesis.async_call(
    model="wan2.7-i2v",
    img_url="https://your-cdn.com/input.jpg",
    prompt="Camera holds still. Subject turns slowly toward light.",
    resolution="720P",
    duration=5
)

ファーストフレーム + ラストフレーム（FLF2V）

これは、WAN 2.7が以前のバージョンではきれいにできなかったことです。開始フレームと終了フレームを定義すると、モデルがその間のモーションを補完します。これは従来の意味でのアニメーションではありません — 2つのセマンティックなエンドポイントからの構造的な推論です。

response = VideoSynthesis.async_call(
    model="wan2.7-flf2v",   # リリース時に正確な文字列を確認
    first_frame_url="https://your-cdn.com/start.png",
    last_frame_url="https://your-cdn.com/end.png",
    prompt="Fixed camera. Smooth transition. Natural lighting.",
    resolution="720P",
    seed=99
)

フレームペアの品質はプロンプトより重要です。 明確な空間的関係を持つよくマッチしたペアは、不一致な入力フレームに対する洗練されたプロンプトを一貫して上回ります。これはある程度の自信を持って言えるほど十分なテストを行いました。オープンウェイト版がフレームコンディショニングをどのように扱うかについては、Hugging Face WANモデルリポジトリがアーキテクチャを詳細に文書化しています — ホスト型APIを呼び出すだけの場合でも参考になります。

9グリッドの画像から動画

9グリッド入力を使うと、1回の生成の構成リファレンスとして3×3の静止画配置を渡すことができます。リリース時に正確なペイロード構造を確認してください — パラメータはおそらく9つの画像URLの配列を受け付けますが、リリース前のドキュメントは暫定的なものとして扱ってください。

非同期ジョブ処理：送信 → ポーリング → 結果

動画生成は決して同期的ではありません。 短いクリップでも、ジョブあたり1〜5分かかります。パターンは常に同じです：送信 → task_idを取得 → ポーリング → 結果URLを取得。

import time

def poll_for_result(task_id, interval=15, timeout=600):
    elapsed = 0
    while elapsed < timeout:
        result = VideoSynthesis.fetch(task_id)
        status = result.output.task_status
        if status == "SUCCEEDED":
            return result.output.video_url
        if status == "FAILED":
            raise Exception(f"Task failed: {result}")
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Job exceeded timeout")

ポーリング間隔：15秒は、AlibabaのWan画像から動画エンドポイントの独自APIリファレンスで記載されている推奨値です。それより速くポーリングしないでください — 処理が速くなるわけではなく、レート制限を消費するだけです。

タスクのステータス遷移：PENDING → RUNNING → SUCCEEDEDまたはFAILED。結果URLは生成後24時間有効です。すぐにダウンロードして保存してください — その期限を逃すと、タスクIDも24時間後に期限切れとなり、以降のクエリでUNKNOWNが返ります。最初のバッチ実行でこれを不格好な形で学びました。

エラー処理

最もよく遭遇するエラー：

エラー	推定される原因	対処法
モデルの404	間違ったまたは古いモデルID	カタログから正確な文字列を確認
入力の400	画像フォーマットが拒否またはURLにアクセス不可	公開HTTPSのURLを使用してフォーマットを確認
429 Too Many Requests	レート制限に達した	ジッターを伴うエクスポネンシャルバックオフ
UNKNOWNタスクステータス	タスクIDの期限切れ（24時間の期限）	早めにポーリングし結果をすぐにダウンロード

429の場合：バックオフし、ジッターを加えて、タイトなループでリトライしないこと。MDN HTTPドキュメントのRetry-Afterヘッダーの動作が標準的なパターンを説明しています — レスポンスヘッダーが正確にいつリトライすべきかを教えてくれることが多いです。

WAN 2.7の動画ジョブのレート制限は、画像生成の制限とは別に公開されています。高解像度または長時間のジョブは通常、1分あたりのリクエスト制限だけでなく、同時実行ジョブ制限にカウントされます。アカウントティアのドキュメントで確認してください。

コスト見積もり

WAN 2.7の価格は執筆時点では確定していませんでした。WANモデルファミリー全体で一貫していることから、コストは3つの次元でスケールします：

解像度 — 1080Pは出力1秒あたり720Pより明らかに高コスト
尺 — 生成動画の1秒あたりで請求
入力の複雑さ — マルチリファレンス入力には乗数がかかる場合があります。リリース時に確認してください

大まかな見積もり式：

estimated cost = duration (seconds) × resolution multiplier × unit price per second

バッチを実行する前に、使用予定の各解像度と尺の組み合わせで1クリップテストしてください。公式のWAN 2.7レートが公開されれば、Alibaba Cloud Model StudioのModel Studio向け請求概要に1秒あたりの単価が掲載されるでしょう。動画生成コストは画像生成よりも速く積み上がります — 解像度が最大のレバーです。

よくある質問

WAN 2.7はAlibaba公式ローンチと同日に利用可能ですか？

常にそうとは限りません。ホスト型APIエンドポイントは通常、オープンウェイトリリースから数日以内に公開されます。同じ日のこともあれば、1週間後のこともあります。プラットフォームの変更ログを直接監視してください。WANモデルのGitHubリポジトリは、Alibabaのチームが新しいオープンウェイトリリースのスキーマ変更を最初に文書化する場所であることが歴史的に多いです。

WAN 2.5のAPI呼び出しはWAN 2.7と互換性がありますか？

標準的なT2Vと単一画像I2Vのペイロードは構造的に互換性があるはずです — 新しい2.7の機能は破壊的ではなく追加的に見えます。とはいえ、モデルID文字列を更新する必要があり、2.5固有のパラメータを使用するコードはドロップインとして扱う前にテストする必要があります。9グリッドとFLF2Vモードは完全に新しいペイロード構造を必要とします。

WAN 2.7の動画ジョブのレート制限は何ですか？

実行時にアカウントティアで確認してください。実用的なデフォルトとして：バースト送信せずに一定のペースでジョブをキューに入れてください。429はエクスポネンシャルバックオフで処理してください。すべてのレスポンスからrequest_idを記録してください — 何か問題が起きてトレースが必要なときに最も有用なフィールドです。

ここでのメカニズスは複雑ではありません。実際に時間がかかるのは、良い入力アセットを構築することです — フレームペア、リファレンス画像、硬直せずに具体的であり続けるプロンプト。それらが安定すれば、API側はルーティンになります。

公式のWAN 2.7パラメータドキュメントが公開され、9グリッドフォーマットをエンドツーエンドでテストする機会を得たら、この記事を更新します。それが最も気になっている部分です。

関連記事：