TTS 限流處理完整指南：Rate Limit 撞牆嘅實戰應對

一句答你： 撞 TTS 限流唔使慌，先分清楚撞緊邊一層：429 rate_limit_exceeded 係每分鐘提交太密（預設 60 次）；429 in_flight_limit_reached 係同時進行嘅任務太多（免費 3 個至工作室 20 個）；403 monthly_cap_reached 係 key 嘅月度字符上限到咗；沙盒 key 仲有每日 20 個生成提交嘅額度。睇錯誤碼、跟 Retry-After 退避，逐層對症下藥。

Key Takeaways

• 限流只計成功嘅提交請求，用滑動 60 秒窗口計；查詢（GET）端點完全唔限流
• 每分鐘限流預設 60 次／key，開 key 時可以調整；撞限流會回 Retry-After 秒數
• 在途任務上限按方案：免費 3、入門 5、專業 10、工作室 20
• API key 可以設定月度字符上限，到頂回 403 monthly_cap_reached
• 沙盒 key 每日 20 個生成提交（按帳戶計、跨 key 共享），查詢同下載唔計
• 一個批量請求喺限流同在途上限都計一次，用盡 25 項最有效率

限流唔係敵人，係紅綠燈

好多開發者將限流（rate limit）當成敵人，見到 429 就煩躁。換個角度諗：限流其實係紅綠燈——佢唔係唔俾你行，係叫你按秩序行。冇限流嘅世界，一個團隊嘅失控腳本可以影響晒成個平台嘅服務質素；有限流，大家先可以各自穩定出量。而且限流規則係公開透明嘅：上限幾多、點樣計、撞到會話你知幾時可以再試，全部有數可循，你可以喺設計階段就納入考量。

但處理得唔好，限流確實會拖慢你嘅生產線。呢篇文將呢個 API 嘅所有限制拆開講清楚：每層限制嘅計法、點樣預早察覺、撞到點樣優雅處理。睇完你會有一套完整嘅應對 playbook，而唔係見到 429 就盲試。

好多開發者第一次見到 429 就當係「用得太多」，然後盲目咁慢落速度——如果其實撞嘅係在途任務上限，放慢提交只會令排隊更長，完全搞錯方向。所以處理限流嘅第一步，永遠係讀錯誤碼。呢個 API 嘅限制分三層，再加埋沙盒 key 嘅每日額度，一共四樣嘢：

各類錯誤碼嘅完整意思（包括 400／401／403／503），錯誤碼對照一文有完整對照表，本文集中講限流相關部分。

第一層：每分鐘提交限流

計法：滑動窗口，只計成功提交

預設每個 key 每分鐘 60 次（開 key 嘅時候可以調整），用滑動 60 秒窗口計——即係唔會喺整分時刻清零，而係任何連續 60 秒入面唔超過上限。呢種計法比「每分鐘歸零」更公平，但亦都意味住：你唔可以靠「等下一分鐘」嚟重置，要等窗口內嘅舊請求滑出去。

重要細節：只計成功嘅生成提交。你提交失敗（例如文字格式錯誤被 400 拒絕、權限唔夠被 403 拒絕）係唔會燒限流額度嘅。所以修正參數、反覆測試提交格式呢啲動作，唔會令你撞限流——真正燒額度嘅係成功提交嗰下。

60 次一分鐘，係咩概念？

人手操作——喺介面撳生成、測試工具試幾下——一分鐘撳到十次已經好誇張，60 次上限對人手嚟講係綽綽有餘。真正會撞牆嘅，幾乎全部係自動化腳本：迴圈入面冇延遲、錯誤處理入面無限重試、又或者幾個程序共用同一把 key 一齊狂發。所以當你撞限流，第一件事唔係抱怨上限太低，而係問：邊段 code 喺度無間斷咁發請求？十居其九係有個迴圈失控咗。

回應 header 點睇

提交請求嘅回應（無論 202 定 429）都會帶三個限流 header：X-RateLimit-Limit（上限）、X-RateLimit-Remaining（今個窗口剩幾多）、X-RateLimit-Reset（幾時重置）。寫 client 嘅時候讀住呢三個數，你可以喺撞牆之前主動減速——呢個係最體面嘅限流處理方式：唔係撞咗先應變，而係睇住錶揸車。

撞限流點做：跟 Retry-After

一旦回 429 rate_limit_exceeded，回應會帶 Retry-After 秒數（body 都有）。正確做法係停一停、等足秒數先重試，唔好即刻重發——重發只會繼續計入窗口，愈撞愈耐，好似塞車時愈扒愈塞。等足 Retry-After，通常一兩個週期就通返。

查詢端點唔限流

再強調一次：限流只計提交。查詢任務狀態、攞聲線目錄呢啲 GET 端點唔計入限流，回應亦冇限流 header。所以輪詢策略唔使為限流妥協，你可以自由設計查詢節奏。仲未行過提交流程嘅話，快速上手教學會由零帶你行一次。

第二層：在途任務上限

按方案分級嘅並行度

在途任務即係你提交咗、但仲未完成嘅任務。上限按方案分：

超上限提交會回 429 in_flight_limit_reached，回應會講明目前上限（limit）同活躍任務數（active）——呢兩個數就係你排程嘅依據：見到 active 接近 limit，就等一等多、完成一個先提交下一個。

呢層限制同每分鐘限流嘅本質唔同：每分鐘限流管嘅係「你幾密提交」，在途上限管嘅係「你有幾多嘢同時喺度整」。所以撞 in_flight 上限，減慢提交冇用——除非你提交嘅嘢完成得快過提交，否則個數只會一路向上。正解係管理完成速度，或者升方案。

善用在途額度：唔好單線程傻等

另一個極端都要避免：有人以為在途上限係 3，就一次過只提交一個、等完成先提交下一個——咁樣永遠用唔盡並行額度，成批任務嘅總時間直接乘大幾倍。正確做法係提交到上限、然後統一輪詢，等邊個完成就補邊個位。並行額度就係俾你用嘅，唔使慳；要管理嘅係「唔好超」，唔係「要留空」。

排程策略：完成驅動提交

穩陣嘅批量做法唔係「一口氣提交晒再算」，而係「完成驅動」：開場提交至上限，之後每偵測到一個任務完成（或者失敗、取消騰空名額），先提交下一個。咁樣你永遠貼住上限行，唔會撞 429，吞吐量亦都最大化。呢個模式好似停車場閘機：一架出先至一架入，閘機永遠唔會彈你。

第三層：key 月度字符上限

開 API key 嘅時候可以設定月度字符上限（唔設就冇上限）。呢個係 key 層面嘅安全閥——例如你俾唔同專案各開一把 key，每把設個上限，防止某個專案失控燒晒全帳戶配額。到頂之後提交會回 403 monthly_cap_reached，回應會有 used（已用量），你就可以決定調高上限，定等下一個週期。

注意呢個上限係「key」層面，同帳戶整體配額係兩回事：帳戶配額用完係配額問題，key 月度上限到就係呢個 403。管理多把 key 嘅團隊，兩層都要睇。API key 嘅申請、權限同上限參數設定，認證入門一文有詳細教學。

沙盒 key：每日 20 個生成提交

免費同入門方案嘅用戶可以開沙盒 key（sk_test_ 前綴）接駁測試，有個特別嘅每日額度：每日 20 個生成提交。三個細節要記住：

• 計數按帳戶計，跨所有沙盒 key 共享——開多幾把 key 唔會多咗額度
• 只計生成提交；查詢同下載完全唔計，輪詢練習零成本
• 超額回 429，聽日重嚟；或者升級到專業方案，現有 key 會即時自動變成全速 key

呢個設計令沙盒環境同正式環境行同一套整合邏輯，差別只在於每日提交量——你唔使為咗測試維護兩套 code，寫好一次，升級之後即刻全速。

批量請求點計？

批量生成（items 格式，單次最多 25 項）喺限流層面計好簡單：一個批量請求計一次。無論你個批量有 3 項定 25 項，限流同在途上限都係當一次提交計。呢個對高吞吐量場景係好消息：用盡批量，等於同一份限流額度搬多幾倍嘅文字。

記住批量係專業及以上方案嘅功能，免費同入門提交批量會回 403 batch_requires_pro（唔會扣費、唔會提交任何一項）。批量流程嘅完整設計可以睇批量生成 workflow；大量內容場景嘅整體安排就參考大量內容生成拆解。

設計你嘅提交架構：三種常見模式

模式一：即時少量（用戶觸發）

應用程式入面用戶撳一下、生成一條音——呢種模式壓力最細：單條提交、用戶等結果，每分鐘限流同在途上限都好少會撞。要注意嘅只有一樣：用戶狂撳重試嗰下——介面要有按鈕防抖（撳咗生成之後禁用個掣直到完成），唔係限流問題都變限流問題。

模式二：定時批量（夜間跑量）

內容團隊最常見：每日定時將累積嘅稿件一次過跑晒。呢種模式要行完成驅動提交：開場提交到在途上限、批量用盡 25 項、輪詢補位。因為係夜間定時跑，時間寬鬆，完全唔需要同限流鬥快——穩陣行晒就係最快。

模式三：持續流（全日不定時）

內容量大、來源分散（幾個系統都會生成）嘅團隊，適合行中央隊列模式：所有生成需求入一個內部隊列，一個提交器統一管理——佢一邊睇住在途數同 Remaining，一邊由隊列拉任務出嚟提交。呢個架構令所有系統共用一個「水龍頭」，限流永遠有單一負責人管理，唔會幾個系統互相踩。

三種模式冇高低，按你嘅量同來源揀。共同點係：限流管理要有一個清晰嘅負責者——唔係人人各自直接提交。

症狀速查表

實戰遇到狀況，先對一對呢張表：

監察同警報：唔好等出事先知

限流管理嘅進階版係「唔使撞牆」。三個簡單監察動作：一係記錄每個提交回應嘅 Remaining 值，畫成趨勢——如果成日貼近零，即係你嘅提交節奏長期頂住上限，要調整設計；二係統計 429 出現次數，突然增加通常代表有程序行為變咗；三係設警報閾值，例如一小時內 429 超過幾多次就通知負責人。限流數據係免費嘅系統健康指標，唔好嘥咗佢。

實戰：一套完整嘅限流處理流程

將上面全部夾埋，一個穩陣嘅 client 應該係咁行：

• 提交前：讀上一個回應嘅 Remaining，剩得少就主動慢落
• 撞 429 rate_limit_exceeded：讀 Retry-After，等足秒數，重試原請求
• 撞 429 in_flight_limit_reached：唔好重試，改為輪詢現有任務，等一個完成先重提
• 撞 403 monthly_cap_reached：呢個係設定問題唔係速度問題——檢查 key 上限同帳戶配額
• 全部重試設上限次數，超過就報警俾人處理，唔好無限循環

再加一條團隊守則：所有 client 嘅重試邏輯要有抖頓（jitter）——大家喺同一刻重試，只會一齊再撞。隨機抖少少，錯開重試時間，成個系統先會暢順。

常見問題 FAQ

429 兩種錯誤碼有咩分別？

rate_limit_exceeded 係你提交得太密（每分鐘窗口），等 Retry-After 秒數再試就得；in_flight_limit_reached 係你未完成嘅任務太多，重試冇用，要等現有任務完成騰空名額先再提交。

查詢任務狀態會唔會計限流？

唔會。限流只計成功嘅提交請求，查詢（GET）端點唔限流、冇限流 header，你可以按需要設計輪詢節奏。

撞在途上限之後即刻重試會點？

只會再撞一次，冇意義。在途數唔會因為你重試而減少——個任務要嘛完成、要嘛你主動取消。正確動作係去輪詢現有任務，見到一個完成，名額騰空咗先重提。

多開幾把 key 可以增加額度嗎？

每分鐘限流係按 key 計，多把 key 各自有自己嘅窗口額度，的確可以分散提交壓力；但「在途任務上限」按方案計、「沙盒每日 20 次」按帳戶計——呢兩層唔會因為多開 key 而增加，開多 key 都冇用。

Retry-After 應該點用？

收到 429 rate_limit_exceeded 嘅時候，回應會講明等幾多秒。老老實實等足（再加少少 buffer），然後重試同一個請求。即刻重發只會繼續佔用窗口，令情況更差。

可以調高每分鐘限流或者在途上限嗎？

每分鐘限流喺開 key 時可以設定；在途任務上限跟方案行——免費 3、入門 5、專業 10、工作室 20，要更高就升方案。

沙盒 key 每日 20 次用完點算？

等聽日，或者升級到專業方案——升級之後現有 key 會即時自動變全速，唔使重新開 key。記住嗰 20 次只計生成提交，查詢同下載隨便用。

批量 25 項會唔會當 25 次限流？

唔會。一個批量請求喺限流同在途上限都計一次。所以想喺有限額度入面搬最多文字，用盡批量係最有效率嘅做法。

[!CTA]

開把 key 試下你嘅限流策略

去 playground 感受生成流程，或者開沙盒 key 接駁測試——限流設計好咗，量再大都唔慌。