Skip to Content
API 參考影片生成錯誤碼

錯誤碼

Video API 各端點的錯誤都使用同一個 JSON 結構：

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

HTTP 狀態碼表示問題的類別；error.code 是穩定的字串識別碼，供程式分支判斷。請始終按 error.code 比對，不要解析 error.message 文案。

錯誤碼表

HTTPcode含義
400invalid_request參數缺失或取值非法
400invalid_callback_urlcallback_url 非 HTTPS 或指向私有網路（被 SSRF 校驗攔截）
400references_conflictframe_images 與 input_references 在同一請求中同時傳（互斥）
400too_many_referencesinput_references 超出上限（圖 > 9 / 音 > 3 / 視 > 1）
400cancel_not_supported上游 provider 不支援中斷該任務
400cancel_failed任務已處於終態，無法取消
401unauthorized / invalid_api_key鑑權失敗
401upstream_auth_failed上游供應商鑑權失敗
402insufficient_credits餘額不足，無法受理任務
404not_found任務不存在，或無存取權限
404model_not_found模型不存在
429rate_limited頻率超限（輪詢限流或上游限流）
502upstream_error / route_error上游供應商錯誤 / 路由失敗
500internal_error內部錯誤

references_conflict 與 too_many_references 是請求體校驗錯誤，具體上限見 建立影片任務。cancel_not_supported 與 cancel_failed 的判定見 取消任務。not_found 對「任務不存在」和「任務屬於其他 API Key」兩種情況統一返回——二者故意不作區分。

real_person 圖片預處理錯誤

當 real_person: true 因傳入圖片問題導致預處理失敗時，API 返回 HTTP 400，且 error.code 為 invalid_request。error.message 末尾會包含以下穩定原因短碼，並標出出錯引用位置，例如 input_references[0]：

原因短碼處理方式
bad_data_uridata: URI 格式錯誤，或 base64 內容無效
download_failed因連線、逾時或存取控制問題無法下載圖片
unreachable圖片 URL 返回非成功 HTTP 狀態
not_image下載內容不是支援且可解碼的圖片
too_large圖片超過檔案大小、像素數或單次請求的處理上限
{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

程式分支仍應判斷 error.code；原因短碼和引用位置用於修正輸入或排查問題。

402 餘額不足

insufficient_credits 僅在建立任務（POST /v1/videos）時返回。啟用預授權時，ofox 會在受理任務前，根據請求的解析度與時長預估費用。若預估額超過你的餘額，請求會被立即拒絕——不會建立任務記錄，也不會產生任何扣費。

{ "error": { "code": "insufficient_credits", "message": "..." } }

Video API 的 402 只會返回 insufficient_credits 這一個 code。接入方處理這一個 code、儲值後重試即可。

429 頻率限制

rate_limited 同時涵蓋 GET /v1/videos/{id} 的按 Key 輪詢限流與上游限流。觸發輪詢限流時，回應會帶 Retry-After 標頭：

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

請尊重 Retry-After 標頭，退避後再重試。若輪詢過於頻繁，改用 Webhook 通知——由 ofox 在終態時主動推送，徹底避開輪詢限流。建立任務（POST）與取消任務（DELETE）不受該輪詢限流影響。

Last updated on
Webhook 通知