逾時與連線問題
排解 ApiSmart 請求逾時、連線問題、暫時性服務錯誤,以及耗時較長的圖片與影片生成請求。
某些 ApiSmart 請求可能比一般 API 呼叫花更長時間,特別是圖片與影片生成。
如果請求逾時或回傳暫時性 5xx 錯誤,請先判斷問題是由於你的用戶端逾時、長時間執行的生成,還是暫時性的上游服務問題。
⏱️ 圖片請求逾時
圖片生成預設為同步。
當你呼叫:
POST /v1/images/generations連線會保持開啟,直到生成完成並回傳結果。
單張圖片通常需要約 20–40 秒。高解析度圖片、多張參考圖片或連續生成可能需要更久。
將你的用戶端逾時設定至少為:
90 秒使用稍長一些的值,例如 120 秒 可提供額外的緩衝。
重要: 用戶端逾時不一定代表生成失敗。即使你的用戶端在接收結果前中斷,圖片仍可能完成並產生費用。
如果發生這種情況,請先檢查 生成媒體歷史記錄 或 使用記錄與成本 ,再立即再次送出相同請求。
🎬 影片請求不應等待完成
影片生成採用非同步任務流程。
先建立影片任務,再另外查詢其狀態。
在生成進行中時,任務可能回傳:
queued
排隊中
running
生成進行中
succeeded
生成完成
failed
生成失敗
cancelled
任務已取消
expired
任務已過期
在等待最終影片期間,不要保持原始影片建立請求開啟。
在狀態為 queued 或 running.
完整流程請參閱 影片生成 API.
🔌 502 — 閘道或上游錯誤
A 502 回應可能表示 ApiSmart 與上游模型服務或網路層之間出現暫時性問題。
可能的代碼包括:
這些錯誤可能是暫時性的。
請稍候片刻再重試,並使用指數退避,而不是立即連續送出請求。
⚠️ 503 — 服務暫時無法使用
A 503 可能表示相依服務暫時無法使用。
可能的代碼包括:
provider_not_available
模型供應商暫時無法使用
quota_service_unavailable
配額服務暫時無法使用
proxy_unavailable
代理相依項目暫時無法使用
asset_owner_service_unavailable
資產擁有者服務暫時無法使用
如果回應提供 Retry-After,請在指示的時間過後再重試。
如果 503 是在切換模型後立即出現,也請確認模型 ID。ApiSmart 模型 ID 必須完全相符。
⌛ 504 — 閘道逾時
A 504 GatewayTimeout 表示上游服務未在預期時間內回應。
這可能是暫時性的服務或網路層問題。
建議的處理方式是等待,並使用受控的指數退避重試。
例如:
請在合理次數後停止,而不要無限重試。
🔁 謹慎重試暫時性錯誤
針對如 502, 503,以及 504這類暫時性連線或服務失敗,請使用受控重試。
良好的重試策略應該:
在各次嘗試之間等待
在多次失敗後增加延遲時間
遵循
Retry-After(若有提供)設定最大重試次數
避免持續重試同一個請求
請不要將此重試策略自動套用到無效參數、驗證失敗或餘額不足。
完整的重試指南請參閱 HTTP 狀態碼與 API 錯誤.
🔎 請求已逾時,但你不確定發生了什麼
在再次送出相同請求之前,請先確認它是否可能已經完成。
對於圖片生成,請查看 生成媒體歷史記錄 以及 使用記錄與成本.
對於影片生成,請查詢:
使用任務建立時回傳的任務 ID。
這有助於避免不必要的重複生成與額外費用。
✅ 快速疑難排解清單
當請求逾時或連線中斷時,請先檢查端點:同步圖片生成請至少使用 90 秒逾時,影片任務請輪詢而不要等待完成,並且僅在受控退避下重試 502, 503,或 504 。如果請求可能已經完成,請在再次送出前先檢查其任務狀態、媒體歷史或使用紀錄。
其他失敗情況請參閱 HTTP 狀態碼與 API 錯誤.
➡️ 下一步
HTTP 狀態碼與 API 錯誤 — 檢視所有 API 錯誤代碼 圖片生成 API — 了解同步圖片請求 影片生成 API — 了解非同步影片任務 使用記錄與成本 — 調查請求活動與費用 生成媒體歷史記錄 — 檢查最近生成的媒體
最後更新於
這有幫助嗎?