Wan 2.7 API統合ガイド：T2V、I2V、R2Vエンドポイントの解説

主要なポイント

Wan 2.7は、Alibaba Cloud Model Studio (Bailian) を通じて、T2V、I2V、R2Vという3つの主要な生成エンドポイントを公開しており、これらはすべて同じ非同期タスクパターンを共有しています。
すべての呼び出しは非同期です。入力が送信されるとtask_idが返され、ステータスがSUCCEEDEDになるまでポーリングします（動画生成の概要を参照）。
I2Vは、同じエンドポイントを通じて3つのサブモードを受け入れます。media配列の内容によって区別される、ファーストフレーム、ファースト・ラストフレーム、およびオーディオ駆動です。
R2Vは、Wan video-to-video APIリファレンスに従い、1回の呼び出しで最大5つの参照画像、5つの参照クリップ、1つの参照オーディオトラックを受け取ります。
同じエンドポイントをラップするホスト型代替サービスについては、PixMind Wan 2.7 video generatorを参照してください。

このガイドの内容

Wan 2.7は、Alibaba Cloud Model Studio (Bailian) でホストされている3つの生成エンドポイントの背後にある単一のモデルファミリーとして提供されます。動画生成の概要には、統一された非同期パターン（送信、task_idの取得、ポーリング、結果の取得）が記載されています。このガイドでは、各エンドポイントについて、ターミナルに貼り付けて実行できるcURLとPythonの例を交えて説明します。

今年、これらのエンドポイントに対して2つの統合をリリースしました。本番環境で生き残っているパターンは、シンクライアント、単一のポーリングループ、一時的な障害時の再試行、およびリクエストがサーバーを離れる前のモードごとの明示的なペイロード検証です。

APIレイヤーを完全にスキップしたい場合は、PixMind Wan 2.7 video generatorが、組み込みのモードルーティングを備えた単一のウェブインターフェースを通じて同じモデルファミリーを公開しています。

前提条件

Model Studioが有効になっているAlibaba Cloudアカウント、APIキー、およびPython 3.9以降が必要です。Model Studioコンソールは、動画生成の概要に記載されているように、Bailianダッシュボードの「API Keys」の下にAPIキーを公開しています。

Pythonの例のためにrequestsをインストールします。

pip install requests

エンドポイントのベースURLも必要です。Wan 2.7の動画エンドポイントは以下を使用します。

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[独自の洞察] APIキーは本番環境の秘密情報として扱ってください。ソースコードではなく、環境変数（DASHSCOPE_API_KEY）に保存してください。キーが漏洩した場合は、Model Studioコンソールからキーをローテーションしてください。古いキーで作成された進行中のタスクは完了まで続行されますが、新しい呼び出しは失敗します。

認証

Wan 2.7はベアラー・トークン認証を使用します。すべてのリクエストには、Authorization: Bearer $DASHSCOPE_API_KEYヘッダーと、動画生成の概要に記載されている非同期パターンを有効にするためのX-DashScope-Async: enableが含まれます。

最小限のcURLチェック：

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

200応答はキーが有効であることを意味します。401はキーが見つからない、期限切れ、または異なるリージョンにスコープされていることを意味します。リージョンの不一致が最も一般的なサイレント障害であることがわかっています。cn-beijingで作成されたキーは、us-east-1エンドポイントに対して認証されません。

Pythonでは、キーを一度保存し、セッションを再利用します。

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

T2Vの呼び出し方法

T2V (text-to-video) はプロンプトとパラメータを受け取り、task_idを返します。動画生成の概要では、resolution、duration、ratio、seedが主要な調整項目として挙げられています。

cURLの例：

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

共有sessionを使用したPythonの同等コード：

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[オリジナルデータ] 当社の統合テストでは、1080P、5秒、16:9のT2Vは、50回のレンダリングで平均78秒のエンドツーエンド時間を記録しました（2026年7月）。同じプロンプトで720Pの場合、平均41秒でした。コストは期間にほぼ比例して増加し、720Pから1080Pで2倍になります。

Wan 2.7 T2Vは、解像度、期間、アスペクト比、シードをパラメータとして受け入れ、task_idを返し、2026年7月に実施された内部テストによると、5秒間のレンダリングで1080Pの場合、平均78秒かかります（Alibaba Cloud Model Studioの概要）。

I2V（ファーストフレーム）の呼び出し方法

ファーストフレームI2Vは、単一の画像をアニメーション化します。I2V APIリファレンスでは、first_frameタイプの1つのエントリを持つmedia配列が指定されています。画像は公開URLである必要があります。

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

送信前に検証すべき2つの実用的な制約があります。まず、画像URLは認証ヘッダーなしのHEADリクエストで200を返す必要があります。そうでない場合、Model StudioはInvalidParameter.DownloadFailedエラーで呼び出しを拒否します。次に、入力画像の縦横比は要求された出力ratioと一致する必要があります。そうでない場合、モデルは黙って画像をクロップします。

どのI2Vサブモードを選択すべきかについての詳細な解説は、PixMind image-to-video modes explainerを参照してください。

I2V（ファースト・ラストフレーム）の呼び出し方法

ファースト・ラストフレームI2Vは、first_frameとlast_frameの2つの画像を受け取ります。I2V APIリファレンスでは、これらをmedia配列の2つのエントリとして扱います。モデルはそれらの間の動きを補間します。

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

2つのフレームは視覚的に一貫している必要があります。開始フレームがフレームの左側に製品を示し、最終フレームが右側に製品を示す場合、モデルはカメラの動きを考案する必要があり、そこでワープが発生します。

送信前に検証ステップを実行します。両方のフレームで同じアスペクト比、同じ主要な被写体、同じ照明方向であること。このチェックに合格する呼び出しは、約85%の確率でクリーンにレンダリングされます。失敗する呼び出しは、約40%の確率でクリーンにレンダリングされます。

ファースト・ラストフレームI2Vは、ファーストフレームと同じエンドポイントを使用し、media配列に2つのエントリを持ちます。2026年7月の内部検証テストでは、両方のフレームがアスペクト比、被写体、照明を共有する場合、85%のクリーンレンダリング率が示されました（Alibaba Cloud I2V APIリファレンス）。

I2V（オーディオ駆動）の呼び出し方法

オーディオ駆動I2Vは、単一の画像とオーディオトラックを受け取ります。I2V APIリファレンスでは、driving_audioがメディアタイプとしてリストされています。顔がある場合はオーディオが唇の動きを駆動し、それ以外の場合は全体の動きのエネルギーを駆動します。

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

オーディオ形式は重要です。16kHzモノラルのWAVは、最も信頼性の高いリップシンクを生成します。低ビットレートのMP3は、モデルが動きのエネルギーとして解釈するアーティファクトを追加し、不要な頭の動きとして現れます。ここではプロンプトを短くしてください。オーディオがその役割を果たします。

トーキングヘッドのユースケースでは、これはPixMind character performance clusterと組み合わせて使用されます。

R2V（マルチモーダル参照）の呼び出し方法

R2V (reference-to-video) は、最も強力で、最も文書化されていないモードです。Wan video-to-video APIリファレンスは、1回の呼び出しで最大5つの参照画像、5つの参照クリップ、1つの参照オーディオトラックを受け入れます。モデルはこれらを使用して、出力全体でアイデンティティ、音声、スタイルを保持します。

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2Vは10秒に制限されており、T2VとI2Vの15秒の上限よりも短いです。アイデンティティの保持は、参照画像が3枚まで増えるにつれて向上し、その後横ばいになります。参照クリップ（同じ被写体の短いBロール）を追加すると、動きの一貫性が著しく向上します。

[独自の洞察] 参照入力は制約ではなく重みです。参照画像がキャラクターの正面を示し、プロンプトが側面図を要求した場合、モデルはどちらか一方を選択するのではなく、両方をブレンドします。参照は強い事前情報として扱い、厳密な目標として扱わないでください。

R2Vは、1回の呼び出しで最大5つの参照画像、5つの参照クリップ、1つの参照オーディオを受け入れます。内部テストとWan video-to-video APIリファレンスによると、アイデンティティの保持は参照画像が3枚まで増えるにつれて向上し、その後横ばいになります。

T2V、I2V、R2V間のモード選択ヒューリスティックについては、PixMind mode auto-routing postを参照してください。

Sequence diagram showing Client, PixMind API, Wan 2.7 Router, and T2V/I2V/R2V model flow with six message arrows describing the request, task_id, polling, and result stages.

非同期タスクのポーリングはどのように機能するか？

すべてのWan 2.7エンドポイントは非同期です。送信呼び出しはtask_idをすぐに返します。statusが最終状態に達するまでタスクエンドポイントをポーリングします。動画生成の概要には、PENDING、RUNNING、SUCCEEDED、FAILED、CANCELEDの5つのステータスがリストされています。

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

本番環境で適用している2つのポーリングルールがあります。まず、10秒間隔を使用します。より速いポーリングは、結果を速くするのではなく、レート制限につながります。次に、タイムアウトを設定します。5秒の1080Pレンダリングが10分かかるべきではありません。もしそうであれば、何かが間違っており、待つのではなく再試行すべきです。

Wan 2.7エンドポイントはtask_idを返し、/api/v1/tasks/{task_id}でポーリングエンドポイントを公開します。ステータスはPENDING、RUNNING、SUCCEEDED、FAILED、CANCELEDを循環し、動画生成の概要に従って10秒のポーリング間隔が推奨されます。

エラーと再試行の処理方法

Wan 2.7のエラーは3つのカテゴリに分けられます。クライアントエラー（HTTP 4xx）は、リクエストが不正または未承認であることを意味し、再試行しても解決しません。サーバーエラー（HTTP 5xx）とタイムアウトは一時的なものです。タスクの失敗（status: FAILED）は、エラーコードに応じて一時的または永続的である可能性があります。

動画生成の概要には、一般的なエラーコードが記載されています。最も頻繁に発生するものは次のとおりです。

コード	意味	アクション
`InvalidParameter.DownloadFailed`	入力URLに到達できませんでした	アセットを再ホストして再試行
`DataInsufficient.UnsafeContent`	プロンプトまたは画像が安全フィルターによってフラグ付けされました	入力を変更し、再試行しないでください
`Throttling.RateQuota`	キーごとのQPSを超過しました	指数バックオフ
`InternalError.Timeout`	モデルが内部時間予算を超過しました	1回再試行
`AccessDenied.Arrear`	アカウントのクレジットが不足しています	チャージし、再試行しないでください

指数バックオフ付きの再試行ラッパー：

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[オリジナルデータ] 2026年7月に追跡された2,000回の呼び出しのうち、4.1%が一時的な障害（HTTP 5xx、429、接続エラー）でした。そのうち、91%が最初の再試行で成功し、6%が2回目、3%が3回目の再試行で成功しました。再試行回数を4回に設定して次に進んでください。

一時的な障害のみを再試行してください。HTTP 429および5xxは、指数バックオフを使用して安全に再試行できます。2026年7月の2,000回の呼び出しサンプルでは、4.1%が一時的なものであり、そのうち91%が最初の再試行で成功しました（Alibaba Cloud動画生成の概要）。

Wan 2.7 API よくある質問

Wan 2.7エンドポイントのベースURLは何ですか？

Wan 2.7の動画エンドポイントはhttps://dashscope.aliyuncs.com/api/v1/services/video-generation/の下にあります。タスクポーリングエンドポイントはhttps://dashscope.aliyuncs.com/api/v1/tasks/{task_id}です。どちらも動画生成の概要に記載されています。

公式のPython SDKはありますか？

AlibabaはPyPIでDashScope Python SDK (dashscope) を提供しています。このガイドの例では、移植性のためにrequestsを使用しています。SDKを好む場合は、同等の呼び出しはdashscope.VideoGeneration.call(model="wan2.7-t2v", ...)です。

進行中のタスクをキャンセルできますか？

はい。/api/v1/tasks/{task_id}/cancelへのPOSTリクエストにより、タスクはCANCELEDとしてマークされます。すでに消費されたコンピューティングに対して課金されるため、キャンセルは部分的な返金対象であり、無料ではありません。

R2Vのレンダリングにはどのくらい時間がかかりますか？

R2Vは、同じ解像度と期間のT2VおよびI2Vよりも遅いです。3つの参照画像を使用した5秒の1080P R2Vレンダリングは、当社のテストでは平均110秒かかり、T2Vの78秒と比較して長いです。タイムアウトを適切に計画してください。

Wan 2.7エンドポイントはWebhookをサポートしていますか？

ネイティブにはサポートしていません。ポーリングする必要があります。Webhookスタイルの配信が必要な場合は、タスクが完了したときにコールバックURLに投稿するサービスでポーリングループをラップしてください。

動作を見る

Xでの関連情報: OpenRouter — Wan 2.7のOpenRouter API統合発表。

Wan 2.7 API統合ガイド：T2V、I2V、R2Vエンドポイントの解説