跳到內容
RouteAPI RouteAPI

OpenAI 影片格式

POST /v1/videos 與 GET /v1/videos/{task_id} 是同一套非同步任務 API 的 OpenAI 影片方言，任務流程見建立影片生成任務與取得影片生成任務狀態。提交主體使用相同欄位，差別在回應：提交回應與 GET 都回傳 OpenAI video 物件，而不是任務記錄。Sora 模型使用這種格式，OpenAI SDK 的影片用戶端也按這種格式解析。

端點

Section titled “端點”
方法路徑用途
POST/v1/videos提交生成任務
GET/v1/videos/{task_id}以 OpenAI video 物件讀取任務
GET/v1/videos/{task_id}/content下載完成的影片位元組
POST/v1/videos/{video_id}/remix以現有影片為基礎建立新任務

提交

Section titled “提交”
Terminal window
curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A calico cat playing a piano on stage",
    "size": "1280x720",
    "seconds": "4"
  }'

請求欄位就是建立影片生成任務中列出的那一組：model、prompt、seconds / duration、size、input_reference、images 與 metadata。支援參考圖的模型會讀取 input_reference。也接受 multipart/form-data，可直接上傳檔案：

Terminal window
curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "size=1280x720" \
  -F "seconds=4" \
  -F "input_reference=@cat.jpg"

提交回應

Section titled “提交回應”
{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

id 就是 RouteAPI 的任務 ID。task_id 是相容別名，後續可能不再回傳，請讀取 id。後續輪詢與下載一律使用這個 id；儲存的上游 payload 中出現的 ID 不是你要用的值。

提交回應也會帶上 X-New-Api-Other-Ratios 回應標頭，內含實際套用的計費倍率，例如 Sora 請求的 {"seconds":5,"size":1}。

取得 video 物件

Section titled “取得 video 物件”
GET /v1/videos/{task_id}
Terminal window
curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"
{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1792048458,
  "completed_at": 1792048569,
  "metadata": { "url": "https://...mp4" }
}
欄位說明
idRouteAPI 任務 ID
object固定為 "video"
model執行該任務的模型
statusqueued、in_progress、completed 或 failed
progress0–100 的整數
created_at / completed_atUnix 秒。部分轉接器會用該列的最後更新時間填入 completed_at，因此請用 status 判斷是否完成，而不要依賴這個欄位
expires_at、size、seconds、remixed_from_video_id僅在供應商回傳時出現
metadata.url供應商透過 video 物件回報的影片 URL。若不論供應商都想取得位元組，請用 /v1/videos/{task_id}/content
error.code / error.message任務失敗時設定，例如 Seedance 的 expired 或 cancelled

上游 payload 自帶的欄位（例如 expires_at 或 size）只有在供應商回傳時才會出現；上表是 RouteAPI 保證會對應的集合。在 Gemini 與 Vertex 渠道上，組出這個物件前會先從供應商重新整理任務狀態。

任務以 API Key 所屬使用者為範圍：屬於其他帳戶的 id 會回報為 task_not_exist，與任務記錄端點一致。

下載內容

Section titled “下載內容”
GET /v1/videos/{task_id}/content

回傳影片位元組，經 RouteAPI 串流傳輸。回應帶有 Cache-Control: public, max-age=86400 與上游的 Content-Type。此路徑接受 API Key 或控制台工作階段，且只提供呼叫者自己任務的影片。錯誤碼與 curl 範例見下載影片。

Remix

Section titled “Remix”
POST /v1/videos/{video_id}/remix

以現有影片建立新任務。RouteAPI 會在你的任務中尋找 video_id，從中推導模型，並把請求固定路由到產生原始影片的渠道，讓結果保持相容。

Terminal window
curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/remix \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "The same cat, now wearing a tiny hat" }'

Remix 對 Sora 系列（sora-2、sora-2-pro）才有實質意義：請求會轉發到上游自己的 remix 端點，且必須提供 prompt。對其他平台而言，請求仍會被接受，模型與渠道會由來源任務解析，任務由該模型的轉接器建立——但上游從未收到 remix 指令，因此新任務只是一般的生成，而非 video_id 的衍生物。

轉接器記錄了來源任務的計費倍率時，remix 會繼承這些倍率，因此新任務按來源任務計價，而不是按預設值。

Sora

Section titled “Sora”

Sora 模型直接使用這組端點，真正起作用的參數是 size 與 seconds。

模型可用尺寸
sora-2720x1280、1280x720
sora-2-pro720x1280、1280x720、1792x1024、1024x1792
  • 不支援的尺寸會在預扣任何費用之前回傳 400，錯誤碼 invalid_size。
  • 預設值為 720x1280 與 4 秒。
  • seconds（或 duration）與其他影片模型同樣驗證：負值與超過 3600 的值會被拒絕，回傳 400 invalid_seconds。
  • input_reference 作為參考圖轉發；JSON 與 multipart 提交都可用。
  • 計費由 seconds 與 size 計算：1792x1024 或 1024x1792 輸出會在接受秒價格之外再乘上尺寸倍率（1.666667）。實際套用的倍率會透過 X-New-Api-Other-Ratios 回傳。
  • 該系列支援 Remix。

可用性與價格依帳戶而定——請確認模型出現在 GET /v1/models 中，並查看模型詳情頁。

錯誤

Section titled “錯誤”

完成路由後適用任務錯誤結構：

狀態碼錯誤碼含義
400invalid_request缺少或空白 prompt、主體格式錯誤，或欄位型別錯誤
400invalid_secondsduration / seconds 為負或超過 3600
400invalid_size模型不接受該尺寸（例如不支援的 Sora 尺寸）
400task_not_existremix 中的 video_id 未知或屬於其他帳戶
400task_source_unavailable來源任務的渠道已移除、停用，或缺少對應轉接器
400asset_remix_conflict對非素材任務做 remix 時試圖參照 asset:// 素材
429—上游容量耗盡；訊息會替換成通用的重試提示
500build_request_failed、do_request_failed任務無法轉換或上游連線失敗
500convert_to_openai_video_failed儲存的任務資料無法轉換為 video 物件
501not_implemented在轉接器沒有 OpenAI 影片轉換的平台上呼叫 GET /v1/videos/{task_id}
任何fail_to_fetch_task上游在提交時回傳非 200 狀態；HTTP 狀態碼沿用上游的值

在路由之前被拒絕的請求改用標準錯誤主體 {"error": {"message": ..., "type": "error", "code": ...}}。

下一步

Section titled “下一步”