{"openapi":"3.1.0","info":{"title":"CantoneseTTS.com Developer REST API & Studio VIP MCP","version":"1.1.0","description":"Expressive Hong Kong Cantonese & Konglish AI Voiceover API with 7 human emotions, proprietary signature voice blends, synced .SRT + .VTT dual subtitle generation, and shared PostgreSQL atomic credit wallet. Human quickstart guide: https://cantonesetts.com/api-docs.md. REST API (/api/v1/*) is available on all paid plans; Remote MCP Server (/api/mcp) is exclusive to Studio VIP."},"servers":[{"url":"https://cantonesetts.com"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ctts_live_<48_hex>"}},"schemas":{"ApiError":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"code":{"type":"string","example":"PAYMENT_REQUIRED"},"error":{"type":"string"}},"required":["ok","error"]},"TtsRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":1200,"description":"Cantonese or Konglish script (up to 1,200 chars per call).","example":"喂大家好呀！今日限時閃購低至 $198，撳下面條 Link 即刻鎖定優惠啦！"},"voice_id":{"type":"string","default":"canto_marcus_host","example":"canto_yuki_ig","description":"Public voice alias from GET /api/v1/voices or custom clone_<id>."},"emotion":{"type":"string","enum":["happy","sad","angry","fearful","disgusted","surprised","neutral"],"default":"happy"},"colloquialize":{"type":"boolean","default":false,"description":"Auto-convert written Chinese and HKD figures into spoken Hong Kong Cantonese."},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1},"pitch":{"type":"integer","minimum":-12,"maximum":12,"default":0}}},"TtsResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"request_id":{"type":"string","example":"job_9f8a1b2c"},"voice_id":{"type":"string","example":"canto_yuki_ig"},"emotion":{"type":"string","example":"happy"},"speed":{"type":"number","example":1},"pitch":{"type":"integer","example":0},"normalized_text":{"type":"string"},"audio_url":{"type":"string","format":"uri"},"duration_sec":{"type":"number","example":5.42},"srt":{"type":"string","description":"Frame-synced SubRip (.srt) subtitle payload."},"vtt":{"type":"string","description":"Frame-synced HTML5 WebVTT (.vtt) subtitle payload."},"billable_chars":{"type":"integer","example":32},"credits_deducted":{"type":"integer","example":160},"credits_remaining":{"type":"integer","example":49840},"standard_chars_remaining":{"type":"integer","example":9968}}}}},"security":[{"BearerAuth":[]}],"paths":{"/api/v1/voices":{"get":{"operationId":"listVoices","summary":"List available Cantonese & Konglish voice IDs and supported emotions","responses":{"200":{"description":"Voice catalog and supported emotions"},"401":{"description":"Missing or invalid Bearer API key"},"402":{"description":"Free trial account without active paid plan"}}}},"/api/v1/usage":{"get":{"operationId":"getWalletUsage","summary":"Inspect shared PostgreSQL credit wallet balance and tier entitlements","responses":{"200":{"description":"Current wallet balance and plan tier"},"401":{"description":"Missing or invalid Bearer API key"},"402":{"description":"Free trial account without active paid plan"}}}},"/api/v1/script/colloquialize":{"post":{"operationId":"colloquializeScript","summary":"Convert written Chinese and HKD numbers into spoken Hong Kong Cantonese","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","example":"這個優惠他們今天不買就沒有了，只需 $198。"}}}}}},"responses":{"200":{"description":"Normalized spoken HK Cantonese script"},"400":{"description":"Empty or invalid script payload"},"401":{"description":"Missing or invalid Bearer API key"},"402":{"description":"Paid plan required"},"429":{"description":"Per-key sliding-window rate limit exceeded"}}}},"/api/v1/tts":{"post":{"operationId":"synthesizeCantoneseTts","summary":"Synthesize expressive Cantonese MP3 + synced .SRT and .VTT captions using atomic wallet credits","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRequest"}}}},"responses":{"200":{"description":"Synthesized MP3 URL, .SRT + .VTT strings, and updated wallet balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsResponse"}}}},"400":{"description":"Invalid voice_id, emotion, or text parameter"},"401":{"description":"Missing or revoked Bearer API key"},"402":{"description":"Paid plan required or insufficient wallet credits"},"403":{"description":"Studio VIP voice requested on standard paid plan"},"429":{"description":"Rate limit exceeded"},"502":{"description":"Upstream synthesis error (reserved credits 100% auto-refunded)"}}}},"/api/mcp":{"post":{"operationId":"mcpStreamableHttp","summary":"Studio VIP Exclusive Model Context Protocol (MCP) JSON-RPC 2.0 Server","responses":{"200":{"description":"JSON-RPC 2.0 MCP response"},"401":{"description":"Missing or invalid Bearer API key"},"402":{"description":"Paid plan required"},"403":{"description":"STUDIO_VIP_REQUIRED when called with non-VIP paid tier"}}}}}}