跳到內容
RouteAPI RouteAPI

取得影片生成任務狀態

透過建立影片生成任務提交任務後，輪詢 GET /v1/video/generations/{task_id} 直到任務進入最終狀態，再從 GET /v1/videos/{task_id}/content 下載影片。輪詢讀取的是 RouteAPI 在背景重新整理的任務記錄，因此 10–15 秒的間隔已經足夠。

取得任務記錄

Section titled “取得任務記錄”
GET /v1/video/generations/{task_id}

任務以 API Key 所屬使用者為範圍：屬於其他帳戶的 task_id 會回報為 task_not_exist。

Terminal window
curl https://api.routeapi.ai/v1/video/generations/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"
{
  "code": "success",
  "message": "",
  "data": {
    "id": 4512,
    "created_at": 1792048450,
    "updated_at": 1792048569,
    "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
    "platform": "54",
    "user_id": 1024,
    "group": "default",
    "channel_id": 18,
    "quota": 123456,
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://...mp4",
    "submit_time": 1792048458,
    "start_time": 1792048461,
    "finish_time": 1792048569,
    "properties": {
      "input": "",
      "origin_model_name": "seedance-2.0-fast"
    },
    "data": { "id": "cgt-xxxxxxxx", "status": "succeeded" }
  }
}

任務記錄欄位

Section titled “任務記錄欄位”
欄位說明
code任務可讀取時為 "success"；失敗時使用下文的任務錯誤結構
data.id內部列 ID，任何請求都不使用
data.task_idRouteAPI 任務 ID——輪詢與下載都用它
data.statusNOT_START、SUBMITTED、QUEUED、IN_PROGRESS、SUCCESS 或 FAILURE
data.progress進度字串，例如 "30%" 或 "100%"
data.result_url任務成功後的影片 URL。它可能指向 RouteAPI 下載端點，或直接指向上游有期限的 URL
data.fail_reason失敗原因，其他情況為空
data.submit_time / start_time / finish_timeUnix 秒。任務開始與結束前，start_time、finish_time 為 0
data.created_at / updated_atUnix 秒，該列的建立時間與最後更新時間
data.quota該任務扣除的額度
data.platform執行該任務的上游渠道類型編號
data.group / data.channel_id / data.user_id計費分組、渠道與所屬帳戶。向支援詢問任務時有用
data.action任務類型：generate、textGenerate、firstTailGenerate、referenceGenerate 或 remixGenerate
data.properties儲存的任務屬性：origin_model_name、upstream_model_name，轉接器擷取時 input 中還有上游請求快照。僅供排查
data.data上游供應商最新的任務 payload，儲存供除錯用。格式由供應商決定

狀態

Section titled “狀態”
狀態含義下一步
NOT_START任務列已建立，但尚未輪詢上游繼續輪詢
SUBMITTED / QUEUED已受理，在供應商佇列中等待繼續輪詢
IN_PROGRESS正在生成繼續輪詢
SUCCESS成功的最終狀態下載影片
FAILURE失敗的最終狀態讀取 fail_reason；預扣金額已退回

只有 SUCCESS 是成功的最終狀態；FAILURE 是失敗的最終狀態，看到它時預扣金額已經退回。其他狀態都代表要繼續輪詢。

輪詢範例

Section titled “輪詢範例”
import os
import time
import requests


BASE = "https://api.routeapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ROUTEAPI_KEY']}"}


task_id = requests.post(
    f"{BASE}/v1/video/generations",
    headers=HEADERS,
    json={
        "model": "seedance-2.0-fast",
        "prompt": "An orange cat stretching on a windowsill at sunrise",
        "duration": 5,
        "resolution": "720p",
        "ratio": "16:9",
    },
    timeout=60,
).json()["task_id"]


while True:
    task = requests.get(f"{BASE}/v1/video/generations/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    print(task["status"], task["progress"])


    if task["status"] == "SUCCESS":
        video = requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=HEADERS, timeout=300)
        video.raise_for_status()
        with open(f"{task_id}.mp4", "wb") as f:
            f.write(video.content)
        break
    if task["status"] == "FAILURE":
        raise SystemExit(f"task failed: {task['fail_reason']}")


    time.sleep(15)

完整 Shell 範例

Section titled “完整 Shell 範例”
#!/usr/bin/env bash
set -euo pipefail
: "${ROUTEAPI_KEY:?set ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"


TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-fast","prompt":"An orange cat stretching on a windowsill at sunrise","duration":4,"resolution":"480p","ratio":"16:9"}' \
  | jq -er .task_id)


echo "task: $TASK_ID"


for _ in $(seq 1 60); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(echo "$RESP" | jq -r .data.status)
  echo "status: $STATUS $(echo "$RESP" | jq -r .data.progress)"


  case "$STATUS" in
    SUCCESS)
      curl -sSL -o "$TASK_ID.mp4" "$BASE/v1/videos/$TASK_ID/content" -H "$AUTH"
      echo "saved $TASK_ID.mp4"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(echo "$RESP" | jq -r .data.fail_reason)"
      exit 1
      ;;
  esac


  sleep 15
done


echo "timed out waiting for the task"
exit 1

輪詢 GET /v1/video/generations/{task_id} 通常只是讀取本地的任務記錄，因此請把間隔維持在 10–15 秒，不要猛打端點。

下載影片

Section titled “下載影片”
GET /v1/videos/{task_id}/content

透過 RouteAPI 串流影片位元組，因此呼叫方不需要能存取供應商的儲存空間。回應會帶 Cache-Control: public, max-age=86400 與上游的 Content-Type（行內 Base64 結果預設為 video/mp4）。

Terminal window
curl -L -o out.mp4 \
  https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/content \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

此路徑接受 API Key 或控制台工作階段，且只會回傳呼叫者擁有的任務資料。其錯誤使用 {"error": {"message": "...", "type": "..."}} 物件結構：

狀態碼含義
400任務尚未完成；訊息中附上目前狀態
404任務未知，或該任務屬於其他帳戶
403解析出的影片 URL 被出站存取保護規則拒絕
500任務列或其渠道讀取失敗，或影片 URL 無法解析
502無法連線供應商、供應商回傳非 200 狀態，或影片 URL 為空

錯誤

Section titled “錯誤”
狀態碼錯誤碼含義
400task_not_existtask_id 未知或屬於其他帳戶
500get_task_failedRouteAPI 無法讀取自身的任務列
500marshal_response_failed、copy_response_body_failedRouteAPI 無法序列化或寫出回應

在路由之前被拒絕的請求使用標準中介層錯誤主體 {"error": {"message": ..., "type": "error", "code": ...}}，而不是任務結構。

下一步

Section titled “下一步”