動画生成タスクの作成

共通情報

• Base URL：https://api.routeapi.ai
• 認証：Authorization: Bearer $ROUTEAPI_KEY。sk- で始まる API Key を使用します（コンソールの API Keys ページで作成）。rat_ で始まる管理キーはモデルを呼び出せません。
• エラー形式：ルーティングされると、タスクエンドポイントは {"code": "...", "message": "...", "data": null} で応答します。ルーティング前に拒否されたリクエスト（API Key の欠落・無効、IP 制限、グループまたはモデルへのアクセス権なし）は標準の {"error": {"message": "...", "type": "error", "code": "..."}} 本文を使用します。ステータスコードの意味はよくあるエラーを参照してください。

RouteAPI の動画生成は 非同期タスク API です。リクエストを送信して task_id を受け取り、そのタスクが終了状態に達するまでポーリングし、その後で動画をダウンロードします。プラットフォーム上のすべての動画モデル — Seedance、Sora、Veo、Wan、Kling、Hailuo、Vidu など — は同じエンドポイントから呼び出されます。RouteAPI がリクエストを、選択された上流が期待する形式に変換するためです。

動画モデルは GET /v1/models に現れます。OpenAI 動画形式で提供されるチャネルのモデルでは supported_endpoint_types に openai-video が表示され、コンソールのモデルページでモデルごとに設定することもできます。いずれの場合もモデル ID はこの一覧から取得してください（モデルを参照）。モデル固有のパラメータはベンダーごとに説明しています。Seedance、Hailuo、Wan。同じ API の OpenAI/Sora 方言は OpenAI 動画形式に記載しています。

エンドポイント

メソッド	パス	用途	記載ページ
POST	/v1/video/generations	生成タスクを送信する	このページ
GET	/v1/video/generations/{task_id}	タスクレコードを読む	動画タスクの取得
POST	/v1/videos	生成タスクを送信する（OpenAI 方言）	OpenAI 動画形式
GET	/v1/videos/{task_id}	タスクを OpenAI video オブジェクトとして読む	OpenAI 動画形式
POST	/v1/videos/{video_id}/remix	既存の動画から派生したタスクを作成する	OpenAI 動画形式
GET	/v1/videos/{task_id}/content	完成した動画のバイト列をダウンロードする	動画タスクの取得

POST /v1/video/generations と POST /v1/videos は同じタスク操作への 2 つのパスで、リクエストとレスポンスの方言が異なります。送信時のレスポンスはいずれも OpenAI の video オブジェクトです。GET エンドポイントは異なるため（タスクレコードと video オブジェクト）、それぞれの送信パスに対応する GET を組み合わせてください。

タスクの実行フロー

1. 送信 — プロンプトとモデルを POST /v1/video/generations（または POST /v1/videos）に送信し、返された task_id を保存します。この時点で見積もりコストが残高から予約されます。
2. ポーリング — 対応する GET エンドポイントを 10〜15 秒ごとに呼び出します。生成には通常 1 分から数分かかり、解像度が高く長さが長いほど時間がかかります。
3. 完了 — ステータスが成功を報告したら、動画をダウンロードするか URL を読み取ります。タスクが失敗した場合、または終了状態に達しなかった場合、予約された金額は返金されます。

ノート

RouteAPI はバックグラウンドでおよそ 15 秒ごとに上流プロバイダをポーリングするため、あなた自身のポーリングはタスクレコードを読むだけです。終了状態に達しなかったタスクは、プラットフォームのタスクタイムアウト（デフォルトは 24 時間）後に失敗とされ返金されるため、永遠にリトライする必要はありません。

タスクを送信する

POST /v1/video/generations

リクエストフィールド

どの動画モデルもこの共通のエンベロープを受け付けます。モデル固有のオプションは metadata に入れます。各アダプタが実際に読むキーはベンダーページに記載しています。

フィールド	型	必須	説明
model	string	はい	GET /v1/models のモデル ID
prompt	string	はい	テキストプロンプト。欠落、空、または空白のみの場合 400 で拒否されます
image	string	いいえ	単一の画像（URL または Base64/data URI）。images の先頭要素として扱われます
images	string[]	いいえ	参照画像／先頭フレーム画像。意味はモデルによって異なります
size	string	いいえ	1280x720 や 720p などのサイズ／解像度ヒント。モデルによって異なります
duration	integer	いいえ	秒単位の長さ。RouteAPI は負の値と 3600 を超える値を拒否します
seconds	string	いいえ	長さの旧来の文字列表現。読むモデルは duration の代わりに使用します
input_reference	string	いいえ	OpenAI 形式の参照画像フィールド。対応するアダプタ（Sora や Wan など）が読みます
ratio	string	いいえ	16:9 や 9:16 などのアスペクト比。Seedance アダプタが読みます
resolution	string	いいえ	720p や 1080p などの出力解像度ティア。Seedance アダプタが読みます
generate_audio	boolean	いいえ	サウンドトラックを生成するか。Seedance では明示的な false も転送されます
metadata	object	いいえ	プロバイダ固有のパラメータ。Seedance では同名の場合 metadata の値がトップレベルより優先されます

RouteAPI が認識しないトップレベルのフィールドは無視されます。モデル固有のパラメータは metadata に入れてください。

送信エンドポイントは multipart/form-data 本文も受け付けます。スカラーのフォームフィールドは同じ名前に対応し、ファイルは直接アップロードされます（例：Sora の input_reference）。不明なフォームフィールドは metadata の項目になります。

注意

すべてのプロバイダがすべての共通フィールドを読むわけではありません。ratio、resolution、generate_audio は Seedance アダプタが解釈します。Veo は metadata.durationSeconds、metadata.resolution、metadata.aspectRatio を読み、size をフォールバックにします。Wan は size と metadata を読み、Sora は size、seconds、入力画像を読みます。プロバイダが認識しないフィールドは拒否されずに黙って破棄されるため、依存する前にベンダーページを確認してください。

送信例

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "An orange cat stretching on a windowsill at sunrise",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

送信レスポンス

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

task_id（およびそのエイリアス id）が RouteAPI のタスク ID で、以降のすべての呼び出しで使用します。上流プロバイダのタスク ID はポーリングに使う値ではありません。それが見える場合でも、保存された上流のペイロード（タスクレコードの data.data）内にあります。

送信が成功すると、適用された課金倍率を含む X-New-Api-Other-Ratios レスポンスヘッダーも返されます。例えば Sora では {"seconds":5,"size":1}、動画入力を伴う Seedance リクエストでは {"video_input":0.608695652174} です。請求額を照合するときに役立ちます。

送信段階のエラー

ルーティングされると、タスクエンドポイントはタスクのエラー形式で応答します:

{ "code": "invalid_request", "message": "prompt is required", "data": null }

ステータス	コード	意味
400	invalid_request	prompt の欠落・空白、metadata フィールドの型誤り、または本文を解析できない
400	invalid_json	本文を独自に検証するアダプタ（Sora と Wan）で JSON が不正
400	missing_model	model がない。本文を独自に検証するアダプタ（Sora と Wan）が返します。それ以外の経路では、model のないリクエストはルーティング前にミドルウェアエラーとして拒否されます
400	invalid_seconds	duration / seconds が負、または 3600 を超える
400	invalid_size	モデルが受け付けないサイズ（例：未対応の Sora サイズ）
400	model_price_error	RouteAPI がモデルの価格を計算できなかった。上流には送信されません
400	model_not_supported	チャネルが提供を終了したモデルに解決された（例：Seedance 1.x）
400	task_not_exist	remix の元タスクが不明、または別アカウントのもの
400	task_source_unavailable	remix の元タスクのチャネルが削除・無効、またはアダプタが見つからない
403	insufficient_user_quota / pre_consume_token_quota_failed	アカウント残高またはキーのクォータが見積もり費用に足りない。上流には送信されません
429	—	上流のキャパシティが枯渇。メッセージは一般的な「後で再試行してください」に置き換えられます
500	build_request_failed、do_request_failed、invalid_response	タスクを変換できない、上流への接続に失敗した、または上流がタスク ID を返さなかった
500	get_channel_failed、task_persistence_failed、gen_relay_info_failed	RouteAPI がルーティングまたはタスク記録に失敗。課金されません（予約は返金されます）
502	upstream_task_id_missing	上流はタスクを受け付けたがタスク ID を返さなかった。タスクは失敗とされ予約が解放されます
任意	fail_to_fetch_task	上流が送信に対して非 200 を返した。HTTP ステータスは上流のものです

ルーティング前に拒否されたリクエスト — API Key の欠落・無効（401）、IP 制限、アクセス権のないグループ、キーの許可リスト外のモデル（403）、または利用可能なチャネルのないモデル（503、コード model_not_found） — は、タスク形式ではなく標準ミドルウェアのエラー本文 {"error": {"message": ..., "type": "error", "code": ...}} を使用します。

送信後に発生した失敗（コンテンツ審査、プロバイダのタイムアウト、キャンセル）は HTTP エラーとして現れません。タスクレコードに fail_reason 付きの FAILURE として現れ、予約額は返金されます。

次のステップ

• 動画タスクの取得 — タスクレコードのポーリング、ステータスの読み取り、結果のダウンロード。
• Seedance、Hailuo、Wan — モデル固有のパラメータと制限。
• Assets（アセット） — 再利用可能な画像・動画・音声素材をアップロードし、asset:// で参照する。
• よくあるエラー — すべてのモデルエンドポイントが共有するステータスコード。