說明文件

錯誤處理 / 速率限制

錯誤處理

HTTP 錯誤會包含一個 error 物件，內有 code（錯誤碼）和 message（錯誤訊息）。即使任務成功建立，後續仍可能生成失敗；請持續查詢任務狀態或處理失敗回呼。

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	欄位	建議處理方法
400	`invalid_request`	請在重試前修正 JSON 格式、缺少的提示詞、無效的參數範圍或媒體 URL。
401	`invalid_api_key`	請檢查 Bearer 權杖（Token）以及 API 金鑰是否處於啟用狀態。
402	`insufficient_credits`	請儲值額度或降低任務成本。回應中可能會顯示所需的額度與目前可用額度。
403	`forbidden`	請檢查錯誤訊息中說明的帳戶權限限制。
404	`not_found`	請檢查任務 ID 是否正確，以及該金鑰是否屬於建立該任務的使用者。
429	`rate_limited`	請在 Retry-After 指定的間隔時間過後再重試。
500	`internal_error`	請檢查錯誤訊息和 API 日誌。請謹慎重試；重複送出建立請求可能會產生新的計費任務。

建立任務：預設情況下，每個 API 金鑰每分鐘最多允許 100 次請求。目前不提供自訂速率限制。

查詢任務：預設情況下，每個 API 金鑰每分鐘最多允許 120 次請求。查詢請求與任務建立請求為分開計算。

圖片與影片的建立請求共用同一個 API Key 的速率限制額度。

回傳 HTTP 429 時，建立任務會包含 Retry-After: 60，查詢任務會包含 Retry-After: 5。請使用退避演算法（Backoff），避免過於頻繁地進行輪詢。

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}