cartesia-api

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 cartesia-line.

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
• API version: Cartesia's API is dated (Cartesia-Version: YYYY-MM-DD). Pin one version across your services and treat bumping it like a major dependency upgrade — a new version can carry breaking changes — so it's a fixed choice, not a runtime/per-call variable.
  • With an SDK (recommended): the SDK already pins a Cartesia-Version it was built and tested against. Let it manage that — do not override it (e.g. via default_headers) with your own date, since the SDK may not work against an arbitrary version. To move to a newer API version, upgrade the SDK.
  • Calling the API directly (no SDK): you must send Cartesia-Version yourself. Browser WebSockets can't set handshake headers, so pass it as ?cartesia_version=... (query wins if both are present).
  • Optional: GET https://api.cartesia.ai/ returns {"ok":true,"version":"..."} (the gateway's current default), useful when wiring a new client.
• 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)
  • The JS/TS SDK (v3+) runs in the browser with an access token — prefer it over hand-rolling the WebSocket (see its Browser Examples below); don't assume the SDK is server-only
  • See Access Token API
• 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 JSON structures
  • See API Errors and API conventions
• Source of truth: Prefer docs since they are updated first before SDKs / plugins / integrations
  • Fetch docs as Markdown: append .md to any docs.cartesia.ai page to get the agent-readable Markdown (e.g. https://docs.cartesia.ai/api-reference/stt/transcribe.md); the bare URL is the human HTML page. Prefer the .md form when fetching docs programmatically
  • For machine index: llms.txt and llms-full.txt
• Optional MCP: hosted server https://mcp.cartesia.ai/mcp (OAuth via the Playground) lists voices, runs TTS/STT, clones, and manages pronunciation dictionaries in Cursor / Claude
  • MCP does not replace API / SDKs for production
  • Local stdio (uvx cartesia-mcp) is for development; see MCP docs

Text-to-speech with Sonic (generating audio)

• Choosing a TTS model: See TTS models for current model IDs, supported languages, and features. Don't trust a model ID from memory — training data goes stale (e.g. sonic-2 is no longer current)
• Voice IDs: Don't invent a voice ID — a made-up UUID won't resolve. Real voice IDs are stable, so hardcoding a real one as a constant is fine and common; copy one from the playground or List Voices. Use List Voices to discover/choose a voice, not as a required call on every request
• Choosing an endpoint — bytes vs WebSocket: if the text is known up front (a fixed string, a button press), use POST /tts/bytes — it streams audio back as it's generated and is simpler. Reach for the WebSocket only when the input text arrives incrementally (e.g. piping an LLM's token stream) — the continuations case. Don't default to WebSockets; compare them in TTS endpoints
• Output audio format: See TTS output audio format for containers/encodings/sample rates (wav + pcm_s16le @ 44.1 kHz is a safe, self-contained default; mp3 carries no separate encoding)

Speech-to-text with Ink (transcribing audio)

• Choosing an STT model: see STT models for current models and supported languages
• Choosing an API endpoint: see Compare STT Endpoints
• Input audio: see STT input encodings for supported formats (self-contained files like .wav carry their own header)
• Before you write any STT code: read Common STT Pitfalls
  • Don't assume model or API behavior without grounding it in the docs — small client-side mistakes cause obscure but severe accuracy degradation
  • Common client-side errors:
    • Stripping or inserting whitespace in transcripts (read the model's text verbatim — no .strip(), no normalization)
    • Improperly concatenating transcript pieces
    • Not following the API spec

Cartesia Python SDK

pip install cartesia

• README.md
• All exported resources
• Examples
• Async Examples

Replace /heads/main/ with /tags/vX.X.X/ (e.g. /tags/v3.2.0/) to source code specific to your SDK version.

Cartesia TypeScript / JavaScript SDK

npm i @cartesia/cartesia-js

• README.md
• All exported resources
• Node / Bun / Deno Examples
• Browser Examples

Replace /heads/main/ with /tags/vX.X.X/ (e.g. /tags/v3.2.0/) to source code specific to your SDK version.

When to use which path

Goal	Path
App or backend calling REST/WebSocket	Python SDK, JS/TS SDK, or native API requests / fetch
IDE agent with MCP	Hosted https://mcp.cartesia.ai/mcp + docs fallback
Deployed voice agent, Line, telephony	cartesia-line
OpenClaw bootstrap	https://cartesia.sh/openclaw.md then docs / llms.txt

Quick start (HTTP TTS, one-shot)

Shape only: confirm field names and enums against the API reference for your Cartesia-Version:

curl -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic-3",
    "transcript": "Hello from Cartesia.",
    "voice": { "id": "f786b574-daa5-4673-aa0c-cbe3e8534c02" },
    "output_format": {
      "container": "wav",
      "encoding": "pcm_s16le",
      "sample_rate": 44100
    },
    "language": "en"
  }' \
  --output /tmp/out.wav

Mental model (for LLMs)

• Sonic = TTS model used to generate speech
• Ink = STT model used to transcribe audio
• Line = separate product: you deploy your Python agent; Cartesia runs STT/TTS/telephony around it, different from "call TTS API from my server."
• Concurrency / quota: Handle 429-class and structured concurrency_limited / quota_exceeded per API errors.

Language vs locale vs accent

Do not collapse these:

• language — coarse code (en, es)
• locale — language-region bucket (en-US, en-GB)
• accent — a specific voice identity inside a locale

One locale can have many accents. en-US includes General American and Southern American. Country cannot pick a unique accent. Prefer catalog IDs from the API over display names when the client will persist or send a value back.

Related material in this repo

• Line voice agents: cartesia-line
• Link hub: references/resources.md

Common mistakes

1. Overriding the SDK's Cartesia-Version: with an SDK, don't set or override the version — it pins one it's tested against; upgrade the SDK to move versions. Only raw HTTP/WS callers send the date themselves, and then keep one date everywhere (wrong date → subtle breakage or legacy error shapes).
2. API keys in frontend code: use short-lived access tokens minted by your backend.
3. Wrong auth header style: examples use Authorization: Bearer; match current docs, not old snippets.
4. Stale SDK / model code from memory: training data lags the API. Model IDs drift (e.g. sonic-2), and the JS SDK's named import { CartesiaClient } is deprecated and won't run in browsers — use import Cartesia from "@cartesia/cartesia-js" (or the default import). Confirm models against the models docs and SDK usage against the linked README / examples.
5. Using this skill for cartesia deploy / Line: switch to cartesia-line.