Cartesia Voice & Speech APIs

Cartesia provides text-to-speech (Sonic), speech-to-text (Ink), voices (library, clone, localize), and related HTTPS and WebSocket APIs. This skill covers application integration and agent-assisted coding. For Cartesia Line (managed voice agents, cartesia CLI, telephony, Line SDK), use line-voice-agent.

Core directives

• HTTPS only: All HTTP endpoints use https://api.cartesia.ai. WebSockets use wss://. HTTP may be unsupported; keys used over HTTP can be auto-rotated.
• Version header (required): Every request MUST send Cartesia-Version with a date (YYYY-MM-DD). Use the same date across your services so responses and errors stay predictable. Valid dates and what changed between them live in API conventions and llms.txt (not every page differs per version). Optional: GET https://api.cartesia.ai/ returns JSON {"ok":true,"version":"..."} with the gateway’s current default, useful when wiring a new client. Browser WebSockets cannot set custom headers on the handshake, so use ?cartesia_version=... there; when a header and query are both present on WebSockets that accept both, the query wins.
• Server-side auth: Use Authorization: Bearer <api_key> with your Cartesia API key (sk_car_...).
• Client apps (browser / mobile): Never embed API keys. Have your backend mint a short-lived access token and use Authorization: Bearer <access_token>. For WebSockets from browsers, pass the token as ?access_token=<token> (headers are not available on WS handshake). See Access Token API.
• Source of truth: Prefer docs, OpenAPI (latest.yml in the docs repo), and AsyncAPI for WebSocket TTS. For machine index: llms.txt and llms-full.txt.
• Choosing a TTS model: See TTS models for current IDs and guidance.
• Do not invent voice IDs: Use the List voices API or the SDK; playground defaults in examples are placeholders only.
• Streaming TTS: WebSocket TTS has different chunking, buffering, and continuation rules than POST /tts/bytes. Read the WebSocket TTS doc before assuming bytes-stream behavior.
• Errors: For Cartesia-Version 2026-03-01 and newer, errors are structured JSON (error_code, title, message, request_id, optional doc_url). Older versions may return legacy plain-text or legacy WebSocket envelopes. See API Errors and API conventions.
• Optional MCP: cartesia-mcp helps in Cursor / Claude (files, voice tools); it does not replace REST/SDKs for production. Requires Python 3.13+. See MCP docs.

When to use which path