Skip to Content
API 參考影片生成查詢任務

查詢任務狀態

GET https://api.ofox.io/v1/videos/{id}

查詢任務的狀態與結果。建立任務後，輪詢此端點直到 status 進入終態——completed、failed、cancelled 或 expired。

Terminal
curl https://api.ofox.io/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718 \
  -H "Authorization: Bearer $OFOX_API_KEY"

限流保護

本端點按 API Key 獨立限流（預設 5 req/s、突發 20）。超限返回 429 rate_limited，並帶 Retry-After: 1 回應標頭。建立（POST）與取消（DELETE）不受此限流影響。

建議輪詢間隔不快於每秒一次，或在建立任務時傳 callback_url，用 webhook 取代輪詢。

回應

{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "completed",
  "model": "bytedance/seedance-2.5",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.io/videos/vgen_xxx.mp4?sig=..."],
  "usage": {
    "video_seconds": 5,
    "video_cost": "0.4000000000"
  },
  "created_at": 1776211362,
  "updated_at": 1776211400
}

逾時會以 status: "failed" 上報，且 error.code 為 expired。完整錯誤碼見 錯誤碼。

Video 任務物件

欄位類型說明
idstring任務唯一識別碼（UUID）
statusenum見 狀態機
modelstring模型 slug
promptstring原始提示詞
unsigned_urlsstring[]completed 時出現。上游原始影片 URL（暫時，可能 24h 過期）
mirror_urlsstring[]completed 且該模型 provider 啟用 CDN 鏡像時出現。持久簽名 URL，見 影片 URL
errorobjectfailed 時出現：{code, message}
usageobjectcompleted 時出現：{video_seconds, video_cost}。video_seconds 為計費秒數（含 v2v 輸入秒）；video_cost 為按平台檔價計費的實際費用，定點 10 位小數字串（防精度遺失）
created_at / updated_atintegerUnix 秒

狀態機

7 個狀態，以 OpenRouter 命名為基底並補充 cancelled / expired。

狀態終態說明
pending—已受理，尚未提交上游
queued—已提交上游，佇列中
in_progress—上游生成中
completed✓成功，影片 URL 可用
failed✓失敗（含逾時，error.code=expired）
cancelled✓已取消
expired✓過期

流轉：pending → queued → in_progress → completed 為成功路徑。任意非終態可轉 failed、cancelled 或 expired。

影片 URL

成功任務可能返回兩組 URL，取決於該模型 provider 是否啟用 CDN 鏡像。

欄位來源特性
unsigned_urls上游供應商原始地址暫時——恆有 · 可能 24h 過期 · 未簽名
mirror_urlsofox CDN 鏡像持久——僅啟用 CDN 的 provider · 每次請求現簽 · 有 TTL

優先使用 mirror_urls（持久、穩定）。當模型只返回 unsigned_urls 時，請盡快下載或轉存，避免上游暫時地址過期。

Last updated on
供應商路由取消任務