MCP 接入粵語 TTS：完整教學同實戰指南

一句答你：MCP（Model Context Protocol）係一個開放嘅標準協議，等 AI agent／IDE 助手／自動化工具可以直接「識得用」外部服務；用 MCP 接入粵語 TTS，即係將語音生成變成 agent 工具箱裏面一件「傢私」，由模型自己判斷幾時用、點用，唔再需要人手 copy paste。

Key Takeaways

• MCP 接入嘅本質係「將 TTS 變成 agent 識得用嘅工具」，唔係另一個新嘅 TTS 服務
• 港嘢嘅 TTS API 已經可以經 MCP 接，async 為主，≤300 字符原本仲有 sync 捷徑但目前暫停
• 免費／入門 plan 可以用 Sandbox key（sk_test_）試接，每日 20 個生成 call，跨所有 key 共享
• 升級 Pro／Studio 之後，現有 sandbox key 會即時自動變 full，唔使重新申請
• 批量（items）係 Pro／Studio 專屬；免費／入門帶 items 會被零提交、零扣費擋返
• 在途任務上限按方案分：免費 3、入門 5、Pro 10、Studio 20

乜嘢係 MCP？點解同粵語 TTS 有關？

MCP 嘅基本概念

MCP（Model Context Protocol）係一個開放嘅協議標準，用嚟連接 AI 模型同外部工具、數據源同服務。你可以將佢理解成「agent 嘅 USB 介面」——只要工具跟呢個協議講嘢，AI 助手（無論係 IDE 插件、桌面 agent 定自動化流程）就可以直接發現同使用佢，唔使每個工具單獨整一套整合。

對一般用戶嚟講，最直接嘅意義係：你唔使再人手 copy paste 文字去 TTS 網站、再人手 download 音檔。MCP 令到 TTS 變成 agent 工具箱裏面嘅一件「傢私」，模型自己識得幾時用、點用。例如 agent 寫完一段粵語文案，可以即刻自己 trigger TTS 生成語音，再將音檔嵌入去影片 workflow。

點解 TTS 特別適合用 MCP 接

TTS 嘅輸入輸出都好簡單：攞一段文字，出一段音頻。呢種 stateless、IO 清晰嘅特性，令佢好適合做 agent 工具。相比起其他工具（譬如要管理 session、要長期持有狀態嘅服務），TTS 接 MCP 嘅心智負擔低好多——tool schema 簡單、錯誤模式可預測、副作用有限。

另一個原因係粵語 TTS 嘅應用場景——客服、影片配音、教材製作、資訊朗讀——好多時都係「文字已經喺度，只差一個聲」。當呢啲文字已經喺 AI agent 嘅 context 入面（譬如對話記錄、生成嘅文案、抽出嘅字幕），最自然嘅下一步就係直接叫 TTS 講出嚟。透過 MCP 將呢個步驟自動化，係最順嘅做法。

如果你想了解粵語 TTS 嘅整體能力同應用，可以參考 廣東話 TTS 完全指南。

MCP 接入粵語 TTS 嘅典型場景

客服機械人同對話系統

AI 客服答完用戶之後，如果可以即刻用廣東話講出嚟，體驗會完全唔同。用 MCP 接 TTS 之後，客服 agent 可以根據對話內容動態生成語音回覆，而唔係預錄一堆罐頭聲。對話長度唔同、情境唔同，聲線情緒都可以唔同。

呢種場景通常會用到 emotion 或者 instruction 參數，去控制語氣——例如用戶投訴時語氣稍慢、稍沉；用戶查詢時語氣明快、稍高。詳細嘅 emotion 用法可以參考 TTS 情緒控制攻略。

內容自動化同批量生成

做短片、YouTube 頻道、或者社交媒體內容嘅人，往往要將大量文案轉成語音。用 MCP 接 TTS 之後，內容生產嘅 pipeline 可以由 agent 自動完成：寫稿 → 校對 → 生成語音 → 出 SRT 字幕 → 上載。每一步都係 agent 自己 trigger 嘅工具。

呢度會用到批量 endpoint（items），一次過交多段文字畀 API。需要留意嘅係批量係 Pro／Studio 專屬，詳細嘅批量 workflow 可以參考 TTS 批量生成工作流。

IDE 助手同編程 agent

而家好多 IDE 都有 AI 助手，可以幫你寫 code、寫文檔。透過 MCP，呢啲助手可以直接將生成嘅粵語內容（例如 README、commit message 嘅中文版、code comment）轉成語音，等你聽到而唔係睇到。對開發者嚟講，呢個場景特別順——佢哋已經習慣喺 IDE 入面用 AI 助手，加多一件工具嘅成本好低。

呢類用法通常會用到聲線目錄入面比較中性、清晰嘅 preset，方便長時間聆聽。

接入前要知嘅 API 基礎

三種生成模式

港嘢嘅 TTS API 提供三種生成模式：

⚠️ design 同 clone 出嘅聲線係 per-request——即係每次請求獨立生成，唔會儲存成可重用嘅 asset。如果你需要反覆用同一個自訂聲線，要自己保留相關參數（gender、age、或者參考音頻），每次請求時重新提交。

同步同異步

API 嘅 pattern 係 async 為主：

1. POST /v1/audio/jobs 提交 → 回 202 + job_id
2. 用 job_id poll GET /v1/audio/jobs/{id} 等完成
3. 完成後 response 入面有 audio_url，下載就得

但係有個 sync 捷徑：≤300 字符嘅請求，而且只支援 voice／design，可以直接用 POST /v1/audio/speech 即時攞到 audio bytes。

⚠️ 而家 POST /v1/audio/speech 係恆回 503 pool_cold，所以實際上 sync 捷徑暫時用唔到。寫 MCP tool 嘅時候，建議當佢係 async 嚟設計，避免到時要改架構。

如果你嘅 agent 工具要支援 clone 或者 SRT，記得 sync 一定唔得——clone 會回 400 clone_not_supported_sync，srt 會回 400 srt_not_supported_sync。

Key 同權限

API key 分兩種前綴：

• sk_live_ — 正式 key，會扣月配額
• sk_test_ — Sandbox key，限每日 20 個生成 call，唔扣月配額

兩種 key 都係 server 只儲 SHA-256，原始 key 只會顯示一次，記低佢。

Scopes 方面：

• tts:generate（預設）— preset／design 生成 + 所有讀取 endpoint
• tts:clone — 聲音複製（以參考樣本）

如果 MCP tool 要做 clone，就要用有 tts:clone scope 嘅 key；否則會回 403 insufficient_scope。詳細嘅 API key 管理可以參考 粵語 TTS API 快速上手。

Sandbox key：免費試接嘅捷徑

點解要用 Sandbox key

如果你係用免費或者入門 plan，想試吓 MCP 接入係咪 work，但又唔想燒配額——Sandbox key 就係設計畀你呢個場景。

Sandbox key 嘅限制：

• 每日 20 個生成 call
• 計數係 per-account，跨所有 keys 共享（即係你開 10 把 sandbox key，加埋都係 20 個 call／日）
• 只計生成 submission，poll／download 唔計

呢個設計嘅原因係防止有人開多把 key 灌水——無論你開幾多把 sandbox key，總額都係 20 個 call／日。

升級之後會點

呢個設計嘅聰明位喺：當你由免費／係門升上 Pro 或者 Studio，現有嘅 sandbox key 會即時自動變 full。你唔使重新申請 key、唔使改 MCP 設定，mode 由 plan 即時推導。

換句話講，你可以由 Sandbox 開始試，一路試一路升級，到正式用嘅時候都唔使郁 configuration。呢個對 MCP 接入嘅開發者嚟講特別方便——你可以用同一份設定由 dev 推到 prod。

⚠️ 未確認：sandbox key 帶 tts:clone scope 實際端到端係咪 work。clone 要參考音頻，sandbox 限制未明。如果你要做 clone，建議先用 live key 喺低用量環境測試。

配額、在途任務同限流

在途任務上限

API 對「仲未完成」嘅 job 數量有上限，按方案分：

超過會回 429 in_flight_limit_reached，response body 會有 limit 同 active 兩個 field 講你限幾多、而家有幾多。

對 MCP agent 嚟講呢個好重要——如果 agent 一次過 trigger 好多 generation（例如批量處理 20 段文案），就要自己排隊，唔可以一次過 fire。否則會撞 429 in_flight_limit_reached，浪費 submission quota。

Rate limit

每個 key 預設 60 requests/min，滑動 60 秒窗口，只計成功嘅 billable 請求。讀取 endpoint（GET /v1/audio/jobs/{id}、GET /v1/voices）唔限流。

撞限流會回 429 rate_limit_exceeded，header 會有 Retry-After 講幾時可以再試。MCP tool 應該識得讀呢個 header，主動退後重試。

批量嘅特殊處理

如果你嘅 MCP tool 支援批量（items），記得：

• 一次請求最多 25 個 request bodies
• 超過回 400 too_many_items
• 批量驗證係全有或全無——任何一項無效，全部回 400 invalid_items
• 批量係 Pro／Studio 專屬；免費／入門帶 items 會被零提交、零扣費擋返（回 403 batch_requires_pro）
• 批量一次請求計一次限流（唔係每項計）

呢個對 agent 設計好重要：如果你嘅 tool 介面接受「多段文字」嘅 input，要先判斷 plan 係咪支援，唔係嘅話就逐段 submit，否則成個 call 會被擋返，連一段都唔會處理。

接入嘅實際流程

設計 MCP tool 嘅 schema

一個好嘅 MCP tool 應該將 TTS 嘅複雜性收埋，對 agent 呈現簡單嘅介面。最基本嘅 tool 應該有：

• text — 要轉成語音嘅文字（1–500 字符）
• voice_slug — 用邊個聲線（optional，唔填就用預設）
• style — 演繹風格（optional）
• emotion — 情緒（optional）

進階嘅 tool 可以加：

• output_format — 音頻格式
• instructions — 自由指示
• srt — 要唔要 SRT 字幕（async only）

記得 text 嘅長度上限係 500 字符，超過會rejected，唔會截斷。MCP tool 應該自己 pre-validate 長度，唔好將責任推畀 API。

處理 async 嘅 pattern

因為 sync 而家係 503，MCP tool 基本上要設計成 async：

1. 收 agent 嘅 call，立即 submit job
2. 返 job_id 畀 agent
3. Agent 用 job_id poll 狀態
4. 完成後攞 audio_url，畀 agent 用

或者你可以喺 MCP tool 入面做埋 polling，等完成先 return audio bytes 畀 agent——視乎你想畀 agent 幾多控制權。前者畀 agent 多控制權（例如可以中途 cancel），後者體驗簡單（agent 一個 call 就攞到結果）。

錯誤處理

API 嘅錯誤碼有清晰嘅語義，MCP tool 應該將呢啲錯誤映射成 agent 理解得到嘅訊息：

特別要留意 text_too_long——超過 500 字符係rejected，唔會截斷。如果你嘅 MCP tool 接受長文，就要喺 tool 入面做 chunking，分段提交。

常見嘅接入陷阱

將 sync 當 async 用

POST /v1/audio/speech 而家係恆 503。如果你寫 MCP tool 嘅時候假設 sync work，到實際用嘅時候會撞牆。建議一開始就設計成 async，避免到時要改 tool schema。

唔理 plan 限制就 trigger 批量

如果你嘅 MCP tool 接受「多段文字」嘅 input，但用戶係免費 plan，就會直接撞 403 batch_requires_pro。最好喺 tool description 入面講清楚限制，或者喺 runtime 偵測 plan。

唔處理 polling

Agent 通常冇耐性無限等。如果 MCP tool 唔主動 poll，agent 就要自己處理 polling logic——但好多 agent framework 唔識做呢樣嘢。建議喺 MCP tool 入面包裝埋 polling，畀 agent 一個簡單嘅「等我」嘅體驗。

忽略 audio_url 時效

audio_url 嘅時效分兩種：

• Materialized（audio library）pre-signed URL：1 小時
• 直接由 generation worker 出（未 materialize）：7 天

Job queued／processing 中，同 failed／cancelled 時，audio_url 唔存在。如果你嘅 MCP tool 要畀 agent 攞 URL，最好喺完成後即刻 download 落本地，再以本地 path 畀 agent。下載唔使 auth header（URL 本身已 pre-signed），過期就 re-poll 攞新 URL。

點樣開始

如果你想即刻試吓，最直接嘅方法係去 Playground 試吓聲線同風格，確定你想要嘅效果先，再寫 MCP tool。寫 MCP tool 嘅時候，記得善用 Sandbox key 試接，唔好一開頭就燒正式配額。

API 嘅詳細規格可以喺 /v1/openapi.json 搵到（OpenAPI 3.1，免 auth），互動文件喺 /v1/docs。如果你係第一次接 API，建議由 粵語 TTS API 快速上手 開始，再參考 廣東話 TTS 完全指南 了解粵語 TTS 嘅整體能力。

揀 plan 嘅時候可以參考 廣東話 TTS 選購指南 同 廣東話 TTS API 錨點攻略，了解唔同用量場景點揀最啱自己嘅方案。

常見問題 FAQ

MCP 接入 TTS 同直接用 API 有咩分別？

基本上冇分別——MCP 只係畀 agent 識得用 API。你嘅 MCP tool 內部都係 call API endpoint，只係多咗一層包裝，等 agent 可以自動發現同使用。對你嚟講，最大分別係工具嘅輸入輸出設計要貼合 agent 嘅 context，而唔係畀人手喺 terminal 用。

免費 plan 可以用 MCP 接入嗎？

可以，但有幾個限制：每日 20 個 sandbox call、3 個在途任務上限、冇批量、唔可以用 live key 嘅全速 API（但 sandbox key 可以試接）。如果你嘅 agent 用量低，呢啲限制可能夠用；用量大就要升級。

Sandbox key 同 live key 可以喺同一個 MCP tool 用嗎？

可以，但通常冇必要。Sandbox key 限每日 20 call，live key 會扣月配額。你應該根據環境（development 用 sandbox，production 用 live）揀對應嘅 key。升級 Pro 之後，現有 sandbox key 會自動變 full，唔使轉 configuration。

MCP tool 要點處理 async？

兩種做法：(1) 將 job_id 返畀 agent，等 agent 自己 poll；(2) 喺 MCP tool 入面 polling，等完成先 return audio bytes。前者畀 agent 多控制權（例如可以中途 cancel），後者體驗簡單。視乎你嘅 agent framework 支援邊種。

接入之後點知有冇超限？

API 嘅 response header 有 X-RateLimit-Limit / -Remaining / -Reset（只喺 POST /v1/audio/jobs 嘅 202／429，同 sync 嘅 200／429）。你可以喺 MCP tool 入面讀呢啲 header，主動提示 agent 將到限。

clone 模式可以用 sandbox key 試嗎？

未確認。Sandbox key 帶 tts:clone scope 嘅端到端行為未有完整驗證。如果你要做 clone，建議先用 live key 喺低用量環境測試，確認 work 先再 deploy。

點解我嘅 MCP tool 收到 503？

最大可能係你 call POST /v1/audio/speech（sync 端點），而家呢個 endpoint 恆回 503 pool_cold。改用 async pattern（POST /v1/audio/jobs + polling）就解決。

[!CTA]

將粵語 TTS 變成你 agent 識用嘅工具

去 Playground 揾你嘅聲線，再寫第一個 MCP tool——免費開戶每月有 5,000 字符試玩，配額用完先考慮升級。