Alibaba Wan 3.0 Video API:次世代動画生成の始め方
対象モデル:
wan3.0-video(任意の姉妹 ID:wan3.0-video-prime)
推論エンドポイント:https://api.toapis.com/v1/videos/generations
関連: Wan 3.0 Prime 対 Wan 2.6 Flash · Kling Video O1 長尺連続性 · Wan 3.0 リファレンス · wan3.0-video モデルガイド · wan3.0-video-prime モデルガイド
1. TL;DR と性能概要
- まずカタログを確認する: 企画ドラフトはときどき
wan-3-primeと書きます。これは文書化された公開 ID ではありません。2026-11-20 に公式 Wan 3.0 生成リファレンス(HTTP 200)を確認したところ、wan3.0-videoとwan3.0-video-primeが挙げられていました。両モデルはそのページの同じ All-in-One API を使います。独立した Prime 専用ドキュメントパスはありませんでした。 - 契約:
POST /v1/videos/generationsに非同期送信し、GET /v1/videos/generations/{id}をcompletedまたはfailedまでポーリングします。通常タスクはGET /v1/tasks/{id}でも照会できます。公式例はhttps://toapis.com(中国本土はhttps://toapis.cn)です。本シリーズの他ガイドはhttps://api.toapis.comを使います。オリジンは 1 つに揃えてください。 - 1 つのスキーマ上の複数モード: テキストから動画、先頭フレームまたは先頭・末尾フレーム制御、参照画像・動画・音声の併用生成、単一ファイルまたは公開 Web ページ、参照クリップからの編集または延長です。先頭・末尾フレームモードと参照アセットモードは互排他です。
- メディア: 公開の
http://またはhttps://URL だけを送ってください。ローカルファイルは先にアップロードし、返却 URL を使います。base64 やローカルパスは送らないでください。promptとメディアアセットの少なくとも一方が必要です。 - 捨てるべき未検証の主張: 5 秒あたり
$0.150といったドラフト単価は、現行の ToAPIs 文書ではありません。アカウントで現行レートとチャネル対応を確認してください。
2. 公式 Wan 3.0 ID、パラメータ、組み合わせ規則
model フィールドには 2 つの公開モデル名のいずれかを使います。ドラフト別名に置き換えたり、Prime モードフラグを発明したりしないでください。
| カタログ ID | 本ガイドでの役割 | 文書化されたジョブ |
|---|---|---|
wan3.0-video | デフォルト / 標準 All-in-One ID | テキストから動画、先頭・末尾フレーム、マルチモーダル参照、ファイルまたはリンク、編集と延長 |
wan3.0-video-prime | 同じスキーマ上の Prime 姉妹 ID | wan3.0-video と同じリクエスト構造。カタログにあり、Prime SKU を意図するときだけ選ぶ |
wan2.6 | 関連する以前の Wan ID。Wan 2.6 生成リファレンス を参照 | テキストから動画、画像から動画、参照動画。パラメータマップが異なる(480p なし、尺は 5/10/15) |
主なリクエストフィールド(両 Wan 3.0 ID で共通):
| フィールド | 文書化された値 | 注記 |
|---|---|---|
prompt | 文字列 | 内容、動き、カメラ、音。prompt とメディアアセットの少なくとも一方が必要。配列順で「image 1」「video 1」「audio 1」と参照 |
duration | 2〜30 の整数、または -1 | デフォルト 5。-1 はスマート尺で、モデルが長さを決める |
ratio | adaptive(デフォルト)、16:9、9:16、1:1、4:3、3:4 | aspect_ratio は互換エイリアス。両方は送らない |
resolution | 480p、720p、1080p(デフォルト 1080p) | この契約では 3 段階すべてが文書化されている |
audio | ブール、デフォルト true | デフォルトで音声あり |
watermark | ブール、デフォルト false | デフォルトオフ |
prompt_extend | ブール、デフォルト true | LLM による書き直しは短いプロンプトを改善し、レイテンシも増やす。原文のまま使うなら false |
seed | 任意整数 | 同じパラメータとシードで近い結果を再現しやすくする |
image_with_roles | {url, role} 配列 | role は first_frame または last_frame。各最大 1。last_frame には first_frame が必要 |
reference_images | 最大 10 の公開画像 URL | 先頭・末尾フレームと混ぜられない |
video_list | 最大 5 本、合計尺 ≤15 秒 | 各項目は {"video_url": "..."} |
audio_with_roles | 最大 5 本、合計 ≤15 秒 | 各項目は {url, role: "reference_audio"} |
metadata.media | file 1 つか link 1 つ | {type, url}。ファイルとリンクは併用できず、先頭・末尾フレームモードとも混ぜられない |
disable_nsfw | ブール、デフォルト true | 上流には転送されない ToAPIs プラットフォームパラメータ。明示的な JSON false だけが、アカウントと販売地域の条件を満たすときにフォールバックを有効化。中国本土では常に無効 |
公式表のアセット組み合わせ規則:
| リクエスト内容 | 対応 | 注記 |
|---|---|---|
| プロンプトのみ | はい | テキストから動画 |
| 先頭フレームのみ | はい | 先頭フレーム制御 |
| 先頭と末尾フレーム | はい | 末尾フレームは単独では使えない |
| 参照画像と参照動画 | はい | 参照音声とも組み合わせ可能 |
| 先頭フレームと参照動画 | いいえ | 先頭・末尾フレームモードと参照アセットモードは互排他 |
| ファイルと Web リンク | いいえ | 互排他 |
「Wan 3.0 cannot mix first/last frames with reference assets/files/web pages in the same request.」のようなメッセージが返ったら、どちらか一方の系統を外して再送してください。
動画編集は別エンドポイントではなく、プロンプトで分類される経路です。編集意図(たとえば “edit the video”、“remove”、“replace”)を含め、参照クリップを渡します。これらのジョブは ratio を adaptive、duration を -1 にし、入力は 4〜30 秒である必要があります。延長は “extend” や “continue” などの表現を使い、duration を -1、またはソース尺+延長(合計 ≤ 30 秒)にします。

図 1: 文書化された Wan 3.0 ペイロードを POST /v1/videos/generations に送り、同じタスク id をポーリングし、status が completed になってから result.data[0].url を読む。
Wan 2.6 Flash との能力・コスト比較は Wan 3.0 Prime 対 Wan 2.6 Flash を見てください。別ファミリーで 3〜10 秒ウィンドウの長尺連続性は Kling Video O1 ガイド です。
3. 本番実装: cURL と Python
本シリーズの国際向け例は https://api.toapis.com を使います。公式ドキュメントは中国本土の利用者に https://toapis.cn を指定しています。環境ごとにオリジンは 1 つに揃えます。
ステップ 1: テキストから動画を cURL で送る
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
"duration": 5,
"ratio": "16:9",
"resolution": "1080p",
"audio": true,
"watermark": false
}'
先頭・末尾フレームのリクエストは image_with_roles を使い、参照メディア、ファイル、リンクを含めてはいけません。
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
"duration": 8,
"ratio": "adaptive",
"resolution": "1080p",
"image_with_roles": [
{"url": "https://example.com/first-frame.png", "role": "first_frame"},
{"url": "https://example.com/last-frame.png", "role": "last_frame"}
]
}'
ステップ 2: Python ヘルパーとポーラー
このスニペットは文書化されたタスク状態パスと、queued / in_progress / completed / failed に従います。出荷前に、アカウント向け API リファレンスで id、result.data[0].url、エンベロープを確認してください。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_IDS = {"wan3.0-video", "wan3.0-video-prime"}
RATIOS = {"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4"}
RESOLUTIONS = {"480p", "720p", "1080p"}
def dispatch_wan30(
prompt: str | None = None,
*,
model: str = "wan3.0-video",
duration: int = 5,
ratio: str = "16:9",
resolution: str = "1080p",
audio: bool = True,
watermark: bool = False,
prompt_extend: bool | None = None,
image_with_roles: list[dict] | None = None,
reference_images: list[str] | None = None,
video_list: list[dict] | None = None,
audio_with_roles: list[dict] | None = None,
media: list[dict] | None = None,
) -> str:
if model not in DOCUMENTED_IDS:
raise ValueError("Send wan3.0-video or wan3.0-video-prime; wan-3-prime is not a documented public ID")
if duration != -1 and duration not in range(2, 31):
raise ValueError("duration must be 2–30 or -1")
if ratio not in RATIOS:
raise ValueError("unsupported ratio")
if resolution not in RESOLUTIONS:
raise ValueError("resolution must be 480p, 720p, or 1080p")
roles = [item.get("role") for item in (image_with_roles or [])]
if "last_frame" in roles and "first_frame" not in roles:
raise ValueError("last_frame requires first_frame")
has_frames = bool(image_with_roles)
has_refs = any([reference_images, video_list, audio_with_roles, media])
if has_frames and has_refs:
raise ValueError("first/last-frame mode cannot mix with reference assets, files, or links")
if media and len(media) > 1:
raise ValueError("a single request accepts at most one file or one web page")
if media and len({item.get("type") for item in media}) > 1:
raise ValueError("file and link cannot be used together")
if not prompt and not has_frames and not has_refs:
raise ValueError("provide a prompt or at least one media asset")
if reference_images and len(reference_images) > 10:
raise ValueError("reference_images is documented as at most 10")
if video_list and len(video_list) > 5:
raise ValueError("video_list is documented as at most 5 clips")
if audio_with_roles and len(audio_with_roles) > 5:
raise ValueError("audio_with_roles is documented as at most 5 clips")
payload: dict = {
"model": model,
"duration": duration,
"ratio": ratio,
"resolution": resolution,
"audio": audio,
"watermark": watermark,
}
if prompt:
payload["prompt"] = prompt
if prompt_extend is not None:
payload["prompt_extend"] = prompt_extend
if image_with_roles:
payload["image_with_roles"] = image_with_roles
if reference_images:
payload["reference_images"] = reference_images
if video_list:
payload["video_list"] = video_list
if audio_with_roles:
payload["audio_with_roles"] = audio_with_roles
if media:
payload["metadata"] = {"media": media}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 900) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_wan30(
"An orange cat running through the streets of Tokyo after rain, cinematic camera work",
duration=5,
ratio="16:9",
resolution="1080p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
パラメータ変更と文言変更を区別できるよう、プロンプトテンプレートの版をタスク記録の横に保存してください。expires_at より前にダウンロードします。ステータスリファレンスは 30 日の保持期間を文書化しています。prompt_extend(デフォルト)を有効にすると、短いプロンプトで追加レイテンシが起き得ます。公式ページはこれを定性的に述べ、実測遅延は公開していません。
4. エラー処理とステータス行列
下表は診断の出発点であり、ToAPIs のエラーコードと完全に一致することを保証しません。HTTP 照会が成功しても、タスク status を読む必要があります。リクエストエラーと status: failed の理由(content_policy_rejected、insufficient_user_balance、generation_timeout、video_edit_parameters_required など)は エラーリファレンス を見てください。
| HTTP またはタスク状態 | よくある分類 | 推奨アクション |
|---|---|---|
400 | 不正フィールド、先頭・末尾フレームと参照アセットの混在、ratio と aspect_ratio の併用、またはファイルとリンクの併用 | wan3.0-video または wan3.0-video-prime を確認し、排他な一方を外し、公開 URL だけを使う |
401 | API キー欠落または無効 | ToAPIs ダッシュボードでキーをローテーションし、Authorization: Bearer ヘッダを確認 |
429 | レートまたは同時実行制限 | Retry-After があれば遵守。ジッタ付きバックオフ。安全なときだけ再試行 |
5xx またはクライアントタイムアウト | ゲートウェイまたは上流の一時障害 | 再送する前に既存のタスク id を照会 |
status: queued または in_progress | エラーではない | 待って再ポーリング。prompt_extend はレイテンシを増やすことがある |
status: failed で video_edit_parameters_required | 編集制約を満たしていない | ratio を adaptive、duration を -1 にし、4〜30 秒のソースを使う |
status: failed(その他) | 生成は成功していない | error.code と error.message(あれば error.reason)を読む。ポリシー拒否のペイロードを変えずに再送しない |
5. 料金と FinOps
Wan 3.0 生成リファレンスはドル表もクレジット表も公開していません。2026-11-20 取得のモデルガイドは、wan3.0-video の料金参考を 26.3 credits / 秒、wan3.0-video-prime を 41.14 credits / 秒 と示し、最終課金は現行アカウント見積もりと現行の尺・解像度規則に従うと述べていました。これらのクレジット数字はスナップショットであり、すべての解像度やモードの契約ではありません。クレジットを自分で通貨換算せず、企画ドラフトのドル単価も再利用しないでください。
- 中程度の尺の
wan3.0-videoから始める(例: 5 秒)。プロンプトとアセットの組み合わせが安定してから、解像度を上げたり Prime に切り替えたりします。 - スマート尺(
-1)とprompt_extendは、モデルが行う仕事を変えます。 文書化された能力であり、固定のジョブ単価やレイテンシを仮定する理由にはなりません。 - 表示価格はチャネル保証ではありません。 バッチを見積もる前に、
GET /v1/models?type=videoとアカウントカタログで ID と現行見積もりを確認してください。
6. よくある質問
frontmatter の FAQ を参照してください。要約: wan3.0-video または wan3.0-video-prime を送り、wan-3-prime は送らない。先頭・末尾フレームは参照アセットと混ぜられない。尺は 2〜30 秒または -1。編集には ratio=adaptive と duration=-1 が必要。generations の状態パスを必ずポーリングし、タスク id を保存する。
7. アクションチェックリスト
- ToAPIs Developer Portal でキーを作成する。
-
GET /v1/models?type=videoでキーにwan3.0-video(必要ならwan3.0-video-primeも)が見えることを確認する。wan-3-primeは送らない。 -
duration: 5、ratio: "16:9"、resolution: "1080p"で cURL スニペットをスモークテストする。 - 期限付きで
GET /v1/videos/generations/{id}をポーリングし、expires_atより前に結果をダウンロードする。 - 次の一歩: 文書化された能力とコスト比較は Wan 3.0 Prime 対 Wan 2.6 Flash、現行カタログは wan3.0-video モデルガイド。







