Skip to main content
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 to authenticate

Authentication is handled using API keys. You can create a new API key from play.cartesia.ai/keys. To use your API key, include Authorization: Bearer <api_key> in the HTTP headers of Cartesia API requests. Client apps making Cartesia API requests should use Access Tokens, to avoid exposing your API Key. Your server generates an Access Token and sends it to your client, which in turn includes Authorization: Bearer <access_token> in the HTTP headers of Cartesia API requests. Read the full documentation for this at Access Token API Reference for more info. For WebSocket connections, authenticate by passing in the field ?api_key=<your_api_key> when creating the WebSocket connection from the server, and passing in ?access_token=<access_token> when creating from the client.

​
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.