廣東話語音，一個 API — 講得出，又聽得懂

MCP tools 一覽

詞彙表

• 每日生成上限 — 免費方案金鑰每日 50 個生成請求（輪詢與下載不計）；付費方案無每日上限。
• 金鑰每月 credits 上限 — 每把金鑰本月（UTC）累計計費 credits 的上限，超出回 403 monthly_cap_reached；預設不設上限。
• 帳戶 credits 池 — 帳戶層級的 credits 餘額，網頁 Playground 與 API 共用，按帳單週期重置；不足時回 402 character_limit_reached。
• Credit Pack — 為帳戶 credits 池一次性增值，永不過期。
• 待處理任務上限 — 同一帳戶可同時 pending 的任務數，按方案分級（3／4／5／10／20／20）；超限回 429 in_flight_limit_reached。

生成參數（所有模式共用）

字幕（SRT）

提交時傳入 "srt": true，完成後任務的查詢回應會附上 srt 欄位，內容為字幕（如上方完成回應所示）。srt_requested 欄位必定存在；srt 只在已要求且已就緒時出現。SRT 字幕輸出全方案適用。

Rate limit 與上限

每月 credits 上限 — 金鑰本月至今（UTC）的計費 credits 數必須低於其上限（null = 無限制）。超限會回傳 403 monthly_cap_reached 並附 used 數字，直至該月重設。X-RateLimit-* headers 附於 POST /v1/audio/jobs 的 202 及 429 回應、以及 POST /v1/audio/speech 的 429 回應（200 回應附帶 X-Credits-Charged 等 usage headers）；讀取 endpoint（GET /v1/audio/jobs/{id}、GET /v1/voices）不受 rate limit 限制。兩個計量器均以「故障時放行」為設計原則 — 計量系統故障絕不會令請求被拒。

同步交付 — 一個 curl 搞定

文件轉寫 — 上載音檔，同一請求內同步回傳文字。Canonical path：POST /v1/asr/transcribe；以 multipart/form-data 傳送。欄位：file（必填）、model（必填）、language（選填，ISO-639-1）、response_format（json 預設／text）。srt／verbose_json 需要段級時間標記，暫不支援（回 400 unsupported_response_format）。可選 vocabulary（上限 50 詞，關鍵詞偏置，asr_vocabulary 權限限定；無權限靜默忽略）— 冇帶呢個欄位時（API key 請求）自動套用你帳戶儲存嘅詞庫（PUT /v1/asr/vocabulary），帶咗（包括空陣列）就以請求為準。現階段轉寫以廣東話為本。

curl -X POST https://canto-gen.com/v1/asr/transcribe \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY" \
  -F file=@sample.wav \
  -F model=cantogen-asr \
  -F response_format=json

200 回應

{
  "id": "b7e6f2a1-4c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "object": "transcription",
  "text": "今日天氣幾好，一齊去行山啦。",
  "duration_seconds": 1830,
  "charged_hkd": 0.4067
}

計費

按音頻時長計費（預付 HK$ 餘額；1 HK$ = 1,000 credits）— 文件轉寫 800 credits／小時（HK$0.80／小時）、實時聽寫 1,400 credits／小時（HK$1.40／小時，1.75 倍），按秒計費、不進位。請求受理前先按偵測到的時長預扣，完成後按實際時長結算；失敗、超時或服務不可用一律全額退回（只扣成功）。餘額不足回 402 insufficient_balance — 請前往 /account/billing 儲值後重試。費率與餘額（credits／HKD 兩版）可用 GET /v1/balance 查詢。

上限

• file size — 同步 route 單檔實際上限 4.5 MB（平台 request body 上限；超出回平台層 413 — 建議先壓縮：ffmpeg -i in.* -vn -ac 1 -ar 16000 -c:a libopus -b:a 16k out.ogg，16kHz mono Opus 16k 單檔約載 33–40 分鐘）。
• audio duration — 同步交付上限 8 分鐘（480 秒）：probe 到超過 → 400 audio_too_long（帶 duration_seconds＋async_endpoint，處理前拒、零扣費）— 長音檔改用 POST /v1/asr/jobs（非同步，上限 4 小時／500MB）。單請求音頻政策上限 4 小時（超出回 413）。
• daily cap — 冇每日音訊上限（2026-10-30 起對所有 plan 一視同仁，包括免費）— 用量只由預付餘額 bound（credit 池 ＋ 錢包 hold）。

查詢餘額與費率

查詢預付餘額（HKD；1 HK$ = 1,000 credits — 回應同時帶 balance_credits credits 版餘額）、文件轉寫／實時聽寫費率（credits／HKD 兩版：800／1,400 credits 每音頻小時）與自動儲值設定。測試金鑰期間回傳測試環境餘額（與正式環境互相隔離）。餘額不足請前往 /account/billing 儲值（可開啟自動儲值 — 餘額跌低門檻時自動增值）。

curl https://canto-gen.com/v1/balance \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

清理規則

• terms — 最多 50 個詞（超出嘅由頭截斷）
• term length — 每個詞最多 30 字（超出嘅詞唔會儲存）
• cleanup — trim 空白、Unicode NFC 收斂、去掉重複詞（保留第一次出現嘅）

讀取 — GET /v1/asr/vocabulary

curl https://canto-gen.com/v1/asr/vocabulary \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

{
  "scope": "api",
  "terms": ["證監會", "庫務局", "Canto-Gen"],
  "updated_at": "2026-10-28T09:12:33.000Z"
}

覆寫 — PUT /v1/asr/vocabulary

curl -X PUT https://canto-gen.com/v1/asr/vocabulary \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"terms": ["證監會", "庫務局", "Canto-Gen"]}'

清空 — DELETE /v1/asr/vocabulary

curl -X DELETE https://canto-gen.com/v1/asr/vocabulary \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

每次請求帶 `vocabulary`

每次請求都可以帶 vocabulary（字串陣列）做即時偏置 — POST /v1/asr/transcribe、POST /v1/asr/jobs 同 POST /v1/asr/realtime/token（實時轉寫）都收。API key 同 browser session 客戶一樣可以帶（sk_ 憑證或 browser session）。空陣列係明確覆蓋（今次唔做任何偏置）；冇帶呢個欄位就係「用預設」語意（下一段）。

儲存詞庫幾時會自動套用

儲存嘅詞庫只係 API key 請求嘅預設：sk_ 客戶嘅轉寫請求如果冇帶 vocabulary 欄位，就會自動套用本帳戶儲存嘅詞庫；帶咗參數（包括空陣列）就以請求為準，永遠唔會 fallback 去儲存嗰份。Browser session（Playground）客戶唔受呢條預設影響 — session 請求冇帶參數就係冇偏置。

認證

認證方式與 REST 相同：sk_ API 金鑰，所需 scope 為 tts:generate。優先使用 Authorization: Bearer sk_… header；瀏覽器 WebSocket API 無法設定自訂 header，可改用 query 參數 ?api_key=sk_…（別名 ?token=）。query 參數會寫入 URL、伺服器日誌與瀏覽器歷史，存在洩漏風險，僅限瀏覽器環境使用；伺服器端請求一律使用 header。

事件 — client → server

事件 — server → client

切句模式（tts.segmentation）

tts.segmentation（extension）控制切句方式：{"mode":"server"}（預設）由伺服器按標點自動切句並逐句合成 — client 只需持續 append token；{"mode":"client"} 則由 client 透過 conversation.item.create / input_text.commit 自行決定段落邊界。可選 min_chars / max_chars / punctuation。

限制與逾時

• billing — 逐句（per utterance）reserve→complete／退款；實扣 = ceil(輸入字符 × 1.5)（2026-11-08 起 WS realtime 倍數，SSOT = constants.ts WS_REALTIME_CHARACTER_MULTIPLIER）。失敗／barge-in 自動退款。`response.done` usage：`input_chars` = raw 輸入、`billed_chars` = 實扣（含倍數）、`remaining` = 餘額。
• idle_timeout — 閒置 120 秒（無任何 app-level 活動）→ 伺服器關閉連線並結算。
• max_session_duration — free plan 單一 session 最長 5 分鐘；付費 plan 無時長上限（達全域上限時關閉）。
• max_sessions_per_user — 同一用戶的同時 session 上限按 plan 階梯：free 1／lite 2／starter 3／pro 4／studio 5／enterprise 5；未知 plan 一律視為 free。
• max_sessions_global — 全平台同時最多 8 個 session。
• max_session_chars — 每個 session **輸入**字符上限（**免費 2,000 字／付費 20,000 字**；按輸入字符量度 — 實扣另乘 WS ×1.5 倍數，見 billing）；server 端 clamp — client 經 `session.update`（或連線時 query `?max_session_chars=`）只可以要求更低，唔可以高過 plan 上限；超出回 session_char_limit_exceeded。生效值會喺 `session.created` 直接回傳（唔使行多次 `session.update` 先知）。
• max_in_flight — 每 session 同時最多 3 句未結算。
• raw_ingress — 每 session 原始輸入上限 20,000 字、每分鐘 5,000 字（標點與空白亦計）；超出回 raw_limit_exceeded，即時拒絕。
• lease — 每句合成有 60 秒結算租約；逾時未完成會自動退款。
• rate_limit / monthly_cap — 每用戶每分鐘 rate limit（同一帳戶嘅所有金鑰加埋計 — 開多把金鑰唔會突破總額；單把金鑰另外有較細上限）；每月 credits 上限按金鑰計。用量帳本逐句記錄（per utterance）。
• daily_generation_limit — 免費方案每日 50 個生成句（與 REST 共用同一計數，輪詢與下載不計）；超出回 sandbox_daily_limit（429），付費方案無每日上限。
• frame_size — 單一 WS 訊息上限 64 KiB。
• heartbeat — 伺服器定期 ping；心跳不計入 app 活動。

錯誤碼

認證

伺服器端：Authorization: Bearer sk_…。瀏覽器：永遠唔准將永久 API key 放入 URL — 先喺伺服器端叫 POST /v1/asr/realtime/token 簽一枚短命 ephemeral token（cst_…，60–600 秒，預設 300），再用 ?token=<cst_…> 開 WS（canonical；?api_key= 仍收做過渡 alias — 2026-10-21 gateway 正名，e2e 兩式實測 PASS）。可選 vocabulary（關鍵詞偏置，上限 50 詞，asr_vocabulary 權限限定；無權限靜默忽略）— sk_ 同 session caller 都帶得。

curl -X POST https://canto-gen.com/v1/asr/realtime/token \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"expires_in_seconds":300}'

協議次序

音訊格式與轉檔

音訊 = PCM16LE mono 16 kHz base64（32,000 bytes = 1 秒）；單 frame ≤640KB、平均 ≤640KB/s。送錯 sample rate 會得到垃圾轉寫並按收到的 bytes 計費 — 轉檔責任在 client（業界標準）：瀏覽器用 new AudioContext({ sampleRate: 16000 }) 取 mic；Node／檔案用 ffmpeg -i in.any -f s16le -ar 16000 -ac 1 out.pcm。關閉前會收 gateway.close（code＋reason）。連線 query 可宣告格式：?sample_rate=8000–48000&channels=1|2；送容器檔（WAV／MP3／Ogg／FLAC）→ 4010 invalid_audio_format（零計費）— 要 raw PCM16LE。

計費與上限

• billing — 1,400 credits／音頻小時（HK$1.40／音頻小時；1 HK$ = 1,000 credits；batch 的 1.75 倍）、按秒計費不進位；連線前驗餘額（唔夠一個 tick → 4002）；session 中每 60 秒 in-arrears 預扣（唔夠 → 4009）；收線按實際音頻秒結算（billed == audio）。實時用量同批次轉寫用量分開計。
• max_sessions_global — 全平台同時 10 條 session；每 key 同時 free 2／paid 4 條。
• session duration / idle — 冇單 session 長度上限（2026-10-30 起對所有 plan 移除）；閒置（無 client frame）120 秒收線；每 60 秒計費 tick 預扣，餘額唔夠即 close（4009）。
• format declaration — 連線 query ?sample_rate=8000–48000&channels=1|2 — 計費秒數按宣告 bps 折算；唔宣告 = 16kHz mono 契約。

WS close codes

生成紀錄清單 — GET /v1/audio/jobs

列出你自己嘅生成紀錄（最新先）— 純 API 客戶唔使登入 web UI 就查得返自己提交過乜、做到咗幾耐。每條紀錄都帶一個有界嘅文字預覽（最多 120 字）；要全文就用 GET /v1/audio/jobs/{id}，或者自己保留原文。金鑰要帶 tts:generate 或 tts:design scope（唔夠 → 403 insufficient_scope）。

curl "https://canto-gen.com/v1/audio/jobs?limit=20" \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

{
  "jobs": [
    {
      "id": "b7e6f2a1-4c3d-4e5f-8a9b-0c1d2e3f4a5b",
      "status": "done",
      "created_at": "2026-10-29T09:12:00.000Z",
      "voice_slug": "sum",
      "duration_ms": 4200,
      "text_preview": "你好，歡迎使用港嘢！"
    }
  ],
  "next_before": null
}

• limit — 每頁行數（1–100，預設 20）
• before — 游標 — 上一頁最後一條紀錄嘅 id（要 uuid）
• status — 可選過濾：queued／processing／cancelling／done／error／cancelled
• next_before — 下一頁嘅游標；null = 冇下一頁
• text_preview — 生成文字嘅有界預覽（最多 120 字）
• duration_ms — 音訊時長（毫秒；未生成完成 = null）

⚠️ status 用任務實際狀態值（done／error／…）；GET /v1/audio/jobs/{id} 嘅輪詢面用公開狀態名（completed／failed／…）—— 兩套詞彙唔同，睇清自己讀緊邊個 endpoint。

匿名使用統計 — GET / PUT /v1/account/telemetry

讀／寫本帳戶嘅匿名使用統計（質素訊號）設定。telemetry_opt_out: true = 關閉自動行為遙測（例如你嘅使用行為記錄）；你主動提交嘅評分／回報唔受影響 — 嗰啲係你明示嘅意圖，唔當成遙測。每個帳戶一個設定（同一帳戶嘅所有金鑰共用 user_profiles.telemetry_opt_out）。

curl https://canto-gen.com/v1/account/telemetry \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

{
  "telemetry_opt_out": false
}

curl -X PUT https://canto-gen.com/v1/account/telemetry \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"telemetry_opt_out": true}'

{
  "ok": true,
  "telemetry_opt_out": true
}

刪除帳戶 — POST /v1/account/deletion

刪除你自己嘅帳戶（自我服務刪除，純 API 客戶唔使登入 web UI 就用得）。兩步確認：body { confirmEmail, confirmWord } — confirmEmail 大小寫不敏感地等於你嘅帳戶電郵，confirmWord 大小寫敏感地等於 DELETE。成功 → 帳戶即時停用（登入被封、現有 session 全部失效），個人資料由每日清理程序清走、30 日內永久清除（purge_by 係完成清除嘅上限時刻）。

curl -X POST https://canto-gen.com/v1/account/deletion \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmEmail": "you@example.com", "confirmWord": "DELETE"}'

{
  "ok": true,
  "purge_by": "2026-11-02T03:00:00.000Z"
}

清除範圍：生成紀錄、聲線、參考音頻等個人資料一律清走；加密備份隨供應商嘅輪替週期移除（唔會即刻清）；帳務／用量紀錄依法保留（唔會因為刪戶而清走）。團隊帳戶要先解散 — 你係一個仲有其他成員嘅工作區擁有者會回 409 team_owner（要先解散／轉讓）；仲有未完成嘅生成工作會回 409 active_jobs。重複請求係冪等嘅（同一個帳戶只有一條刪除申請）。

錯誤碼

保留與刪除規則

刪除一律先刪資料庫紀錄、後刪音檔，資料即時失效、唔設復原；刪走之後唔會再喺任何生成或轉寫流程入面用到。

數據存放地與次處理者

資料中心位於南韓（首爾），備份由同區託管管理。次處理者：Supabase（託管資料庫同儲存）、Stripe（付款處理，唔經手你嘅內容）。語音生成由我們自家嘅雲端基礎建設執行，唔涉額外第三方。

刪除一條轉錄紀錄

刪除一條 ASR 轉錄紀錄（連你上載嘅音檔）：DELETE /v1/asr/transcriptions/{id}。個 id 就係 POST /v1/asr/transcribe／POST /v1/asr/jobs 回應帶返嘅 id。只可以刪自己金鑰嘅紀錄；搵唔到或者唔屬於你，一律回 404（唔會洩露 id 存在與否）。

curl -X DELETE https://canto-gen.com/v1/asr/transcriptions/<id> \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

刪除你的聲線

刪除你自己嘅聲線：DELETE /v1/voices/{id}（{id} 係聲線嘅 slug 或者 id）。聲線即刻喺所有清單消失、唔可以再用於生成；參考音檔同準備好嘅參考音頻副本即時清走，唔設復原。官方預設聲線唔可以刪（同一個 404，唔會洩露存在與否）；金鑰要帶 voices:manage scope。如果有生成工作仲引用緊呢把聲線，會回 409 voice_busy（唔會刪，等個工作完成之後再刪）。

curl -X DELETE https://canto-gen.com/v1/voices/<voice-slug> \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"

刪除一條生成紀錄

刪除一條生成紀錄：DELETE /v1/audio/jobs/{id}（{id} 係 POST /v1/audio/jobs 回應帶返嘅 job_id）。如果個 job 仲未完成（queued／processing），呢條 route 照取消佢（退款語義唔變）；如果已經完成／失敗／取消咗，就會刪走工作紀錄（連你生成嘅文字）、音檔同字幕副檔。刪除一律先刪資料庫紀錄、後刪音檔，資料即時失效、唔設復原。

curl -X DELETE https://canto-gen.com/v1/audio/jobs/<job_id> \
  -H "Authorization: Bearer \$CANTOGEN_API_KEY"