粵語語音 Bot 建置指南：由揀聲線到自動出音頻嘅六步流程

一句答你： 起一個識講廣東話嘅語音 Bot，主線流程六步：定場景 → 寫口語稿 → 揀聲線（鎖 slug）→ 接生成 API → 處理錯誤同限流 → 存檔交付；開發期用沙盒金鑰試接，上線先轉正式金鑰。

Key Takeaways

• 對白稿一定要口語化——書面語讀出嚟一耳假
• 聲線用圖庫 slug 鎖死，跨對話先一致；design／clone 係單次性唔存底
• 生成係任務式：提交（202）→ 輪詢 → 下載預簽網址
• 音頻網址有時效（1 小時／7 日兩級），完成即刻下載
• 開發期用沙盒金鑰：每日 20 次生成，輪詢同下載唔計數
• 上線前過一次檢查清單：限流、在途上限、錯誤後備、降級

語音 Bot 同文字 Bot 差在邊？

文字 Bot 出字，語音 Bot 出聲——多咗三個工序：聲線揀選、音頻生成、音頻交付。背後嘅對話邏輯（意圖理解、狀態管理）可以完全共用，所以如果你已有文字版，轉語音版嘅增量工作主要就係「講嘢」嗰一環——即係呢篇嘅主題。

以下流程根據 2026-10 嘅公開文件。由零認識港嘢語音生成嘅整體面貌，可以配住廣東話 TTS 完全指南一齊讀。

由零認識港嘢語音生成嘅整體面貌，可以配住廣東話 TTS 完全指南一齊讀；呢篇專注「點由零起一個 Bot」，嗰篇補「語音生成嘅全景」。

Step 1：定場景同範圍

先答三條問題：

1. Bot 講咩？ 固定台詞多（導覽、通知、播報）定動態內容多（即時回應）？前者可以預生成快取，後者先要實時生成
2. 幾多輪？ 單向廣播定雙向對話？
3. 喺邊度播？ 網頁、電話、實體裝置——影響音頻格式（mp3／wav）同交付方式
4. 幾時要更新？ 台詞日日變定一年變一次？更新頻率決定你嘅生成流程要幾自動化

新手建議由「固定台詞＋單向」開始：一日內可以行晒全流程，先驗證聲線同文稿，再加深。第 4 條問題特別值得諗清楚——好多團隊高估咗自己嘅更新需求，起咗一套自動化重生成流水線，結果一年用三次；亦都有團隊低估咗，台詞月月變，人手重做到喊。誠實答呢條問題，架構先唔會起錯規模。順帶一提，三條問題嘅答案應該寫低嚟做項目記錄——三個月後接手嘅同事（包括三個月後嘅你自己），會多謝呢頁紙。

Step 2：寫口語稿

粵語 Bot 最易死喺文稿。三條規則：

• 口語字：佢、咗、喺、嘅、唔、冇——照書面語（他、的、不）寫，讀出嚟生硬。書面轉口語嘅完整對照，睇書面語 vs 口語處理指南
• 句短：一句 20 至 60 字符，聽感同生成效率都最好
• 數字、日期、專名：粵語讀法有自己習慣，電話號碼、金額呢類特殊讀法要先查清楚再寫入稿

稿寫好，自己出聲讀一次——你讀得唔順，引擎都唔會讀得順。

Step 3：揀聲線，鎖 slug

用 GET /v1/voices 攞聲線目錄，每個聲線有 slug（ASCII 穩定識別，官方示範係 sum 對應「心妍」）、性別、年齡層、支援風格同試聽連結。揀聲線建議：

1. 按品牌調性篩性別／年齡層
2. 用試聽 clip 短 list 入面逐把聽
3. 用你真實台詞（唔係示範句）試生成核對
4. 揀定之後，slug 寫入設定檔，全 Bot 統一用

一個好重要嘅規格細節：設計聲線（用性別＋年齡描述出嚟嗰種）同聲音複製嘅結果係單次請求性質，唔會存做可重用資產。要 Bot 把聲長期一致，用圖庫聲線。揀聲線嘅系統化準則，另文有詳細框架（TTS 聲線揀選指南）；想直接試聽，全部官方聲線喺粵語聲線庫。

Step 4：接生成——任務式三步曲

提交

POST /v1/audio/jobs，帶語音 slug 同文字，成功回 202，有任務編號同輪詢地址。單個 text 上限 500 字符；要 mp3 定 wav 用 response_format 揀。

輪詢

GET /v1/audio/jobs/{id} 查狀態：queued → processing → completed／failed／cancelled。建議 2 至 5 秒退避。好消息：輪詢接口唔計限流，隨便 poll。

下載

completed 之後回應帶 audio_url（預簽，下載唔使再驗證）。時效兩級：已入音頻庫 1 小時；直接由生成端出、未入庫 7 日。Bot 交付場景嘅最佳實踐：完成即下載，存去你自己嘅儲存，再交俾播放端——唔好將預簽網址當永久連結長期塞喺回應度。

Step 5：錯誤處理同限流

錯誤全部有穩定錯誤碼，分兩類處理：

• 唔使重試：400 參數錯（文字超長、格式錯）、401 金鑰問題、403 額度／權限——改嘢，唔好死 loop
• 可以重試：429 限流（照 Retry-After 等）、5xx 暫時性問題（退避重試）

兩個上限要喺代碼入面管：每分鐘提交限流（預設 60 次）、在途任務上限（免費 3／入門 5／專業 10／工作室 20）。完整錯誤表同每個碼嘅對策，睇錯誤碼大全。

揀聲線之外：風格都係 Bot 嘅人設

同一把聲，風格設定唔同，人設完全兩回事。Bot 場景常用三招：

• 演繹風格（styles）：每把圖庫聲線有佢支援嘅風格列表（查聲線目錄或者 GET /v1/voices/{slug}/styles），通知型 Bot 揀穩重風格，零售型揀活潑啲
• 情緒常數：全 Bot 一個預設情緒（多數 neutral 或 gentle），特殊分支先覆蓋——唔好每句都手調
• 自由指示（style）：想有少少「個性」（例如「輕鬆啲、似朋友傾偈」），可以用自由文字提示，效果逐句試聽微調

人設定好就寫入設定檔，同 slug 一齊管理——聲線、風格、情緒三樣都係 Bot 人設嘅一部分，唔應該散落喺代碼入面。

台詞模板化：變數點處理

Bot 台詞多數有變數：「你嘅預約係 10 月 15 號下晝 3 點」。處理模式：

• 模板＋變數拼接：固定部份（「你嘅預約係」……「到時見」）預生成存底；變數部份（日期時間）按需要實時生成，然後拼接
• 拼接位揀喺自然停頓：預生成句尾同變數開頭嘅語調唔一定接得順，硬喺句子中間接會聽得出斷口——揀逗號級嘅停頓位先接
• 變數讀法先驗證：日期、時間、金額嘅粵語讀法，生成一輪樣本逐個聽，先寫入正式模板

台詞模板化令「改一句要重生成一套」變成「改一塊重生成一塊」，長遠維護成本差好遠。

品質驗收：人耳 checklist

上線前，成套台詞音頻人耳過一次，逐項剔：

• 數字、日期、金額讀法正確
• 專名（地方、產品、人名）讀音企理
• 無書面語漏網（「之」「的」「了」呢類一聽就知）
• 語氣同場景匹配（錯誤提示唔好興奮、確認訊息唔好沉痛）
• 開頭結尾無爆音、無切字

呢一步冇捷徑——每條台詞都係品牌嘅出口，聽一次先至穩陣。

Step 6：開發用沙盒，上線轉正式

免費同入門方案可以開 sk_test_ 開頭嘅沙盒金鑰：每日 20 次生成（按帳戶計、跨金鑰共享），只計提交，輪詢同下載唔計。開發期成日重接重試，用沙盒先唔會嘥正式額度。升上專業方案之後，現有金鑰即時自動變全速，唔使重新接。金鑰嘅建立參數（名稱、權限範圍、限流、月度上限、過期時間）喺 playground 嘅「API 金鑰」頁管理。

三種 Bot 形態對照

「語音 Bot」其實涵蓋三種好唔同嘅形態，工作量同設計重點唔一樣：

大多數商業場景由播報型起步（最快見效、風險最低），行穩之後先加對話能力。混合型係最常見嘅終態——純對話型反而少，因為大部分業務對答嘅八成內容，其實都係可以模板化嘅。

錯誤處理實戰：一個上線日嘅劇本

模擬一下語音 Bot 上線第一日可能發生嘅事，同正確反應：

• 朝早：首批用戶觸發生成，有幾句撞 400 text_too_long——檢查發現係模板變數太長（用戶名+職銜），模板加長度上限，重試成功
• 下晝：撞 429 in_flight_limit_reached——一個推廣活動令請求突增。反應：排程器改為排隊提交，在途滿額就等，唔硬撞
• 夜晚：一個任務長期 processing 唔走——記錄任務編號、查狀態，最後主動取消重交
• 全日：401 一次都冇——因為金鑰由頭到尾一把、存喺環境變數、冇人手改過

留意：成日冇一次「盲 retry」。每個錯都有對應動作，日誌全部留底——咁樣嘅 Bot 先可以長期行，唔係示範性質。

多環境台詞管理：測試同正式分開

認真嘅 Bot 有兩套環境，台詞同金鑰都要分：

• 測試環境：沙盒金鑰（每日 20 次生成），台詞用縮細版（每類三五句），驗流程唔驗全量
• 正式環境：正式金鑰，台詞全量＋版本號
• 同步規則：測試版台詞通過人耳驗收先升格入正式庫，正式庫台詞變更要有 changelog

最平嘅事故預防，就係令「直接改正式」變成一件有記錄、有門檻嘅事。

上線前檢查清單

一個場景示例：預約提醒 Bot

流程行一遍：一間診所想喺預約前一日自動打電話提醒病人。

1. 場景定性：單向通知＋簡單回覆（確認／改期），固定模板為主
2. 文稿：主訊息一條模板＋三個變數（姓名、日期、時間）；回覆分支兩條固定台詞
3. 聲線：溫和成年聲，gentle 為主，全 Bot 一把聲
4. 生成：模板主體預生成存底；每次提醒實時拼變數（句子短，單請求搞掂）
5. 交付：mp3 交電話平台播；語音失敗有文字短訊做後備
6. 量：一日 40 個提醒、每通約 30 秒（約 120 字符），一日約 4,800 字符——入門方案月額 200,000 字符，綽綽有餘

由構想到上線一個星期內可行到，而且大部份時間係寫稿同聽樣本，唔係寫 code——呢個正正係語音 Bot 項目嘅真實工作量分佈。仲有一個位值得提：呢類播報 Bot 上線之後幾乎零維護——台詞唔變，音頻就日日照用；會變嘅只有業務數據（預約名單），嗰截本來就喺你自己系統度。

進階：交俾 agent 框架

如果你嘅 Bot 背後係 agent 框架（對話管理、工具調用），可以行 MCP 接入——港嘢提供 MCP 伺服器整合，agent 可以直接調用生成能力，唔使自己包 HTTP（用 MCP 教 agent 講廣東話）。完整 API 起步流程（包括第一個請求點發、金鑰點開），睇粵語 TTS API 快速上手。

常見問題 FAQ

唔識寫 code，整唔整到語音 Bot？

分兩半：生成音頻呢半，喺 playground 貼字即出，零 code；「Bot」嘅自動回應邏輯嗰半，一定涉及某啲整合（API 或者 MCP）。建議分工：先用 playground 驗證文稿同聲線，再搵技術資源接自動化。好多成功項目就係咁誕生——業務同事定內容，技術同事定管道，中間用「台詞庫＋版本號」做交接口。

一個 Bot 可以用幾多把聲？

技術上無限制——唔同意圖用唔同 slug 都得。但品牌一致性角度，一個 Bot 主聲線一把、必要時加第二把（例如轉人工提示用唔同聲），比多把聲輪流用更好。聲多唔等於豐富，多數時候只係散。

台詞成日改，次次要重新生成？

台詞變更先要重生成——所以固定台詞應該快取存底，動態內容（有變數嘅句子）先行實時生成。模板＋變數嘅寫法可以令重生成範圍最細：改一句，重做一句，其他台詞唔受影響。

揀聲線嘅試聽流程，具體啲係點？

一個可以用嘅流程：先按性別年齡層收窄到五把聲以內；每把聲用同一句你嘅真實台詞生成（唔好用示範句——示範句一定好聽，你嘅台詞先係真實考卷）；閉眼聽一次，剔走聽到出戲嗰啲；剩低嘅俾三個同事盲聽投票。成個過程一個鐘內搞掂，但揀中嘅機會率高好多——而且呢個流程嘅副產品（每把聲嘅試聽檔）留底，第日想換聲，有歷史可比。

免費方案可唔可以由頭行到尾？

可以驗證成條流程：每月 5,000 字符（約 21 分鐘音頻）、單請求功能齊全，只係冇批量。沙盒金鑰每日再有多 20 次生成測試。正式上線有量，先由入門方案（HK$128／月，200,000 字符）起步。即係話，由第一句試聽到自動化驗證，全程唔使碌卡。

Bot 要講嘢好快，用任務式會唔會太慢？

近即時體驗係架構問題唔係接口問題——短句、預取、快取三招可以令任務式 API 有即時聽感，另一篇即時 Agent 架構文專門講呢個題目。簡單講：一句 30 字符嘅話，播就有七八秒，下一句喺呢段時間早就整好。

對話入面要兩把聲對答點做？

兩把聲即係兩個 slug，分開請求生成再拼接。輪流對答嘅稿寫法、句距同語氣交替嘅要點，可以參考我哋嘅多聲道對話音頻教學一文。

[!CTA]

今日就俾個 Bot 講第一句廣東話

免費開戶每月有 5,000 字符，playground 貼字即聽；要自動化先開沙盒金鑰試接。