跳到內容
RouteAPI RouteAPI

建立影片生成任務

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 影片格式。

端點

Section titled “端點”
方法路徑用途文件位置
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 是同一項任務操作的兩條路徑，只是請求和回應的方言不同。兩者的提交回應都是 OpenAI video 物件；GET 端點則不同（任務記錄與 video 物件），因此每條提交路徑都要搭配對應的 GET。

任務執行流程

Section titled “任務執行流程”
  1. 提交 — 把提示詞與模型送到 POST /v1/video/generations（或 POST /v1/videos），並保存回傳的 task_id。此時會從你的餘額預扣預估費用。
  2. 輪詢 — 每 10–15 秒呼叫對應的 GET 端點。生成通常需要一到數分鐘；解析度越高、時長越長，耗時越久。
  3. 完成 — 狀態回報成功後，下載影片或讀取它的 URL。若任務失敗，或一直沒有進入最終狀態，預扣金額會退回。

提交任務

Section titled “提交任務”
POST /v1/video/generations

請求欄位

Section titled “請求欄位”

每個影片模型都接受這組通用外層結構。模型專屬選項放在 metadata；各轉接器實際讀取的鍵請見對應廠商頁面。

欄位類型必填說明
modelstring是來自 GET /v1/models 的模型 ID
promptstring是文字提示詞。缺少、空白或只含空白的提示詞會以 400 拒絕
imagestring否單張圖片（URL 或 Base64/data URI）。視為 images 的第一個項目
imagesstring[]否參考圖／首影格圖片。意義依模型而定
sizestring否尺寸或解析度提示，例如 1280x720 或 720p，依模型而定
durationinteger否時長（秒）。RouteAPI 會拒絕負值與超過 3600 的值
secondsstring否時長的舊式字串形式。會讀取它的模型會以此取代 duration
input_referencestring否OpenAI 風格的參考圖欄位，由支援它的轉接器讀取（例如 Sora 與 Wan）
ratiostring否長寬比，例如 16:9 或 9:16；由 Seedance 轉接器讀取
resolutionstring否輸出解析度等級，例如 720p 或 1080p；由 Seedance 轉接器讀取
generate_audioboolean否產生配樂。在 Seedance 上明確的 false 會轉發，而不是被丟棄
metadataobject否供應商專屬參數。對 Seedance 而言，metadata 中的同名值優先於頂層值

RouteAPI 不認識的頂層欄位會被忽略；模型專屬參數請放在 metadata 底下。

提交端點也接受 multipart/form-data 主體：純量表單欄位對應到相同名稱，檔案則直接上傳（例如 Sora 的 input_reference）。不認識的表單欄位會成為 metadata 項目。

提交範例

Section titled “提交範例”
Terminal window
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
  }'

提交回應

Section titled “提交回應”
{
  "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 不是你要用來輪詢的值——即使能看見，也只會出現在儲存的上游 payload（任務記錄中的 data.data）裡。

提交成功時也會回傳 X-New-Api-Other-Ratios 回應標頭，內含此次套用的計費倍率——例如 Sora 的 {"seconds":5,"size":1}，或帶有影片輸入的 Seedance 請求的 {"video_input":0.608695652174}。核對扣費時很有用。

提交階段的錯誤

Section titled “提交階段的錯誤”

一旦完成路由，任務端點會以任務錯誤結構回應：

{ "code": "invalid_request", "message": "prompt is required", "data": null }
狀態碼錯誤碼含義
400invalid_request缺少或空白 prompt、metadata 欄位型別錯誤，或請求主體無法解析
400invalid_json在自行驗證請求主體的轉接器上（Sora 與 Wan），JSON 格式錯誤
400missing_model缺少 model；由自行驗證請求主體的轉接器（Sora 與 Wan）回傳。其他路徑會在路由前以中介層錯誤拒絕缺少 model 的請求
400invalid_secondsduration / seconds 為負或超過 3600
400invalid_size模型不接受的尺寸，例如不支援的 Sora 尺寸
400model_price_errorRouteAPI 無法為該模型計價；不會提交到上游
400model_not_supported模型解析到渠道已不再供應的模型，例如 Seedance 1.x
400task_not_existRemix 的來源任務未知或屬於其他帳戶
400task_source_unavailableRemix 的來源任務渠道已移除、停用，或缺少對應轉接器
403insufficient_user_quota / pre_consume_token_quota_failed帳戶餘額或 Key 額度不足以負擔預估費用；不會提交到上游
429—上游容量耗盡；訊息會替換成通用的「請稍後再試」文字
500build_request_failed、do_request_failed、invalid_response任務無法轉換、上游連線失敗，或上游未回傳任務 ID
500get_channel_failed、task_persistence_failed、gen_relay_info_failedRouteAPI 無法選渠道或記錄任務；不會扣費（預扣會退回）
502upstream_task_id_missing上游接受任務但未回傳任務 ID；任務會標為失敗，預扣金額隨之釋放
任何fail_to_fetch_task上游在提交時回傳非 200 狀態；HTTP 狀態碼沿用上游的值

在路由前就被拒絕的請求——缺少或無效的 API Key（401）、IP 限制、分組沒有存取權、模型不在 Key 的白名單內（403），或模型沒有可用渠道（503，錯誤碼 model_not_found）——會使用標準中介層錯誤主體 {"error": {"message": ..., "type": "error", "code": ...}}，而不是任務結構。

提交之後才發生的失敗（內容審核、供應商逾時、取消）不會以 HTTP 錯誤呈現。它們會以任務記錄中的 FAILURE 搭配 fail_reason 出現，並退回預扣金額。

下一步

Section titled “下一步”