TTS 輪詢 Polling 完整指南：提交任務後點樣穩陣攞音檔

一句答你： TTS 輪詢（polling）就係提交語音任務之後，用同一個 job_id 定時查詢進度，等任務完成先攞音檔連結落嚟。整個流程得三步：提交、輪詢、下載——查詢端點唔計限流額度，音檔連結有效期由 1 小時到 7 日不等，過咗期就重新查詢攞過新連結。

Key Takeaways

• 粵語 TTS API 主流程係非同步：POST 提交任務，成功會回 202 同一個 job_id
• 之後用 GET 查詢同一個 job_id 追蹤狀態；查詢端點唔計入限流，可以放心輪詢
• 任務排隊或者處理中嘅時候，回應唔會有 audio_url；要等完成先會出現
• 已入素材庫嘅音檔連結有效期 1 小時；未入庫嘅直出連結有效期 7 日
• 在途任務有方案上限：免費 3 個、入門 5 個、專業 10 個、工作室 20 個
• 批量生成、聲音複製、SRT 字幕都要行非同步輪詢，冇同步捷徑

乜嘢係 TTS 輪詢？點解要輪詢？

第一次接觸語音合成 API 嘅朋友，好多時以為個流程同呼叫普通網頁服務一樣：傳一段文字過去，即刻就有音檔返嚟。現實係，生成一段自然流暢嘅廣東話語音需要時間——文字越長、句式越複雜，需要嘅處理時間就越長。如果成個請求要企喺度等佢做完先至回應，網絡一唔穩陣就容易斷線收場，之前嘅功夫白晒。

打個比喻：輪詢就好似去茶餐廳落單。你唔會企喺廚房門口乾等個菠蘿油出爐，而係攞張單號坐返落位，伙記見到幾多號就會叫幾多號。job_id 就係嗰張單號——你提交完任務就可以去做其他嘢，定時問一聲「好未呀？」，一叫號就上前攞嘢。成個過程你「企喺門口等」嘅時間係零，但個結果一樣準時到手。

輪詢模式仲有一個隱藏好處：責任清晰。提交係提交、查詢係查詢、下載係下載，三個動作各自獨立，任何一步出問題都可以單獨重做——提交失敗就改參數重提、查詢唔到就等等再問、下載斷咗就再拉一次連結，唔會好似一體化長請求咁，一斷就要成個流程由頭嚟過。

如果你未接觸過呢個 API，建議先睇一篇粵語 TTS API 快速上手教學，有咗基本概念先返嚟睇輪詢細節會順好多。

同步捷徑 vs 非同步主流程

呢個 API 其實有兩條路。第一條係同步捷徑：適合極短文本（300 字符以內）、用圖庫聲線或者聲線設計兩種模式，一次過就回音檔本身，唔使輪詢。第二條係非同步主流程：提交之後攞 job_id，再輪詢等結果。

幾時用邊條路？簡單講：同步捷徑係試音、互動場景先好用；所有正式整合——尤其係聲音複製、SRT 字幕、批量生成呢三類任務——一定要行非同步輪詢，因為呢啲任務冇同步選項。想知各模式點揀，可以參考廣東話 TTS 完全指南入面嘅模式比較。

三步曲：提交、輪詢、下載

第一步：提交任務，攞 job_id

用 POST 向任務端點（POST /v1/audio/jobs）提交請求，帶上你想讀嘅文字（1 至 500 字符）同埋聲線設定。文字超過 500 字符會直接被拒絕（回 text_too_long 錯誤），唔會幫你自動截斷，所以長稿要自己分段。提交成功，伺服器會回 202 狀態碼，回應入面就有一個 job_id——記住呢個編號，之後成個輪詢流程都靠佢。

常見嘅提交失敗原因有兩個：一是 API key 無效或者過期（回 401 invalid_or_expired_token），二是權限唔夠——例如你想用聲音複製，但 key 冇開啟對應權限（回 403 insufficient_scope）。呢啲提交階段嘅問題同輪詢無關，遇到就應該即刻修正設定，而唔係傻傻咁輪詢。API key 嘅申請同權限設定，認證入門一文有詳細教學。

第二步：定時查詢任務狀態

攞到 job_id 之後，用 GET 查詢端點（GET /v1/audio/jobs/{id}）去問進度。任務仲排緊隊（queued）或者處理中（processing）嘅時候，回應入面係唔會有 audio_url 嘅——呢個係設計上嘅正常行為，唔係出錯。當任務完成，回應就會帶埋音檔連結。

呢度有個對開發者好友好嘅設計：查詢端點唔計入限流額度，回應亦都冇限流相關 header。換言之，你嘅輪詢再密都唔會令你撞限流牆（當然都唔好誇張到一秒十幾次，意義唔大）。

第三步：攞 audio_url 下載音檔

見到 audio_url 就可以直接下載。呢條連結係預先簽署嘅，下載嗰下唔使再帶 API key，用瀏覽器、命令列定程式下載都得。落咗檔之後，記住自己管理好檔案——連結有時效（下一節詳講），唔好當佢係永久連結嚟用。

關於下載之後嘅格式同保存，MP3 下載教學有完整講解，包括點樣核對檔案完整性。

任務狀態逐個睇

輪詢嘅本質係讀狀態，所以你要清楚每個狀態代表咩、應該做咩：

呢張表入面最重要嘅一行係「完成」：audio_url 只會喺任務成功完成嗰刻先出現，其他任何狀態都唔會有連結。所以你嘅程式邏輯應該係「見到連結先行動」，而唔係「提交咗之後就預期有嘢攞」——混淆咗呢兩者，係新手最常見嘅出錯位。

輪詢節奏點樣定？

建議間隔同退避策略

幾耐查一次？冇硬性規定，但實務上有條好簡單嘅原則：短文本起碼等兩三秒先查第一次，長文本或者批量任務就由五秒開始。如果查咗仲未完成，將間隔乘大 1.5 至 2 倍，去到某個上限（例如 30 秒）就封頂。呢種叫指數退避（exponential backoff）嘅做法，可以喺「反應快」同「唔嘥請求」之間取得平衡。

點解唔建議固定好密咁查？因為查詢雖然唔計限流，但每一次查詢都係你自己系統嘅一次網絡往返——太密嘅輪詢會令你自己嘅伺服器同日誌都受壓，而回報通常係零：任務幾時好，唔會因為你查多幾次而快一秒。一個好嘅節奏係「完成之後一兩個查詢週期之內就發現」，夠快、又唔使發瘋。

同一時間，記住設定一個整體超時上限。例如一段 500 字符嘅文本，你預計一兩分鐘內應該完成；如果輪詢咗五分鐘都未好，就唔好無了期等落去——要麼報警提示人工檢查，要麼用 DELETE 端點（DELETE /v1/audio/jobs/{id}）取消個任務再重新提交。

查詢唔計限流，提交先計

限流只計成功嘅生成提交（預設每 key 每分鐘 60 次，開 key 嗰陣可以調），查詢端點完全唔計數。所以你嘅輪詢策略再進取，都唔會令你撞 429 rate_limit_exceeded。真正要管理嘅反而係在途任務數量——下一節講。

在途任務上限：按方案分級

除了每分鐘限流，仲有一個在途任務上限：即係你提交咗但未完成嘅任務數量。超咗上限，提交會回 429 in_flight_limit_reached，回應會話你知目前上限同活躍數量。

設計輪詢流程嗰陣，要將呢個上限考慮入去：任務完成一個，名額就騰空一個。如果你想一口氣提交大量任務，就要確保完成速度追得上提交速度，否則就會撞上限。批量內容生產嘅排隊策略，可以參考大量內容生成 workflow嘅完整拆解。

音檔連結時效：1 小時 vs 7 日

攞到 audio_url 之後唔係一勞永逸。連結分兩種情況：

實務建議：生成完就盡快落檔，唔好靠連結做長期分發。如果連結過咗期，只需要用同一個 job_id 再查詢一次，就會攞到條新連結——前提係個任務紀錄仲在。每個方案嘅生成紀錄保留期唔同（免費 15 日、入門 60 日、專業 90 日、工作室 120 日），有需要回頭攞舊檔，都要喺保留期內搞掂。

異常狀態處理：失敗、取消、過期

任務失敗或者取消點算

任務失敗（failed）或者被取消（cancelled）嘅時候，同樣唔會有 audio_url。遇到失敗，第一步係睇清楚回應入面嘅錯誤資訊，判斷係文字內容問題（例如有字符處理唔到）定係系統問題；前者要改稿重提，後者可以原稿重試。想中途喊停，就用 DELETE 端點取消個任務，騰返個在途名額出嚟。

全部錯誤碼嘅意思同處理方法，錯誤碼對照一文有完整對照表，建議儲定起底。

連結過期同重試

上面提過，連結過期就重新查詢。最常見嘅陷阱係：你將 audio_url 轉發俾客戶或者存入自己嘅系統，幾日後先發現連結失效。正確做法係落檔存自己嗰度，或者需要時重新查詢攞新連結，而唔係長期依賴原連結。

批量任務一樣用輪詢

批量生成嘅本質同單條任務一樣：提交、等、攞檔。幾個批量特有嘅規矩要記住：

• 每個批量請求最多 25 項，超過會回 too_many_items
• 驗證係全有或全無：有任何一項格式唔啱，成個請求都唔會受理（回 invalid_items），所以提交前要逐項檢查
• 批量係專業及以上方案嘅功能，免費同入門方案提交批量會回 batch_requires_pro，唔會扣費
• 一個批量請求喺限流同在途上限都係計一次，唔係逐項計

批量場景下，輪詢節奏嘅設計多咗一層考慮：你唔係等一個任務，而係等一批。建議做法係同一個輪詢迴圈入面追蹤晒成批任務嘅狀態，完成一個落檔一個，全部完成先算收工。咁樣唔單止下載時間攤勻咗，中途想喊停都知剩返邊啲未好。

沙盒環境嘅輪詢

免費同入門方案嘅用戶可以開沙盒 key（sk_test_ 前綴）先行測試接駁。沙盒環境嘅輪詢同正式環境完全一樣——重點係每日額度嘅計法：沙盒 key 每日 20 個生成提交，只計提交，查詢同下載完全唔計。即係話你可以喺沙盒入面盡情練習輪詢流程、測試你嘅退避策略同超時處理，唔使擔心消耗提交額度。

呢個係好實際嘅建議：正式寫整合之前，先用沙盒環境手動行一次「提交—查詢—下載」三步，親眼睇下每個狀態嘅回應長咩樣，之後先將流程自動化。見慣咗正常嘅回應，異常先會一眼認出。

輪詢實用檢查清單

開工前最後過一次：

• 提交之後有冇攞到 job_id？冇嘅話係提交層面出咗問題
• 輪詢間隔有冇退避？有冇整體超時？
• 程式邏輯係咪「見到 audio_url 先行動」？
• 攞到連結之後幾快落檔？知唔知條連結屬於 1 小時定 7 日嗰種？
• 有冇記低每個 job_id 對應嘅稿件同用途？日後對數同重做都靠佢
• 失敗重試有冇上限？唔會無了期燒配額？
• 撞在途上限嗰陣，有冇等任務完成再重提嘅機制？

常見問題 FAQ

輪詢要查幾耐先會完成？

視乎文本長度同當前排隊情況，短文本通常幾秒到就完成，長文本同批量任務需要耐啲。建議由兩三秒開始查，用退避策略拉長間隔，並且設定整體超時，唔好無了期等。睇到 queued 好耐都唔使慌，排隊係正常現象。

查詢太密會唔會被限流？

唔會。限流只計成功嘅提交請求，查詢端點（GET）唔計入限流額度，所以輪詢本身唔會令你撞 429。不過都唔建議瘋狂狂查，正常間隔已經足夠。

音檔連結過期咗點算？

用同一個 job_id 重新查詢一次，就會攞到條新連結。已入素材庫嘅音檔連結有效期 1 小時，直出連結 7 日。最好嘅習慣係生成後盡快落檔存好。

同步捷徑幾時先用得？

只適合 300 字符以內嘅短文本，而且只支援圖庫聲線同聲線設計兩種模式；聲音複製、SRT 字幕、批量都冇同步選項，一律要行輪詢。

可以取消進行中嘅任務嗎？

可以。用 DELETE 端點帶上 job_id 就可以取消任務，騰返個在途名額。取消咗嘅任務唔會有音檔出。

輪詢會唔會消耗生成配額？

唔會。配額按生成嘅字符量計，查詢同下載都唔計入配額；沙盒 key 嘅每日生成次數限制亦都只計提交，查詢同下載唔計。

批量任務都係用同樣輪詢方式嗎？

係。批量提交成功之後一樣用查詢端點追蹤，完成一個落檔一個，全部完成先算收工。記住單個批量請求上限 25 項、驗證全有或全無，而且係專業方案以上嘅功能。

[!CTA]

親手行一次提交—輪詢—下載

開個免費帳戶試晒成個流程，或者直接去 playground 貼稿出聲，感受非同步生成嘅流暢度。