For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
跳至內容

逾時與連線問題

排解 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 — 了解非同步影片任務 使用記錄與成本 — 調查請求活動與費用 生成媒體歷史記錄 — 檢查最近生成的媒體

最後更新於

這有幫助嗎?