venice-video

Venice Video

動画は音楽の音声と同様に非同期です。稼働中のエンドポイントが4つ、廃止済みのエンドポイントが1つあります。

エンドポイント	用途
POST /video/quote	USD での料金を確認します（課金なし、ジョブなし）。アップスケールモデルを除き、API キーは不要です。
POST /video/queue	検証、課金、キューへの追加を行います。すぐに queue_id を返します。
POST /video/retrieve	ステータスをポーリングし、video/mp4 をダウンロードするか、ジョブの失敗内容を受け取ります。
POST /video/complete	完了したメディアをクリーンアップします。現在、/video/queue の queue_id は拒否されるため、代わりに retrieve で delete_media_on_completion を使用してください（ステップ 4を参照）。
POST /video/transcriptions	廃止済み — 常に 410 を返します。 下記を参照してください。

/video/queue、/video/retrieve、/video/complete では、Bearer API キーまたは x402 SIGN-IN-WITH-X ウォレットヘッダーを使用できます（venice-x402を参照）。

使用する場面

• テキストから動画、画像から動画、最初／最後のフレーム間のトランジション、参照画像から動画（R2V）、動画から動画、動画のアップスケール、または音声付き動画が必要な場合。
• 非同期実行を許容できる場合（モデル、長さ、キューの深さに応じて数秒から数分かかります。/video/retrieve は、リアルタイムの推定値として average_execution_time と execution_duration を返します）。
• ジョブを実行する前に、正確な料金を確認したい場合（/video/quote）。

対象外：既存の動画の理解や要約には、video_url コンテンツパートを指定して venice-chat を使用してください。

まずモデルを選択する

以下の各フィールドはモデル固有です。リクエストを作成する前に、GET /models?type=video でモデルの制約を確認してください（venice-modelsを参照）。

• constraints.model_type — text-to-video、image-to-video（R2V およびトランジションモデルを含む）、または video（動画から動画、モーションコントロール、アップスケール）。
• constraints.durations、aspect_ratios、resolutions — 受け付けられる正確な文字列（大文字と小文字を区別します。MiniMax H3 Max では 480P ／ 768P ／ 1080P、MiniMax H3 では 768P ／ 2K を使用します）。
• constraints.audio_configurable — この条件を満たす場合に限り、audio を送信できます。
• constraints.audio_input — この条件を満たす場合に限り、audio_url を送信できます。
• constraints.prompt_character_limit — モデル独自の上限が設定されている場合に表示されます。それ以外の場合、上限は2500文字です。

リクエストスキーマはモデルごとに厳密に定義されています。モデルがサポートしないフィールドは、無視されるのではなく 400 エラーになります（例：「This model does not support aspect_ratio」）。

ライフサイクル — 生成

1. /video/quote で価格を確認する

curl https://api.venice.ai/api/v1/video/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6-text-to-video",
    "duration": "5s",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true
  }'

レスポンス：{"quote": 0.55}（USD）。

• 必須：model。固定時間のモデルでは duration も必須です。
• resolution と aspect_ratio を省略した場合は、モデルのデフォルト値が使われます。
• 見積もりエンドポイントは、モデルが使用しないフィールド（例：audio_configurable: false のモデルに対する audio、aspect_ratios を持たないモデルに対する aspect_ratio、不明なキー）を破棄します。一方、/video/queue はそれらを拒否します。見積もりが成功しても、キューのリクエストボディが有効であるとは限りません。
• アップスケールモデル（topaz-video-upscale）：見積もりには Bearer API キー（キーがない場合は 403 となるため、x402 ウォレットでは見積もりできません。キューに直接送信し、402 の残高チェックに頼ってください）と video_url が必要です。Venice はファイルを取得して、時間、FPS、高さを検出します（読み取れない場合は 400）。duration は無視されます。キューに送信する倍率の価格を確認するには、upscale_factor（1／2／4）を指定します。resolution: "1x"／"2x"／"4x" は非推奨のエイリアスです。
• 動画から動画を生成するモデル（例：wan-2-7-video-to-video）：video_url が必須です。時間はファイルから検出されます。
• 参照動画に対応する R2V モデル（Seedance 2.x、MiniMax H3／H3 Max、Wan 3.0 R2V など）：reference_video_total_duration（すべての参照動画の合計秒数。モデルの合計上限まで。例：Seedance 2.0／H3／Wan 3.0 は 15、Seedance 2.5 は 30。上限を超えると 400）を指定してください。参照動画は課金対象のため、省略すると参照動画なしの価格が返され、見積もりが実際より低くなります。入力画像ごとに課金されるモデルでは、価格を確認するために reference_image_count（モデルの参照画像上限以下。超えると 400）を指定してください。省略した場合は、画像 1 枚分が課金されます。

2. /video/queue で送信する

curl https://api.venice.ai/api/v1/video/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6-text-to-video",
    "prompt": "Commerce being conducted in the city of Venice, Italy.",
    "negative_prompt": "low resolution, worst quality, defects",
    "duration": "5s",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true
  }'

レスポンス：{ "model": "...", "queue_id": "uuid" }。VPS 対応モデルでは download_url も含まれます。

• バリデーションと残高チェックは 200 の前に行われます。また、API キーを使用するクライアントはこの時点で課金されます（x402 ウォレットのクライアントはジョブが受理された時点で課金されます）。コンテンツ審査とプロバイダーへの送信はレスポンスの後に実行されるため、これらの失敗はここではなく /video/retrieve で報告されます。通常、失敗時には返金されます（エラーボディに credits_refunded がある場合、結果が記載されています）。ただし例外として、Runway モデル（runway-gen4-5、runway-gen4-5-text、runway-gen4-turbo）は、コンテンツポリシーによりプロバイダーがリクエストを拒否した場合も課金されます（credits_refunded: false）。
• download_url はVPS 対応モデルで返されます。現在は、*-private ID と grok-imagine-1-5-lite-text-to-video／grok-imagine-1-5-lite-image-to-video を含む、すべての Grok Imagine 動画モデルが該当します。モデル ID ではなく、キューのレスポンスに download_url が含まれているかどうかで判断してください。含まれている場合、/video/retrieve はステータスのみを JSON で返します。ステータスが COMPLETED になったら、download_url に対して（認証ヘッダーなしで）GET を実行してください。有効期間は最大 24 時間です。

3. /video/retrieve でポーリングする

curl https://api.venice.ai/api/v1/video/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan-2.6-text-to-video","queue_id":"...","delete_media_on_completion":false}' \
  --output out.mp4

ボディ：model と queue_id（どちらも必須）、任意の delete_media_on_completion（デフォルトは false）。ほかのキーは受け付けられません。

• 処理中：200 の JSON {"status":"PROCESSING","average_execution_time":145000,"execution_duration":53200}（単位は ms。average_execution_time は P80 の推定値です）。
• 完了（ほとんどのモデル）：200 のバイナリ video/mp4 ボディ。
• 完了（VPS 対応モデル）：200 の JSON {"status":"COMPLETED", ...}。キューのレスポンスに含まれる download_url を取得してください。
• 失敗：200 以外の JSON エラー（エラーを参照）。終端エラー（送信の失敗、コンテンツポリシーによる拒否、プロバイダー側の失敗、メディアの有効期限切れ）はジョブに記録されるため、同じ queue_id を再度ポーリングすると同じエラーが返されます。429 は一時的なエラーです。間隔を空けて再度ポーリングしてください。
• delete_media_on_completion: true を指定すると、出力が返された後に保存済みの出力を削除するよう要求できます。これにより、別途 /video/complete を呼び出す必要がなくなります。
• queue_id はキーのユーザーに紐づき、有効期限は 24 時間です。不明な ID または期限切れの ID には、400 "Request ID is invalid." が返されます。

4. /video/complete でクリーンアップする

curl https://api.venice.ai/api/v1/video/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"...","queue_id":"..."}'

本文：model と queue_id のみです。レスポンス：200 {"success": true}、または削除が実行されなかった場合は {"success": false} です。現在、/video/queue が発行した queue_id に対して 400 "Request ID is invalid." を返すため、これに頼らないでください。delete_media_on_completion: true を指定してポーリングすることでクリーンアップしてください。

/video/queue のリクエストフィールド

フィールド	型	備考
model	string	必須です。
prompt	string	必須です（空白以外の文字が1文字以上）。ただし、アップスケールモデルと minimax-h3-max-multi-angle は除きます。モデルごとの最大長は、デフォルトで2500文字です。それ以外の場合は constraints.prompt_character_limit が適用されます（Runwayの1000文字からWan 3.0の20000文字まで）。
negative_prompt	string	prompt と同じ最大長です。ネガティブプロンプトに対応していないモデルでは無視されます。
duration	string	constraints.durations の値が必須です（1s～30s）。アップスケールモデルと動画から動画を生成するモデルでは、省略するとサーバーがソースの長さを検出します。または、"12.5" のように秒数を文字列で送信できます（≤ 300）。文字列リテラルの "Auto" は拒否されます。seedance-2-5-reference-to-video-basic では、"-1" / "auto"（ソースクリップに合わせる）も指定できます。
aspect_ratio	string	モデルの aspect_ratios が空でない場合は 必須 です。リストが空の場合は拒否されます（画像入力型のモデルでは入力画像から比率が決まります）。Seedance 2.0 R2V -basic モデル（standard / fast / mini）と seedance-2-5-reference-to-video-basic では、adaptive / auto（ソースクリップに合わせる）も指定できます。
resolution	string	constraints.resolutions の値を指定します。省略するとモデルのデフォルト値が使われます。モデルに解像度の指定項目がない場合やアップスケールモデルの場合は拒否されます。アップスケールモデルでは upscale_factor を使用してください。
upscale_factor	整数 1 / 2 / 4	アップスケールモデル専用です。1 は画質向上のみを意味します。省略するとモデルのデフォルト値が使われます（topaz-video-upscale では 2）。
audio	bool	audio_configurable: true の場合のみ指定できます。デフォルトは true です。
image_url	URL または data: URL	画像から動画を生成する場合の開始フレームです。テキストから動画を生成するモデルでは拒否されます。
end_image_url	URL または data: URL	対応モデルで指定する終了フレームです（非対応の場合は 400）。トランジションモデル（pixverse-c1-transition、pixverse-v5.6-transition、flux-3-first-last-frame-to-video）では 必須 です。
audio_url	URL または data: URL	audio_input: true のモデルで使用します。WAV / MP3形式で、通常は30秒以下かつ15 MB以下です。Seedance 2.x R2VとMiniMax H3 R2Vでは、追加の参照音声として扱われます（クリップごとの上限は同じです）。
video_url	URL または data: URL	アップスケールモデルと動画から動画を生成するモデルでは必須です。MP4、MOV、WebMなど一般的なコンテナ形式を指定できます。
reference_image_urls[]	URL	R2Vのキャラクター / スタイル参照画像です。モデルごとの上限（指定がない場合は4）については、上限を参照してください。
reference_video_urls[]	URL	R2Vの動き / カメラ / スタイルの参照動画（.mp4 / .mov）です。Seedanceの編集 / 延長ではソースクリップとしても使用します。
reference_audio_urls[]	URL	音声、ナレーション、または効果音の参照素材（.wav / .mp3）です。Seedanceでは、プロンプト内で <Audio 1>、<Audio 2> のように指定してください。少なくとも1つの画像または動画の参照素材と組み合わせる必要があります。音声のみの場合は 400 になります。
reference_document_urls[]	URL、最大1件	wan-3-0-reference-to-video 専用です。ドキュメント（pdf、docx、pptx、xlsx、txt、md、…、最大100 MB）または公開ウェブページを指定します。
elements[]	配列、最大4件	Kling O3 R2Vモデルおよび kling-v3-4k-reference-to-video 用です（後者では image_url も必須です）。各要素には frontal_image_url（および最大3件の reference_image_urls）または video_url が必要です。プロンプト内では @Element1、@Element2 のように指定します。
scene_image_urls[]	URL、最大4件	elements と同じモデルで使用するシーン / スタイル参照画像です。@Image1、@Image2 のように指定します。
camera_trajectory[]	配列、2～12件	minimax-h3-max-multi-angle 専用です。レシピを参照してください。
omni_reference_task_type	auto / reference / edit / extend	seedance-2-5-reference-to-video-basic 専用です（editing / extension も別名として使用できます）。edit / extend を指定する場合は reference_video_urls が必須です。省略時に reference_video_urls が指定されていると、Veniceがプロンプトから推測します。
bitrate_mode	standard / high	Seedance 2.0 / 2.5モデル（1.5を除く）で使用します。デフォルトは standard です。価格は変わりません。
image_references[]	{image_url, type?: subject|background, ref_name?}	型付き参照（例：pixverse-c1-reference-to-video）です。@ref_name のように指定します。
video_references[]	{video_url, ref_name?, audio_url?}	per_reference_audio: true のモデル（例：wan-2-7-reference-to-video）で使用します。エンティティごとの音声を任意で指定して、参照クリップを登録します。
voice_id	string	grok-imagine-1-5-reference-to-video-private 用の、Grokのプリセット音声IDです（例：eve。無効なIDを指定すると、400 の応答で使用可能な値が示されます）。アップロードした音声はサポートされていません。
consents	object	Seedanceの顔に関する同意確認です。注意点を参照してください。/models に掲載されているモデルでは使用しません。
anon_user_id	string、最大128文字	エンドユーザー識別子（任意）です。印字可能なASCII文字を使用し、|| は含めないでください。
すべてのメディア URL は data: URL、または公開ホスト上の http(s):// URL である必要があります。プライベート、ループバック、リンクローカル、クラウドメタデータのアドレスは拒否され、400 が返されます。bitrate_mode、image_references、video_references、voice_id、anon_user_id は受け付けられますが、公開されている OpenAPI スキーマには記載されていません。

参照メディアの上限

上限はモデルごとに異なります。一般的な R2V ファミリーの現在の上限は次のとおりです（2026-09-30 時点）。

モデルファミリー	参照画像	参照動画（クリップごと／合計）	参照音声（クリップごと／合計）
seedance-2-0-*-reference-to-video-basic（fast／mini を含む）	9	3（2–15 s、≤ 50 MB / 15 s）	3（2–15 s、≤ 15 MB / 15 s）
seedance-2-5-reference-to-video-basic	30	10（2–30 s、≤ 50 MB / 30 s）	10（2–30 s、≤ 15 MB / 30 s）
seedance-2-5-us-reference-to-video-private	30	10（2–30 s、≤ 200 MB / 30 s）	10（2–30 s、≤ 15 MB / 30 s）
wan-3-0-*reference-to-video	10	5（1–15 s、≤ 100 MB / 15 s）	5（1–15 s、≤ 15 MB / 15 s）
minimax-h3-reference-to-video、minimax-h3-max-reference-to-video	9	3（2–15 s、≤ 50 MB / 15 s）	3（2–15 s、≤ 15 MB / 15 s；audio_url は 3 件に数えられます）
minimax-h3-enhanced-reference-to-video	9	—	3（上記と同じ）
kling-o3-{standard,pro}-reference-to-video、kling-v3-4k-reference-to-video	4	—	—
kling-o3-4k-reference-to-video、pixverse-c1-reference-to-video、grok-imagine-reference-to-video-private、grok-imagine-1-5-reference-to-video-private	7	—	—
gemini-omni-flash-1-1-reference-to-video	10	—	—
gemini-omni-flash-reference-to-video	3	—	—

上限を超える配列は 400 になります。モデルに constraints.reference_image_min_aspect_ratio / reference_image_max_aspect_ratio（Seedance と MiniMax H3 では 0.4 と 2.5）が指定されている場合、この幅／高さの比率を外れる画像は拒否されます。reference_image_min_short_side_pixels を下回る画像は自動的にアップスケールされます。

一般的なレシピ

テキスト → 音声付き動画

{
  "model": "wan-2.6-text-to-video",
  "prompt": "A golden retriever chasing a frisbee in slow motion at sunset.",
  "duration": "10s",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "audio": true
}

画像 → 動画

{
  "model": "wan-2.6-image-to-video",
  "prompt": "Camera slowly zooms out, revealing the cityscape.",
  "image_url": "https://example.com/cityscape.jpg",
  "duration": "5s",
  "resolution": "720p"
}

aspect_ratio は指定しないでください。このモデルの aspect_ratios リストは空のため、比率は画像に従い、指定すると 400 になります。

動画のアップスケール

{
  "model": "topaz-video-upscale",
  "video_url": "https://example.com/input.mp4",
  "upscale_factor": 2
}

prompt と duration は不要です（duration はファイルから検出されます）。resolution は拒否されます。ソースの長さは最大 300 s です。

複数要素の一貫性（Kling O3 R2V）

{
  "model": "kling-o3-pro-reference-to-video",
  "prompt": "@Element1 walks toward @Element2 against @Image1.",
  "duration": "5s",
  "aspect_ratio": "16:9",
  "elements": [
    { "frontal_image_url": "https://example.com/char1.png", "reference_image_urls": ["https://example.com/alt1.png"] },
    { "frontal_image_url": "https://example.com/char2.png" }
  ],
  "scene_image_urls": ["https://example.com/street-scene.jpg"]
}

Seedance 2.5 の編集（ソースクリップに合わせる）

{
  "model": "seedance-2-5-reference-to-video-basic",
  "prompt": "Strictly edit <Video 1>: make it snow, keep everything else unchanged.",
  "reference_video_urls": ["https://example.com/source.mp4"],
  "omni_reference_task_type": "edit",
  "duration": "auto",
  "aspect_ratio": "adaptive",
  "resolution": "720p"
}

duration: "auto" / "-1" を使うには、4–30 s のソースクリップが必要です（それ以外は 400）。ソースに合わせた引用の場合は、同じ duration / aspect_ratio に reference_video_total_duration を加えて指定してください（必須です。指定しないと 400 になります）。

H3 Max Multi-Angle（カメラの周回）

{
  "model": "minimax-h3-max-multi-angle",
  "image_url": "https://example.com/scene.jpg",
  "duration": "5s",
  "resolution": "768P",
  "camera_trajectory": [
    { "time": 0, "azimuth": 0, "elevation": 0, "distance": 1 },
    { "time": 1, "azimuth": 45, "elevation": 10, "distance": 1 }
  ]
}

camera_trajectory には 2–12 個のキーフレームを指定し、それぞれに time、azimuth、elevation、distance のみを含めてください（余分なキーがあると 400 になります）。time は 0–1 の範囲で、値は厳密に増加する必要があります。azimuth は符号付きの角度です（移動量の絶対値の合計は 32 回転以下）。elevation は −90…90、distance は初期カメラ位置に対して 0 より大きい値です（1 = 変更なし）。指定しない場合、モデルが経路を選択します。image_url は必須、prompt は任意で、アスペクト比は画像に従います（aspect_ratio を指定すると 400 になります）。

/video/transcriptions（廃止済み）

POST /video/transcriptions は削除されました。認証済みかどうかにかかわらず、すべてのリクエストに対して、ヘッダー Deprecation: true および Link: </api/v1/chat/completions>; rel="successor-version", </api/v1/models>; rel="describedby" と、置き換え先を示す error メッセージを含む 410 が返されます（IP ごとに 1 分あたり 60 件を超えるリクエストを送信した場合は、同じメッセージの先頭に Rate limit exceeded. が付いた 429 が返されます）。

置き換え先：動画を分析、要約したり、動画について質問したりする場合（プロバイダーが対応していれば YouTube URL も含む）は、model_spec.capabilities.supportsVideoInput が true のモデルに対し、{"type":"video_url","video_url":{"url":"..."}} コンテンツパートを指定して POST /chat/completions を呼び出してください。1 リクエストにつき最大 3 本の動画を指定できます。venice-chat を参照してください。音声ファイルの逐語的な文字起こしには、venice-audio-transcription を使用してください。

完全なポーリングループ

// Pass download_url from the queue response whenever it is present.
async function waitForVideo(model: string, queueId: string, downloadUrl?: string) {
  while (true) {
    const res = await fetch(`${base}/video/retrieve`, {
      method: 'POST', headers,
      body: JSON.stringify({ model, queue_id: queueId, delete_media_on_completion: true }),
    })
    const ct = res.headers.get('content-type') ?? ''
    if (res.ok && ct.startsWith('video/')) {
      return Buffer.from(await res.arrayBuffer())
    }
    const body = await res.json()
    if (!res.ok) {
      // Job failures are replayed here (e.g. 422 with credits_refunded). 429 / 502 / 503 are transient.
      if ([429, 502, 503].includes(res.status)) { await new Promise(r => setTimeout(r, 15000)); continue }
      throw new Error(`video failed (${res.status}): ${JSON.stringify(body)}`)
    }
    if (body.status === 'COMPLETED' && downloadUrl) {
      const v = await fetch(downloadUrl)
      return Buffer.from(await v.arrayBuffer())
    }
    if (body.status === 'COMPLETED') throw new Error('COMPLETED without download_url: pass download_url from the queue response')
    if (body.status !== 'PROCESSING') throw new Error(`unexpected ${body.status}`)
    await new Promise(r => setTimeout(r, 5000))
  }
}

エラー

コード	意味
400	無効なパラメーター（このモデルでサポートされていないフィールド、不正な列挙値、prompt／image_url／video_url の欠落、配列の上限超過、ブロックされている、または読み取れないメディア URL、破損した画像）。/video/retrieve では、不明または期限切れの queue_id に対して "Request ID is invalid." が返されます。/video/complete では、現在、/video/queue が発行したすべての queue_id に対して同じメッセージが返されます。代わりに delete_media_on_completion: true を指定してクリーンアップしてください（手順 4 を参照）。
401	認証に失敗しました。
402	残高不足、または API キーの利用上限超過（課金前に /video/queue で確認されます）。ウォレット残高が最低額の $0.10 を下回る場合は、x402 の PAYMENT_REQUIRED 本文と PAYMENT-REQUIRED ヘッダーが返されます。残高が最低額を上回っていても、このジョブの見積額を下回る場合は、ヘッダーなしで通常の {"error":"Insufficient USD or Diem balance…"} 本文が返されます。/x402/top-up でチャージしてから再試行してください。
403	お住まいの地域でモデルを利用できない、API キーのモデルプライバシー設定で許可されていない、または認証されていないアップスケール見積もりです。
404	モデルが見つかりません（すべての動画エンドポイント）。/video/retrieve では、メディアの有効期限切れ、またはすでに削除済みです。
409	/video/queue のみ。非公開の顔対応 Seedance モデルでは、{"error":{"code":"needs_consent",...},"consent_flow":"seedance","face_media_roles":[...],"consent":{"consent_version","policy_text"},"docs_url"} が返されます。
410	/video/transcriptions（廃止済み）。
413	ペイロードが大きすぎます。data: URL にインラインで埋め込むのではなく、メディアを縮小するかホストしてください。
422	コンテンツポリシー違反、またはプロバイダー側の失敗です。審査はジョブの受け付け後に行われるため、通常は /video/retrieve で次のいずれかが返されます。プロバイダーによる拒否 {"error":{"message","type":"provider_content_policy","credits_refunded",...}}（recommended_model が含まれる場合があります）、またはプロバイダー側の失敗 {"error","credits_refunded"}（利用可能な場合は hint も含まれます）。
429	レート制限（/video/queue は 40 リクエスト／分、/video/retrieve は 120 リクエスト／分、認証済みアップスケール見積もりは 40 リクエスト／分。いずれもユーザーごと）、またはモデルが過負荷です。
500	推論または内部エラーです。/video/retrieve で再度返された 500 は、その queue_id に対して終端エラーです。再送信してください（ブロックされた可能性がある場合は、プロンプト／メディアを修正してから再送信してください）。
502	/video/retrieve のみ。動画の生成は完了しましたが、プロバイダーから取得できませんでした。ジョブには記録されません。待機時間を延ばしてから、再度ポーリングしてください。
503	モデルがオフライン、または容量上限に達しています。後でもう一度お試しください。

本文の形式と再試行の方法については、venice-errors を参照してください。

注意点

• 見積もりの検証はキューより緩やかです。 見積もりでは未対応のフィールドが破棄されますが、キューではそれらに対して 400 が返されます。成功した見積もりではなく、/models の制約に基づいてキューのリクエスト本文を作成してください。
• モデルにアスペクト比が列挙されている場合、/video/queue では aspect_ratio が必須です。アスペクト比が列挙されていない場合は禁止されています。
• キューの成功 ≠ 生成の成功です。 モデレーションやプロバイダーのエラーは /video/retrieve で返され、該当する場合は返金状況が credits_refunded に示されます。200 以外の retrieve レスポンスは必ず処理してください。Runway のコンテンツポリシーによる拒否は返金されません。
• download_url が返されるのは VPS 対応モデル（Grok Imagine モデル）のみです。ID ではなく、このフィールドの有無を確認してください。どちらの方法にも対応してください。/video/retrieve からバイナリを取得する方法と、COMPLETED の後に download_url へ GET リクエストを送る方法です。有効期限は 24 h 以内のため、速やかにダウンロードしてください。
• アップスケールモデルでは resolution ではなく upscale_factor を使用してください（キューでは resolution が拒否されます。見積もりでは、非推奨のエイリアスとして 1x ／ 2x ／ 4x のみ受け付けられます）。
• GET /models では、ほとんどのアップスケールモデルと動画間変換モデルの duration が "Auto" と表示されますが、/video/queue はリテラルの "Auto" を拒否します。代わりに duration を省略してください。
• Seedance の命名規則：列挙されている Seedance の ID は -basic で終わります（例：seedance-2-0-text-to-video-basic）。また、別系統として seedance-2-5-us-*-private ファミリーがあります。どちらも consents ／ needs_consent は使用せず、識別可能な人物が写っているメディアは上流で拒否される場合があります。顔の同意フロー（confirmed_terms_and_privacy、confirmed_legal_right、confirmed_screening_acknowledged がすべて true の consents.seedance を設定し、409 の後に再送信する方法）が適用されるのは、/models に返されない、未列挙の Seedance ID のみです。
• Seedance のソースに一致する値：-basic の Seedance 2.0 ／ 2.5 R2V モデルでは aspect_ratio: "adaptive" ／ "auto" が動作し、duration: "-1" ／ "auto" は seedance-2-5-reference-to-video-basic でのみ動作します。どちらもキューでは reference_video_urls、見積もりでは reference_video_total_duration が必要です。seedance-2-5-us-*-private モデルはこれらに対応していません（adaptive は 400 になり、auto は通常のアスペクト比オプションとして扱われます）。それ以外では、"auto" も通常のアスペクト比オプションです（例：Flux 3）。
• MiniMax H3 および H3 Max の動画間参照モデルでは、参照メディアと組み合わせた image_url ／ end_image_url が拒否されます。また、audio_url は参照音声の上限数に含まれます。
• data: URL はペイロードサイズに含まれます。サイズの大きな base64 動画は 413 の原因になる場合があるため、ホスト済み URL を優先してください。
• 料金は動的に変化します（解像度、長さ、音声、参照メディア、プロモーションなど）。必ず見積もりを取得し、料金をハードコードしないでください。