限流與配額

平台的限制分為幾類，觸發後的表現各不相同。分清楚是哪一類，才能快速處理。

請求頻率限制

平台對請求頻率有限制。輪詢過快、並行過高，或短時間內大量重試，都可能觸發：

{ "error": { "code": "...", "message": "请求过于频繁" } }

HTTP 狀態為 429。

正確做法：

• 收到 429 後退避：等待一段時間再送出下一次請求，不要立刻重送；
• 不要用並行請求繞過限流，這只會讓退避時間更長；
• 輪詢非同步任務時使用固定且合理的間隔（例如每隔幾秒一次），不要無間隔輪詢。

不要對 429 以外的狀態碼盲目重試：

非同步任務並行

影片等非同步任務受並行上限約束，分為單一帳號層級和平台整體層級。達到上限時傳回 HTTP 429， 錯誤碼為 task_concurrency_exceeded，提示中會給出「目前 N 個 / 上限 M 個」。

遇到時應：

1. 保留既有任務的 ID，不要丟棄；
2. 等待進行中的任務進入終態（或直接查詢它們的目前狀態）；
3. 等待後再由使用者主動重新提交，不要連續重試；
4. 不要為了「搶」並行而重複提交同一個任務——那會產生重複任務和重複費用。

批次提交前，建議在業務後端做佇列化管理：控制進行中的任務數量，而不是一次全部提交。

Key 額度與帳戶餘額

額度與餘額是兩層限制：

非同步任務在提交前會驗證餘額能否涵蓋本次預估消耗。不足時會傳回可讀提示， 並且不會建立任務，因此這種情況不會產生費用。

處理方式：

• Key 額度不足 → 在「API 金鑰」中調整該 Key 的額度或有效期限；
• 帳戶餘額不足 → 前往「錢包」儲值或使用方案；
• 預估消耗過大 → 降低解析度、時長或改用更小的模型。

建議在業務後端對餘額做前置判斷，向最終使用者提供清楚的提示，而不是把平台的錯誤直接拋給使用者。

素材限制

素材介面會對上傳資料進行驗證：

素材審核未完成不是錯誤：查詢傳回 200 且 status 為 Processing，繼續使用同一個素材 ID 輪詢即可， 不要重複提交。

輪詢建議

非同步任務的查詢不產生費用，但過於密集的輪詢會觸發限流。

輪詢應有總時長上限。達到上限後停止查詢並向使用者傳回任務 ID，讓使用者可以稍後憑 ID 繼續查詢—— 不要重新建立任務。

冪等與重複提交

平台不會自動合併相同的請求。即使提示詞、參數和參考素材完全相同，每次主動提交都會建立 新的任務和新的結果，並各自計費。

因此：

• 使用業務端的冪等鍵（訂單編號、業務 ID）防止使用者重複點擊導致重複提交；
• 非同步任務提交後立即在資料庫中儲存任務 ID，網路中斷時以查詢而不是重新建立來還原；
• 只有對同一筆失敗結果點擊「直接重試」時，才會在原位置重新執行——這同樣會產生新任務和新費用。