查詢任務狀態


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

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

Terminal


curl https://api.ofox.ai/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": "google/veo-3.1",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.ai/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 任務物件

欄位	類型	說明
`id`	string	任務唯一識別碼（UUID）
`status`	enum	見狀態機
`model`	string	模型 slug
`prompt`	string	原始提示詞
`unsigned_urls`	string[]	`completed` 時出現。上游原始影片 URL（暫時，可能 24h 過期）
`mirror_urls`	string[]	`completed` 且該模型 provider 啟用 CDN 鏡像時出現。持久簽名 URL，見影片 URL
`error`	object	`failed` 時出現：`{code, message}`
`usage`	object	`completed` 時出現：`{video_seconds, video_cost}`。`video_seconds` 為計費秒數（含 v2v 輸入秒）；`video_cost` 為按平台檔價計費的實際費用，定點 10 位小數字串（防精度遺失）
`created_at` / `updated_at`	integer	Unix 秒

狀態機

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_urls`	ofox CDN 鏡像	持久——僅啟用 CDN 的 provider · 每次請求現簽 · 有 TTL

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

查詢任務狀態

限流保護

回應

已完成

失敗

Video 任務物件

狀態機

影片 URL