TTS API Key 認證入門：申請、設定與常見錯誤排查

一句答你：TTS API key 認證就係用一把帶前綴嘅字串（sk_live_ 或 sk_test_）喺每個請求 header 帶住，等伺服器認到你、計你用量、執行你嘅權限範圍。

Key Takeaways

• 認證用 Bearer token：每個 API 請求都要喺 Authorization: Bearer <key> header 帶住把 key，唔帶或者帶錯就 401
• 兩種 key 前綴：sk_live_ 正式生產用，sk_test_ 沙盒試接用；原始 key 淨係顯示一次，server 只存 SHA-256 hash
• Scopes 分權限：預設 tts:generate，聲音複製要另外開 tts:clone；唔夠 scope 就 403 insufficient_scope
• Rate limit 預設 60/min：滑動 60 秒窗口，header 有 X-RateLimit-* 提示剩餘額度；讀取 endpoint 唔限流
• Sandbox key 免費可用：免費同入門 plan 可以開 sk_test_，每日 20 個生成 call 跨所有 keys 共享
• Key 唔可以入 Git：用環境變數或者 secret manager，洩漏即 revoke 再 rotate

點解 TTS API 要認證？

認證唔係麻煩，係保護雙方。對你嚟講，把 key 等於你嘅用量鎖匙——伺服器靠佢知道呢個請求應該扣邊個帳號嘅配額。對平台嚟講，認證可以防止有人亂用、可以追蹤濫用來源、可以分級收費。

如果你用過 粵語 TTS 完全指南 嘅 Playground，應該留意到唔使登入都可以試聽聲線。但係一旦你想用 API 自動化、想批量生成、想用聲音複製功能，就一定要認證。冇認證嘅請求會直接被擋喺門外。

匿名訪問同認證訪問嘅分野好簡單：

換句話講，認證係由「睇」過渡到「用」嘅門檻。

API key 基本概念

API key 係一串長字符，用嚟代表一個特定嘅帳號同權限組合。喺呢個系統入面，把 key 一定會有前綴，等你可以一眼分到佢嘅用途。

sk_live_ 同 sk_test_ 嘅分別

• sk_live_：正式生產環境用。會扣你帳號嘅真實配額、會計入帳單、會執行你 plan 嘅所有限制
• sk_test_：沙盒環境用。適合本地開發、CI/CD、或者想試下 API 點用但唔想燒配額

兩種 key 嘅 endpoint 一樣、request body 一樣，但行為唔同：

• sk_test_ 喺免費同入門 plan 每日限 20 個生成 call
• 升級去 Pro 之後，原本嘅 sk_test_ 會自動變 full（mode 由 plan 即時推導，唔使人手轉 key）

Key 嘅生命週期

把 key 由產生到退役會經過幾個階段：

1. 建立：透過 Playground 或者 POST /api/api-keys，要俾 name、scopes 等參數
2. 首次顯示：原始 key 淨係顯示一次，之後再睇只會見到 prefix + 後幾位
3. 使用：每個請求 header 帶住
4. 到期（可選）：建立時可以設 expiresAt，過咗就 401
5. Revoke：人手撤銷，或者被系統因為濫用而停

如果你想由零開始接 API，可以睇 粵語 TTS API 快速上手，嗰度有完整嘅第一個請求流程。

點樣建立第一把 API key

喺 Playground 建立

最直接嘅方法就係登入 Playground 之後去 API keys 頁面，撳「New Key」，填個易認嘅名（例如「本地開發」、「CI deploy」），揀你需要嘅 scopes，就會見到原始 key。記住：見到嘅嗰一刻就要 copy 落安全嘅地方，因為離開呢個 modal 之後就再睇唔到原始字串。

用 API 建立 key

如果你想自動化（好似幫客戶開 key、或者寫 onboarding tool），可以用 POST /api/api-keys。支援嘅參數：

• name（必填，≤64 字）
• scopes（預設 ["tts:generate"]，可以加 tts:clone、tts:design、voices:manage）
• monthlyCreditCap（null = 無上限）
• rateLimitPerMin（預設 60）
• expiresAt（ISO 8601 未來時間）
• testMode（true → 出嚟係 sk_test_）

建立嘅 response 會包含原始 key（淨係呢一次），之後再 call 讀取 endpoint 就只會見到 metadata。

Key 顯示一次嘅原因

呢個唔係平台嘅怪癖，係整個行業嘅標準做法。原因好簡單：如果 server 儲咗原始 key，資料庫一旦洩漏，所有用戶嘅 key 都會即刻被盜。所以 server 只係儲 SHA-256 hash，原始 key 淨係喺建立嗰一刻俾返畀你。如果你唔見咗，畀可以「睇返」，淨係可以 revoke 再開新嘅。

Scopes：權限分級

Scope 係 OAuth-style 嘅權限分級。一把 key 可以有多個 scope，每個 scope 代表一種能力。預設係 tts:generate，夠用 90% 嘅 case。

tts:generate 預設 scope

呢個 scope 包含：

• 所有 preset 聲線生成
• design（gender + age）聲線生成
• 所有讀取 endpoint（GET /v1/voices、GET /v1/audio/jobs/{id} 等）

基本上除咗聲音複製之外嘅嘢，tts:generate 都做到。

tts:clone 點解要另外開

聲音複製涉及私隱同版權風險，所以獨立成一個 scope，等你可以：

• 開一把淨係畀內部同事用嘅 clone key
• 開一把畀客戶用但唔可以 clone 嘅 key
• 監控邊把 key 用咗 clone 功能（log 入面會見到 scope）

如果你想知 clone 嘅實際操作，可以參考 API 生成地道粵語語音 anchor 攻略 嗰度提到嘅聲線設計同 clone 嘅差異。

voices:manage 同 tts:design

• voices:manage：管理自訂聲線嘅權限
• tts:design：純 design 模式生成（如果你想限制把 key 唔可以用 preset 聲線）

一般嚟講呢兩個 scope 比較少用，但如果你嘅 use case 嚴格分開「邊個可以 generate、邊個可以 manage」，就可以用呢種分層。

Rate Limit 同用量控制

認證唔單止係認你係邊個，仲要限你用幾多。Rate limit 係保護平台同用戶嘅雙重機制。

預設 60/min

每把 key 預設每分鐘可以提交 60 個成功嘅 billable 請求。留意幾點：

• 滑動 60 秒窗口（唔係「每分鐘 0 點 reset」）
• 淨係計成功嘅請求（4xx 唔計入限流窗口）
• 讀取 endpoint（GET /v1/audio/jobs/{id}、GET /v1/voices）唔限流、冇 X-RateLimit-* header
• 批量請求當一個計（唔係每項一個）

如果你需要更高，可以建立 key 嘅時候調 rateLimitPerMin。

monthlyCreditCap

除咗 rate limit，你仲可以設月度字符上限。例如你開一把 key 畀客戶 demo 用，可以設 monthlyCreditCap: 50000，咁佢用完就會 403 monthly_cap_reached，唔會燒你嘅主配額。撞到月度上限嘅 response body 會有 used 字段，等你知道用咗幾多。

撞限流會點

• Rate limit 撞：429 rate_limit_exceeded，header 有 Retry-After（秒數）
• 月度 cap 撞：403 monthly_cap_reached
• 在途任務撞：429 in_flight_limit_reached（按 plan 分級：免費 3、入門 5、專業 10、工作室 20）

如果你想知唔同 plan 嘅限制同成本，可以參考 TTS 定價同成本分析。

認證錯誤碼速查

接 API 嘅時候最常見嘅就係認證錯誤。以下係一定要背低嘅幾個：

401 invalid_or_expired_token

• Key 無效（打錯字、revoke 咗）
• Key 過咗期（設咗 expiresAt）
• Header 格式錯（記住要 Bearer 加空格，唔好漏空格）

403 insufficient_scope

你用緊嘅 scope 唔夠。最常見情況：用 tts:generate 試 clone，返呢個錯。解決方法：開新 key 加 tts:clone scope。

403 monthly_cap_reached

月度字符上限到。睇返 monthlyCreditCap 設定，或者加 cap。

403 batch_requires_pro

你用咗批量（items）但係 plan 唔夠。記住：批量係專業同工作室專屬，免費同入門帶 items 會零提交、零扣費。

如果你想知同其他平台嘅認證流程對比，可以睇 2026 粵語 TTS 平台對比。

Sandbox key：免費試接

如果你未決定買邊個 plan，又想試下 API 點接，sandbox key 就係為你而設。

點樣開 sk_test_

免費同入門 plan 用戶可以喺 API keys 頁面或者 POST /api/api-keys（帶 testMode: true）開 sandbox key。過程同開正式 key 一樣，只係前綴變 sk_test_。

每日 20 個 call 限制

Sandbox 每日限 20 個生成 call。留意：

• 計數係 per-account，跨所有 sandbox keys 共享（防開多把 key 灌水）
• 只計生成 submission，poll 同 download 唔計
• 超額回 429

呢個限制係防有人開多把 sandbox key 灌水。如果你需要多啲，升級去 Pro 之後現有 sandbox key 會自動變 full，唔使重新開。

升級 Pro 自動變 full

呢個設計嘅好處係：你開發期間用 sandbox key 寫嘅 code，升級之後唔使改任何嘢，淨係換 plan，key 就自動有完整權限。Mode 由 plan 即時推導，唔涉及 schema 改動。

如果你想知免費 plan 仲有咩玩法，可以睇 免費粵語 TTS 攻略。

安全最佳實踐

認證嘅另一面係安全。一把 key 洩漏嘅後果可以好嚴重——唔單止你嘅配額會被燒，仲可能被人用嚟做濫用內容。

Key 唔好入 Git

即使係 private repo，都唔應該 commit 原始 key。Git 嘅歷史係永久嘅，delete 都會留低。.gitignore 一定要 ignore .env 檔。

用環境變數

export CANTO_GEN_API_KEY="sk_live_..."

或者用 secret manager（AWS Secrets Manager、HashiCorp Vault 等）。Code 入面讀環境變數，唔好 hardcode。

Rotate key 嘅時機

以下情況應該 rotate（撤銷舊嘅、開新嘅）：

• 懷疑洩漏（log 入面見到、員工離職）
• 定期 rotate（例如每 90 日）
• 換咗 use case（例如 dev key 變 production key）
• 帳號被入侵

建立新 key 之後記得更新所有引用嘅地方（包括 CI/CD、本地 .env、部署 config）。

點樣喺請求入面用 key

最後實際睇下點用。每個 API 請求都要喺 header 加：

Authorization: Bearer sk_live_你的key

例如用 curl：

curl -X POST https://canto-gen.com/v1/audio/jobs \
  -H "Authorization: Bearer sk_live_你的key" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好香港","voice":"sum"}'

記住：

• Bearer 後面有空格
• Header 名大小寫唔敏感，但 Authorization 係標準
• 唔好將 key 放 URL（會入 server log）

常見問題 FAQ

API key 喺邊度搵？

登入之後去 API keys 頁面就會見到所有 key 嘅列表。但係留意：原始 key 淨係建立嗰一刻顯示一次，如果你已經建立咗一陣，要睇返原始值係冇辦法嘅，只會見到前綴加後幾位（例如 sk_live_abc...xyz）。

Key 唔見咗點算？

冇辦法「睇返」，因為 server 只係儲 SHA-256 hash，原始 key 唔會儲低。唯一做法就係 revoke 舊嘅 key（如果仲 active 嘅話），再建立一把新嘅。記得建立新嘅之後即刻更新所有引用嘅地方。

一個帳號可以開幾多把 key？

冇硬性上限。你可以為唔同 use case 開唔同 key（例如 dev、staging、production 各一把），每把可以獨立設 rate limit、monthly cap、scopes。咁樣做嘅好處係：一旦某把 key 洩漏，影響範圍可控。

Sandbox key 同正式 key 可以同時用？

可以。你嘅帳號可以同時有 sk_test_ 同 sk_live_ 嘅 key。佢哋係獨立計數嘅——sandbox 嘅 20/日 限制唔會影響正式 key 嘅 rate limit，反過來都一樣。咁樣設計係方便你喺同一個 project 入面分開 dev 同 prod 環境。

點知 key 嘅 rate limit 剩幾多？

每個 POST /v1/audio/jobs 嘅 202 response 同 429 response 都會帶 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 三個 header。讀取 endpoint（GET 嗰啲）就唔會有呢啲 header，因為佢哋唔限流。如果你做自動化，最好喺 client side log 呢啲 header，等你可以預先知道幾時會撞限流。

認證 header 應該點寫？

要寫 Authorization: Bearer <key>。留意 Bearer 後面有空格，key 唔使加任何引號或者 prefix。例如 Authorization: Bearer sk_live_abc123def456。如果你嘅 HTTP client 有現成嘅 interceptor（例如 axios interceptor、requests middleware），可以喺度統一加，唔使每個 request 都手動寫。

可以同人分享 key 嗎？

唔建議。即使你信對方，key 一旦離開你嘅控制範圍就難追蹤。如果真係要畀人用（例如同事），最好開一把獨立嘅 key，設低 monthlyCreditCap 同短嘅 expiresAt，咁樣出事都有數得計，亦可以隨時 revoke 唔影響你自己嘅 key。

---

[!CTA]

開一把 API key 試下

註冊就送 每月 5,000 字符額度，即刻喺 Playground 建立你嘅第一把 sandbox key，唔使信用卡、唔使 commit。