Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints use HTTPS. HTTP is not supported. API keys that call the API over HTTP may be subject to automatic rotation.
All API requests use the following base URL: https://api.cartesia.ai. (For WebSockets the corresponding protocol is wss://.)

​
Always send a Cartesia-Version header

Each request you send our API should have a Cartesia-Version header containing the date (YYYY-MM-DD) when you tested your integration. For WebSockets, you can alternately use the ?cartesia_version query parameter, which will take precedence. This will help us provide you with timely deprecation notices and enable us to provide automatic backwards compatibility where possible. For a given Cartesia-Version, we will preserve existing input and output fields, but we may make non-breaking changes, such as:
  1. Add optional request fields.
  2. Add additional response fields.
  3. Change conditions for specific error types
  4. Add variants to enum-like output values.
Our versioning scheme is inspired by the Anthropic API.

​
Use API keys when making requests from a server

Create a new API key at play.cartesia.ai/keys. Include Authorization: Bearer <api_key> in the headers of your requests.

​
Use access tokens when making requests from a client app

Never use API keys in client apps; they grant full account access and can be extracted from browser or mobile code. Instead, your server can generate a short-lived access token and send it to the client. See the Access Token API Reference for how to generate one.
  • For HTTP requests, include Authorization: Bearer <access_token> in the headers.
  • For WebSocket connections, pass the token as the ?access_token=<access_token> query parameter since browsers can’t set headers on WebSocket handshakes.

​
Check response codes

Our API uses standard HTTP response codes; refer to httpstatuses.io.

​
Parse structured error responses

For Cartesia-Version values on or after 2026-03-01, Cartesia returns structured JSON errors. For the full error reference (all current error codes, schemas, and field nullability), see API Errors.
HTTP error response (Cartesia-Version 2026-03-01 and newer)
{
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
Field meanings:
  1. error_code: machine-readable identifier for client logic; can be null.
  2. title: short human-readable summary.
  3. message: detailed human-readable explanation.
  4. request_id: request identifier for support/debugging.
  5. doc_url: optional link to docs for the specific error (when available).
Common error_code values today include quota_exceeded, concurrency_limited, voice_model_mismatch, voice_not_found, model_not_found, language_not_supported, file_too_large, unsupported_audio_format, and plan_upgrade_required. WebSocket and SSE error events include the same error fields plus transport context:
WebSocket/SSE error event (Cartesia-Version 2026-03-01 and newer)
{
  "type": "error",
  "done": true,
  "status_code": 429,
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000:happy-monkeys-fly:8a0f5f3a-3b2f-4f28-b73e-8c5f27e2f8bb",
  "context_id": "happy-monkeys-fly"
}
Notes:
  1. context_id appears for TTS WebSocket errors when available.
  2. status_code is included in WebSocket/SSE error payloads; for HTTP, status remains in the HTTP response status line.
  3. request_id is always a string; HTTP and SSE request IDs are UUIDs, while WebSocket request IDs may include additional context.
For Cartesia-Version values before 2026-03-01 (and invalid versions), legacy error formats are returned instead:
  1. HTTP errors are plain text in Title: Message format.
  2. WebSocket/SSE errors use legacy envelopes with string-only error messages.

​
Pass data according to the method

All GET requests use query parameters to pass data. All POST requests use a JSON body or multipart/form-data.