Node.js 粵語 TTS cookbook：串接 API 由零到出聲完整教學

一句答你： 想用 Node.js 整廣東話文字轉語音，最直接嘅路係行 REST API：提交文字任務、攞返 job id、輪詢狀態、下載音頻。單次請求可以入 1 至 500 個字符，每把金鑰預設每分鐘 60 個計費請求限額，免費帳戶開戶就有每月 5,000 字符（月月重置）試玩。呢篇 cookbook 由申請金鑰、第一次請求、錯誤處理，到批量同成本管理，逐步教晒。

Key Takeaways

• 粵語 TTS 行異步流程：POST 提交任務回 202 同 job id，再用 GET 輪詢狀態，完成先有音頻連結可以下載。
• 單次文字上限 500 字符，超額會成個請求被拒（唔會自動截斷），長文一定要預先拆段。
• 每把金鑰預設限流每分鐘 60 個計費請求；查詢類請求唔計數，撞限流會回 429 並附 Retry-After 秒數。
• 免費帳戶有每月 5,000 字符（約 21 分鐘音頻）；免費同入門方案另可開沙盒金鑰，每日 20 個生成提交試接。
• 任務有在途上限：免費 3 個、入門 5 個、專業 10 個、工作室 20 個，並行生成要自己排隊管理。
• 批量生成一次最多 25 個項目，屬專業同工作室方案功能，一次批量只計一次限流。

點解 Node.js 開發者要識粵語 TTS

香港嘅數碼產品要落地，聲音好大程度決定咗用戶覺得你「係咪自己人」。同一段通知文字，用其他語言嘅語音讀出嚟，香港用戶嘅投入感即刻打個折；用廣東話讀，先至似日常講嘢。呢個就係點解愈來愈多本地團隊將粵語語音合成直接砌入自己嘅 Node.js 服務。

實際場景唔少：電話系統嘅語音通知、網上課程旁白、內容平台嘅文章朗讀、購物網站嘅商品介紹、內部系統嘅警報廣播，甚至社群機械人嘅回覆語音。呢啲場景有個共通點：文字係動態嘅，冇可能逐句搵真人預錄，唯有交俾語音引擎即場生成。

舉個例：一個網上訂菜平台，每晚要為第二日嘅訂單出一段確認語音；一間保險公司，想將保單重點逐日更新成語音摘要；一個自媒體創作者，想將每篇網誌自動變成有聲版本。呢啲嘢全部可以由一個定時運行嘅 Node.js 工作流程搞定——文字入、音頻出，全程唔使人手守候。

同時，做慣後端嘅人都知道，接入一項外部服務最怕係流程拐彎抹角。粵語 TTS 嘅 API 行異步模式：提交任務之後唔會即刻有成品，要輪詢狀態先攞到音頻。呢種「提交、等待、收割」嘅流程，同 Node.js 嘅 async/await 同 Promise 天然夾到合晒，幾十行程式碼就寫得到一條完整嘅生成流程，冇多餘嘅 SDK 負擔。想先了解粵語語音合成嘅基本原理同整體玩法，可以睇吓廣東話 TTS 完全指南，再返嚟跟本篇動手。

開工前準備：金鑰、額度同工具

申請 API 金鑰

喺港嘢帳戶入面建立一把 API 金鑰。正式金鑰以 sk_live_ 開頭，沙盒金鑰以 sk_test_ 開頭。金鑰嘅原始字串只會喺建立嗰刻顯示一次，之後系統只會保留加密指紋，所以一拿到手就要存入環境變數，千祈唔好 commit 入 git。

權限方面，一般生成任務用預設嘅 tts:generate 就夠；日後要接聲音複製功能，先至需要另外開 tts:clone。建立金鑰嗰陣可以順手設定每分鐘限流（預設 60）同月度字符上限，方便唔同環境用唔同配額。

搞清楚你手上嘅額度

• 免費帳戶：開戶每月有 5,000 字符，月月重置。按每分鐘音頻約 240 字符估算，5,000 字符大概出到 21 分鐘音頻，足夠你完整行通成條流程。
• 沙盒金鑰：免費同入門方案都可以開 sk_test_ 沙盒金鑰試接，每日 20 個生成提交。計數只計「提交生成」呢一下，輪詢狀態同下載音頻都唔計，用嚟開發調試好抵。升級到專業方案之後，原有金鑰會即時自動轉做全速模式。
• 付費方案：入門每月 200,000 字符（HK$128）、專業 600,000（HK$338）、工作室 1,400,000（HK$688），配額每個帳單週期重置，同網頁版共用同一筆額度。

工具方面

Node.js 18 或以上已經內建 fetch，呢篇教學唔使裝任何額外 HTTP 函式庫。金鑰建議用環境變數或者 .env 檔管理。想由註冊一步步行到第一次出聲，可以配合粵語 TTS API 快速上手一齊睇。

第一次請求：提交生成任務

生成入口係 POST /v1/audio/jobs。請求內容最少兩個欄位：text 係要讀嘅文字（1 至 500 字符），voice 係聲線嘅英文識別碼。

const res = await fetch("https://canto-gen.com/v1/audio/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.CANTO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "大家好，歡迎收聽港嘢嘅粵語語音示範。",
    voice: "sum",
  }),
});

if (res.status !== 202) {
  throw new Error("提交失敗，HTTP " + res.status);
}
const data = await res.json();
console.log("job_id:", data.job_id);

幾個位要留意：

• voice 用嘅係英文識別碼，唔係中文名。識別碼係穩定嘅 ASCII 字串，例如心妍係 sum（女性、成人聲線），介面上嘅中文名只係顯示用。完整聲線目錄可以用 GET /v1/voices 攞，連每把聲線嘅試聽片段都有。
• 成功提交會回 HTTP 202，內容帶 job_id。記住呢個 id，之後輪詢就靠佢。
• 文字長度一定要喺 1 至 500 字符之間，超額會回 400 text_too_long，成個請求被拒，系統唔會幫你截短，所以提交前最好自己檢查一次長度。

輪詢狀態同下載音頻

任務唔會即時完成。用 GET /v1/audio/jobs/{id} 輪詢，狀態會由 queued 去 processing，完成時變 completed，先至有 audio_url 可以下載。

async function waitAudio(jobId) {
  const url = "https://canto-gen.com/v1/audio/jobs/" + jobId;
  const headers = { "Authorization": "Bearer " + process.env.CANTO_API_KEY };

  for (let i = 0; i < 60; i++) {
    const res = await fetch(url, { headers });
    const job = await res.json();
    if (job.status === "completed") return job.audio_url;
    if (job.status === "failed" || job.status === "cancelled") {
      throw new Error("任務完結但未成功：" + job.status);
    }
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("輪詢超時");
}

下載嗰下有個貼心位：audio_url 本身已經係預簽連結，下載唔使再帶 Authorization header，直接 GET 就得。連結有時效：由生成端直接出嘅連結 7 日內有效，已入音頻庫嘅就 1 小時；過咗期重新查詢任務一次，攞返條新連結就OK。另外，任務仲排緊隊或者處理中、以至 failed 同 cancelled 狀態，回應入面係唔會有 audio_url 嘅，程式要處理埋呢啲狀態先至穩陣。

輪詢節奏建議兩三秒一次。查詢類請求唔計入限流，所以輪詢本身唔會食你嘅每分鐘配額，但都冇必要密過半秒一次。

錯誤處理同重試策略

Production code 最緊要識得優雅咁跌倒。常見錯誤碼同對應做法：

重試要有紀律：429 就跟 Retry-After 秒數等；其他 5xx 可以指數退避（1 秒、2 秒、4 秒咁樣遞增），設個最大重試次數（例如 5 次），超過就記低等人手跟。4xx 類錯誤重試都冇用，直接報錯俾上層處理。完整嘅錯誤碼清單同每個 code 嘅詳細解釋，可以睇TTS API 錯誤碼對照。

另外記得埋好日誌：每次提交記低 job_id、聲線、字符數同時間戳，每次失敗記低錯誤碼同處理結果。呢啲紀錄唔單止方便排查，仲可以同月度配額對數，一睇就知邊條流程食量最大、有冇異常。

長文拆段：由 500 字符限制到流暢朗讀

500 字符上限聽落細，其實夠讀成兩分幾鐘。真正嘅功力在於點樣拆得靚：

• 以自然邊界切：段落、句子、逗號位都係好嘅切割點，唔好喺詞語中間斬開。
• 每段長度均勻：盡量每段 200 至 400 字符，太短會令段同段之間嘅停頓怪怪哋，太長就貼近上限冇緩衝。
• 控制並行：每個方案有在途任務上限（免費 3、入門 5、專業 10、工作室 20），超額會回 429。寫個簡單嘅任務佇列，保持喺上限以下跑，完成一件先提交下一件。
• 順序拼合：記低每段嘅提交順序，下載完之後按序處理，或者逐段餵俾播放器。

實作上一個簡單做法係寫個拆段函式：先用句號同問號切句，再將句子逐句裝入緩衝區，裝到接近 400 字符就封一段；每段各自提交、各自輪詢，最後按序拼合。想深究旁白稿嘅分段節奏同語氣鋪排，建議直接喺網頁版試讀幾個版本，聽住嚟微調標點，會快過齋睇文件。

揀聲線同演繹風格：令把聲夾個品牌

揀聲線唔好求其。同一句歡迎詞，用沉穩嘅成人聲線同用活潑嘅年輕聲線，聽嘅人感受完全唔同。建議先喺聲線圖庫逐把試聽，記低兩三把候選，再攞自己真實嘅文案（唔係示範句）逐把讀一次，聽吓邊把最夾你嘅品牌語氣。

團隊合作仲有一個慳位：同時用網頁版同 API 揀聲線。網頁版試聽快，適合非技術同事參與揀聲；揀定之後先將識別碼寫入 API 呼叫，來回溝通成本低好多。

API 層面有幾樣嘢可以玩：

• 演繹風格：每把聲線支援嘅風格可以用 GET /v1/voices/{slug}/styles 查到，提交任務嗰陣指定，等同一把聲可以讀出唔同場合嘅味道。
• 情緒同指示：生成時可以帶情緒設定同自由指示，例如要求讀得輕快啲或者嚴肅啲，適合同一套系統要分場合轉語氣嘅場景。
• 聲線設計：用性別同年齡兩個結構條件可以設計出新聲線，不過留意呢類生成係逐次請求計，唔會儲存成可以重用嘅固定聲線。

想知點樣組合呢啲參數先出到最地道嘅粵語，點樣用 API 生成地道粵語語音一文有完整嘅參數講解。

批量生成：一次過交幾十段稿

如果你有成批固定文案要出聲（例如幾十條產品介紹、幾十題練習旁白），可以用批量方式：同一個 POST /v1/audio/jobs 入面帶 items 陣列，一次過最多 25 個項目。

幾條規則要記住：

• 批量係專業同工作室方案功能。免費或者入門方案提交 items 會回 403 batch_requires_pro，零提交、零扣費，唔會收你錢。
• 驗證係全有或全無：任何一項無效，成批回 400 invalid_items，所以提交前要逐項檢查。
• 超過 25 項會回 400 too_many_items，分批交就得。
• 一次批量請求只計一次限流，唔係逐項計，所以批量其實係慳限流嘅好方法。

批量嘅完整設計考量——點樣分批、點樣管理失敗重交、點樣對齊檔名——批量生成粵語語音 workflow一文有全套流程。

成本同配額管理

API 同網頁版共用同一筆月度配額，所以團隊有人喺網頁版玩緊，API 嗰邊嘅餘額就會同步減，做用量監控嗰陣要記住呢一點。

成本估算好簡單：每分鐘音頻約 240 字符。即係話：

• 10 分鐘旁白約 2,400 字符（入門約 HK$1.54、專業約 HK$1.35、工作室約 HK$1.18）
• 5,000 字符約 21 分鐘；反過嚟講，300 分鐘嘅長期內容大約 72,000 字符
• 100,000 字符約 417 分鐘，即大約 7 小時音頻

配額用完冇超額收費，需要加量可以買字符包，四檔劃一每千字符 HK$0.80，最小 HK$50 有 62,500 字符。金鑰層面仲可以設定月度字符上限做保險，防止某條流程爆走食晒成個帳戶嘅額度。各方案嘅詳細價目同單價換算，廣東話 TTS 價錢點計有逐項拆解。

常見問題 FAQ

Node.js 要邊個版本先接到？

Node.js 18 或以上已經內建 fetch，直接用就得，唔使裝 axios 之類嘅函式庫。再舊嘅版本就要自行加 HTTP 客戶端先至方便。

500 字符上限，成篇文章點算？

拆段。以標點或者段落做邊界切開，逐段提交，記住每個方案嘅在途任務上限（免費 3 個），用佇列控制在限額內跑，最後按序拼合或者逐段播放。

免費可以試到咩程度？

每月 5,000 字符，約莫 21 分鐘音頻，夠行通全條流程；免費同入門方案仲可以開沙盒金鑰，每日 20 個生成提交慢慢調試，輪詢同下載都唔計數。換句話講，由第一次請求到行通錯誤處理，基本上唔使蝕底。

可以順便攞字幕檔嗎？

可以。提交任務嗰陣開埋 SRT 選項，任務完成除咗音頻連結，仲會有對應嘅字幕檔，適合影片配音流程。留意呢個功能同樣行異步軌，要跟返同一套輪詢流程攞結果。

撞正 429 應該點做？

兩種 429 要分清楚：rate_limit_exceeded 係每分鐘限流，照回應入面嘅 Retry-After 秒數等完再重試；in_flight_limit_reached 係在途任務滿，等現有任務完成先好提交新的。兩種都唔好即刻狂重試。

音頻連結可以擺幾耐？

由生成端直接出嘅連結 7 日內有效，已入音頻庫嘅 1 小時。連結過期就重新查詢任務攞新連結。上線的話，建議下載返自己嘅儲存做長期備份。生成任務紀錄按方案保留 15 至 120 日，唔同方案日數唔同，要做審計就記得及時歸檔。

聲線點指定？識別碼同中文名有咩分別？

API 用 ASCII 識別碼做穩定標記（例如 sum 代表心妍），中文名只係介面顯示。用 GET /v1/voices 攞完整目錄，每把聲線都有試聽片段，寫死識別碼之前先聽清楚。

[!CTA]

用 Node.js 出你第一句廣東話

開個免費帳戶，用開戶每月 5,000 字符，幾分鐘就行通由提交到下載嘅整條流程。