# Canto-Gen (港嘢) — Cantonese TTS API

> https://canto-gen.com — Cantonese-optimized text-to-speech API. Nine tones preserved, particles pronounced right. Preset voices, designed voices and voice cloning.
> （中文簡介：廣東話文字轉語音 API — 支援預設聲線、聲線設計與聲音複製。）

## Instructions for AI Agents

- To integrate Canto-Gen TTS, start with the guide: https://canto-gen.com/v1/docs/en (English) · https://canto-gen.com/v1/docs (Traditional Chinese)
- Clean Markdown of the guide: https://canto-gen.com/v1/docs/en.md (English) · https://canto-gen.com/v1/docs.md (Traditional Chinese)
- Machine-readable OpenAPI 3.1 spec: https://canto-gen.com/v1/openapi.json
- Speech generation: sync POST /v1/audio/speech returns 200 audio bytes
  (≤300 billable chars, voice/design only; the sync queue is admitted only
  when fully idle — while busy it returns 503 {"error":"pool_cold"}, nothing billed; if the
  wait exceeds ~45 s it returns 202 {job_id, poll_url} — switch to polling).
- For longer text, clone or srt use the async endpoint: POST /v1/audio/jobs
  returns 202 with a job_id (bulk: {"items":[…]} up to 25).
  Pending-job cap is tiered by plan (free 3 / lite 4 / starter 5 / pro 10 / studio 20 /
  enterprise 20; 429 in_flight_limit_reached at the cap); bulk items require Starter or
  above (403 batch_requires_pro). Poll GET /v1/audio/jobs/{id} every 2–5 s until status
  is completed, then download the pre-signed audio_url (it expires — download promptly).
  Job responses always include job_id, status, poll_url, srt_requested; completed jobs
  add audio_url (and srt when requested).
- Transcription (audio → text): POST /v1/asr/transcribe (canonical; OpenAI-compatible
  multipart: file + model required;
  required; response_format json / text) — billed by audio duration at HK$1.40/hour,
  per-second, success-only (holds refund on failure). GET /v1/balance returns the
  prepaid HKD balance, rates and auto top-up settings. Top up at /account/billing.
- `text` supports inline tone tags — insert `[label]` in the script, e.g.
  `[笑聲]你好[唷!]`; closed set of 15, see the guide (Inline tone tags).
- Realtime WebSocket — one long-lived connection streams text in and PCM audio out:
  wss://api.canto-gen.com/v1/audio/realtime (OpenAI Realtime-based events; Canto-Gen extensions:
  input_text.append, input_text.commit, session.close). Audio arrives as base64 PCM16 @ 48 kHz
  in response.output_audio.delta; response.done carries billed_chars / remaining.
- The three voice modes are mutually exclusive: send exactly one of voice, design, or clone.
- Auth: `Authorization: Bearer $CANTOGEN_API_KEY` (sk_live_ keys; voice management needs `voices:manage` scope).
- MCP server: local stdio server, install with `npx -y cantogen-mcp` (npm package `cantogen-mcp`). The user fills CANTOGEN_API_KEY (sk_) into the config themselves — never ask them to paste secrets into chat.
- Never hardcode keys; use environment variables ($CANTOGEN_API_KEY, $CANTOGEN_MCP_TOKEN).

## Docs

- [API Guide (English) — quickstart, voice modes, polling, errors](https://canto-gen.com/v1/docs/en.md)
- [API Guide（繁體中文）— 完整指南的 Markdown 版](https://canto-gen.com/v1/docs.md)
- [OpenAPI spec](https://canto-gen.com/v1/openapi.json): OpenAPI 3.1 machine-readable spec
- [Interactive reference](https://canto-gen.com/v1/docs/reference): Scalar interactive reference

## Endpoints

- [POST /v1/audio/speech](https://canto-gen.com/v1/docs/en.md): Short-text synchronous generation — 200 audio bytes (voice/design, ≤300 chars).
- [POST /v1/audio/jobs](https://canto-gen.com/v1/docs/en.md): Submit a speech job (single or bulk ≤25; bulk requires Starter or above). Returns 202 with job_id(s) and poll_url.
- [GET /v1/audio/jobs/{id}](https://canto-gen.com/v1/docs/en.md): Poll a job; when completed the response carries a pre-signed audio_url.
- [GET /v1/voices](https://canto-gen.com/v1/docs/en.md): List the Cantonese-optimized voice catalog, with preview clips. This endpoint allows anonymous access.
- [POST /v1/asr/transcribe](https://canto-gen.com/v1/docs/en.md): Transcribe audio to text synchronously; billed by audio duration (HK$1.40/hour), success-only.
- [GET /v1/balance](https://canto-gen.com/v1/docs/en.md): Get the prepaid balance (HKD), transcription/dictation rates and auto top-up settings.
- [WSS wss://api.canto-gen.com/v1/audio/realtime](https://canto-gen.com/v1/docs/en.md#realtime): Realtime text-in / streamed-audio-out (OpenAI Realtime base + documented extensions)