粵語 TTS API：一行 code 加廣東話語音

一句答你：粵語 TTS API 嘅核心就係兩個動作 —— 提交（POST 攞 job_id）同輪詢（GET 攞音檔）；攞到 API key 之後，一行提交就出到廣東話語音，短過 300 字符仲可以直接同步攞音檔，唔使寫複雜嘅串接。想幫產品加廣東話語音，最快嘅路係由呢兩個動作開始。

市面上唔少語音 API 都聲稱支援中文，但「中文」同「粵語」係兩回事：讀音、語氣、中英夾雜處理，全部唔同。如果你要為 app、客服、內容平台加入地道廣東話，就要揀一個粵語原生嘅 API。呢篇會由 API key 講起，逐步拆解提交、輪詢、同步捷徑、錯誤處理同實際應用。想先睇完整上手流程，可以睇《粵語 TTS API 快速上手》。

Key Takeaways

• 主流程只有兩步：POST 提交（攞 202 + job_id）→ GET 輪詢（攞音檔 URL）
• 短過 300 字符、用圖庫聲線或者聲線設計，可以直接同步攞音檔（200）
• 提交文字 1–500 字符；超過會被拒（400 text_too_long），唔會自動截斷
• 三種生成模式：voice（用 slug）、design（性別＋年齡）、clone（參考音頻）
• 音檔 URL 有時效：已整理嘅 1 小時、直接由生成出嘅 7 天；過期就重新輪詢
• 預設限流每 key 每分鐘 60 次；讀取類請求唔限流

第一步：攞 API key

去港嘢嘅帳戶設定建立 API key。幾個要點：

• Key 前綴：正式 key 係 sk_live_ 開頭，沙盒 key 係 sk_test_ 開頭。
• 只顯示一次：原始 key 建立之後只顯示一次 —— 記得即刻複製。伺服器側只儲存雜湊值，唔會保存原文。
• Scopes：預設 scope 係 tts:generate（圖庫聲線同聲線設計生成，加所有讀取）。聲音複製要額外加 tts:clone。
• 沙盒 key：免費同入門方案可以開 sk_test_ 沙盒 key，限每日 20 個生成請求（計數係 per-account，跨所有 key 共享）。升級至專業方案後，現有 key 會即時自動變全速。

建立 key 嘅參數（camelCase）包括：name（必填，最多 64 字）、scopes、monthlyCreditCap（唔填 = 無上限）、rateLimitPerMin（預設 60）、expiresAt（ISO 未來時間）、testMode（true 出沙盒 key）。API key 認證嘅詳細排查，可以睇《TTS API Key 認證入門》。

主流程：提交同輪詢

提交：POST 提交任務

最核心嘅一行，就係提交任務：

curl -X POST https://canto-gen.com/v1/audio/jobs \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，歡迎使用粵語語音。","voice":"sum"}'

成功會回 202，body 有一個 job_id。呢個 job_id 就係之後攞音檔嘅鎖匙。

請求 body 嘅主要欄位：

輪詢：GET 攞結果

提交之後，用 job_id 輪詢：

curl https://canto-gen.com/v1/audio/jobs/JOB_ID \
  -H "Authorization: Bearer sk_live_xxx"

任務完成之前，audio_url 唔存在（排隊中、處理中、失敗、取消都係）。完成之後，回傳會有一個已簽名嘅音檔 URL —— 下載唔使再帶 auth header，因為 URL 本身已經簽好。

同步捷徑：短句直接攞音檔

如果文字 300 字符以內、而且用圖庫聲線或者聲線設計，可以行同步捷徑：直接回 200 加音檔 bytes，唔使輪詢。要注意：

• 同步唔支援聲音複製 → 會回 400 clone_not_supported_sync
• 同步唔支援 SRT → 會回 400 srt_not_supported_sync

所以「一句提示」「一句歡迎語」呢類短內容，同步最方便；長文同需要字幕嘅內容，就行異步。

點解要揀粵語原生 API

市面好多語音 API 都支援「中文」，但粵語唔係普通話嘅方言變體咁簡單。實際落地時，粵語原生同「中文通用」嘅差距會喺三個位爆出嚟。

讀音

粵語有九聲六調，同普通話四聲系統完全唔同。加上成語、地名、多音字嘅約定俗成讀法，唔係「用普通話讀中文」可以蒙混過關。一個字讀錯，喺粵語聽眾耳中好刺耳。粵拼同聲調系統嘅基礎，可以睇《廣東話 TTS 完全指南》嘅語言學部分。

語氣

粵語嘅語氣詞（喇、囉、啦、咩、啩）係日常對話嘅靈魂。語氣詞讀得唔自然，成句聽落就「唔似香港人講嘢」。呢點係判斷一個引擎係咪真粵語嘅試金石，詳見站內關於語氣詞嘅文章。

中英夾雜

香港人講嘢成日中英夾雜（「個 file send 咗未？」）。粵語原生引擎識得喺粵語句子入面自然讀英文詞，通用引擎好易讀到怪腔怪調。

所以揀 API 唔應該只睇「有冇中文選項」，要睇「係咪粵語原生」。

由第一個 request 到上線：完整時序

第一階段：驗證（半日）

攞沙盒 key，去 playground 聽聲線，揀一兩把。再寫一個最簡單嘅提交＋輪詢腳本，確認成條鏈跑得通。呢個階段嘅目標係「確認可行」。

第二階段：整合（幾日）

將提交同輪詢包成你自己嘅 function／service。處理好錯誤（尤其係限流同文字過長）、重試（指數退避）、同音檔儲存（攞到即刻下載）。呢個階段嘅目標係「穩定整合」。

第三階段：生產化（一至兩週）

加快取（同一段內容唔好重複生成）、加併發控制（尊重在途任務上限）、加監控（提交成功率、輪詢次數、失敗原因）。呢個階段嘅目標係「可維運」。

第四階段：規模化（持續）

用批量生成處理大量內容，用字符包應付配額爆額，用月度字符上限控制成本。呢個階段嘅目標係「可預算」。

四個階段唔使一次過做齊，但次序係「先驗證、後整合、再生產化、最後規模化」。

三種生成模式點揀

要留意：design 同 clone 出嘅聲線係 per-request —— 唔會儲存成可重用嘅資產。如果你要一個長期穩定嘅品牌聲線，用圖庫聲線（slug）最穩陣。

聲線識別用 ASCII slug（例如 sum 係心妍，female，adult），中文名只係介面顯示。想睇齊所有聲線同試聽，用 GET /v1/voices；想知某聲線支援咩演繹風格，用 GET /v1/voices/{slug}/styles。

音檔 URL 時效同下載

URL 過期唔使慌，重新輪詢一次就有新嘅已簽名 URL。所以生產環境最好係「攞到 URL 即刻下載並存落自己嘅儲存」，而唔係將 URL 當長期連結周街派。

錯誤處理：最常撞到嘅幾個碼

錯誤處理嘅實戰做法，可以睇《TTS API 錯誤碼對照》。

限流同並行上限

限流

預設每個 key 每分鐘 60 次，計成功嘅計費請求。回應 header 有 X-RateLimit-Limit / -Remaining / -Reset。撞限流會回 Retry-After 秒數。讀取類請求（輪詢、攞聲線目錄）唔限流，亦冇呢啲 header。

在途任務上限

超過會回 429 in_flight_limit_reached。批量一次請求只計一次限流，唔係每項計。

批量生成

要一次出多段語音，用批量：

• 一次最多 25 個 request body；超過回 400 too_many_items。
• 驗證係全有或全無 —— 任何一項無效，成批回 400 invalid_items。
• 批量係專業／工作室專屬；其他方案帶 items 會零提交、零扣費。

呢個設計令「一整批句子一次過出」成為可能，例如產品目錄、站名表、通知模板。

配合字幕同快取：兩個實用延伸

SRT 字幕一併出

提交時將 srt 設為 true，就會行一條異步軌，一併產生字幕檔。呢個對於「要出片」嘅場景好實用：同一批文字，一出語音、一出字幕，兩條軌時間軸對得上。要留意同步捷徑唔支援 SRT（會回 400 srt_not_supported_sync），所以需要字幕就一定行異步。SRT 嘅時間軸對齊技巧，可以睇《TTS 加 SRT 字幕》。

快取：唔好重複生成同一段

好多 app 嘅語音內容係重複嘅（固定提示、選單、招呼語）。做法係喺自己嗰邊加一層快取：同一段文字＋同一個聲線，生成一次之後存低音檔，下次直接攞本地副本，唔再提交。呢個做法有兩個好處：一，慳配額（唔使重複扣字符）；二，快（唔使等生成）。快取嘅有效期同更新策略要自己定 —— 一般「聲線唔變、文字唔變，就唔使重出」。

呢兩個延伸加起上嚟，令 API 由「生成工具」變成「內容產線嘅一環」。

實際應用場景

App 加入語音

最短嘅整合：提交一句歡迎語（同步捷徑），回音檔直接播放。要動態內容（例如用戶名、數字）就即場組句再提交。

客服熱線選單

將選單句子用同一把聲線批量生成，改稿時只重出受影響句子。呢種「模板＋變數」做法，可以睇站內關於模板化廣播製作嘅文章。

內容平台批量出聲

文章、通知、產品介紹批量生成語音版。以約 240 字符 ≈ 1 分鐘語音估算，成本可以預算。

Agent／MCP 接入

想畀 AI agent 直接攞聲，行 MCP 接入。詳細可以睇《MCP 粵語語音》。

內部工具同自動化

除咗 app 同客服，API 亦可以接落內部工具：例如表單提交之後自動出語音通知、每朝自動生成廣播稿音檔、或者由 Google Sheet 批量出多語言版本。呢類「唔使寫成套 app」嘅自動化，通常用 no-code 平台（例如表單工具、自動化工作流）接一個 HTTP 提交就做到。

關鍵係認清 API 嘅兩個基本動作 —— 提交同輪詢。任何工具，只要識發 HTTP 請求，就接得落。

OpenAPI 同互動文件

想睇齊所有 endpoint 同 schema：

• Spec：/v1/openapi.json（OpenAPI 3.1，免 auth，CORS *）
• 互動文件：/v1/docs

主要 endpoint 一覽：

要留意：API 目前未公開發布，喺 deployment protection 後面。如果 curl 撞到 hosting auth challenge，係撞到保護閘，唔係 API 壞。

五個落地注意事項

一、唔好將音檔 URL 當長期連結

URL 有時效（1 小時或 7 天）。正確做法係攞到即刻下載，存落自己嘅儲存同 CDN。將上游 URL 存入資料庫再派發，遲早會爆。

二、提交之前先量字數

500 字符係硬限制，超過會 400 text_too_long，唔會自動截斷。所以喺自己嗰邊加一層字數檢查同自動切段，避免無謂嘅失敗請求。

三、輪詢要退避，唔好狂問

固定間隔狂輪詢，會浪費你嘅請求同上游資源。做法係由短間隔開始（例如一秒），逐步拉長（指數退避），設一個上限。詳細策略見站內輪詢指南。

四、尊重在途任務上限

撞到 in_flight_limit_reached 唔係「API 壞」，而係你自己嘅併發超過方案上限。做法係喺應用層加任務隊列，令同一時間嘅在途任務數控制喺上限之內。

五、計費請求先計限流

限流係計成功嘅計費請求，讀取類（輪詢、攞目錄）唔計。所以「狂輪詢」唔會加你嘅計費負擔，但仍然應該用合理嘅退避策略 —— 因為你嘅輪詢請求本身有網絡成本。

呢五點睇落係細節，但正係「demo 跑得通」同「生產穩定」之間嘅距離。

常見問題 FAQ

「一行 code」真係做得到嗎？

做得到 —— 如果你只想出一句短語音。一行提交（POST）＋一個輪詢（GET），就攞到音檔。真正要寫多啲 code 嘅，係錯誤處理、重試、快取同併發控制呢啲生產級需求。但如果只求「跑得通、聽得到」，兩個動作就足夠。

點解要輪詢？冇 callback 咩？

呢個 API 係輪詢（polling）型：提交攞 job_id，之後主動問狀態。冇 webhook callback，所以如果你想事件驅動，要喺自己嗰邊自建一層回調（提交時記錄 job_id，背景定時輪詢，完成就觸發你嘅流程）。輪詢嘅節奏同退避策略，站內有專講輪詢節奏同退避策略嘅文章。

提交長文點算？500 字符限制好窄。

單次提交上限係 500 字符，所以要自己按段落切開。實務做法係按句或者按段切，逐段提交，再喺自己嗰邊拼接音檔。好處係逐段可以獨立重出，改一段唔使動全文。以 240 字符 ≈ 1 分鐘估算，500 字符大約兩分鐘語音。

沙盒 key 同正式 key 有咩分別？

沙盒 key（sk_test_）限每日 20 個生成請求，計數係 per-account 共享，只計生成提交，輪詢同下載唔計。正式 key（sk_live_）冇呢個每日限制。免費同入門方案用沙盒 key 試接；升級專業後，現有 key 即時自動變全速。

要唔要自己處理音檔儲存？

建議要。因為音檔 URL 有時效（1 小時或 7 天），生產環境最好攞到就即刻下載存落自己嘅儲存，用自己嘅 CDN 派發。咁樣唔會因為 URL 過期而影響用戶。

三個模式之中，邊個最適合我？

想要一個穩定、可重用嘅品牌聲線 → 用圖庫聲線（voice）。想按屬性（性別、年齡）試聲 → design。要用特定一把聲 → clone。因為 design 同 clone 出嘅聲係 per-request，唔會儲成可重用資產，長期用途建議用圖庫聲線。

成本點計？

月配額同 playground 1:1 共用（API 同 playground 共用同一份額度）。入門 HK$128／月包 200,000 字符（約 HK$0.64／千字符），專業 HK$338／月包 600,000，工作室 HK$688／月包 1,400,000。冇超額收費 —— 配額用完就完，要加量就買字符包（四檔同價 HK$0.80／1K，最小包 HK$50 = 62.5K 字符）。開戶送每月 5,000 字符（月月重置，約 21 分鐘語音）。

結語：由兩個動作開始

粵語 TTS API 睇落好多欄位、好多錯誤碼，但核心其實得兩個動作：提交同輪詢。搞掂呢兩步，你就出到廣東話語音；之後加嘅錯誤處理、重試、快取、併發控制，全部都係喺呢個核心之上加固。與其一次過研究齊所有細節，不如先用沙盒 key 跑通一句話，再逐步加料 —— 呢個次序，係由「睇得明」到「真係用」最穩嘅路。

[!CTA]

一行提交，出廣東話語音

攞 key、提交、輪詢 —— 三步跑到出聲。開戶即享每月 5,000 字符，去 港嘢 Playground 或睇 /v1/docs 即刻試。