Messages

{
  "model_id": "sonic-3",
  "transcript": "Hello, world! I'm generating audio on Cartesia!",
  "voice": {
    "mode": "id",
    "id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "language": "en",
  "context_id": "ab977222-f9e0-4563-a1c0-5a934ae8fdd6",
  "output_format": {
    "container": "raw",
    "encoding": "pcm_s16le",
    "sample_rate": 8000
  },
  "add_timestamps": true,
  "continue": false
}

{
  "type": "timestamps",
  "done": false,
  "status_code": 206,
  "context_id": "872ec12d-bc63-4e1e-a241-4f58c879d105",
  "word_timestamps": {
    "words": [
      "Hello",
      "world"
    ],
    "start": [
      0,
      0.5
    ],
    "end": [
      0.4,
      0.9
    ]
  }
}

{
  "type": "phoneme_timestamps",
  "done": false,
  "status_code": 206,
  "context_id": "872ec12d-bc63-4e1e-a241-4f58c879d105",
  "phoneme_timestamps": {
    "phonemes": [
      "h",
      "ə",
      "l",
      "oʊ"
    ],
    "start": [
      0.093,
      0.174,
      0.255,
      0.337
    ],
    "end": [
      0.174,
      0.255,
      0.337,
      0.418
    ]
  }
}

{
  "type": "error",
  "done": true,
  "title": "Invalid model",
  "message": "The model is not valid, make sure it is a valid model ID.",
  "error_code": "model_not_found",
  "status_code": 400,
  "doc_url": "https://docs.cartesia.ai/build-with-cartesia/tts-models/latest",
  "request_id": "2ff8af53-4d38-479d-8287-58940f01c701",
  "context_id": "50dc3b5e-5841-4aa1-9f94-60cfb9aead79"
}

TTS

Text to Speech (WebSocket)

This endpoint creates a bidirectional WebSocket connection. The connection supports multiplexing, so you can send multiple requests and receive the corresponding responses in parallel.

The WebSocket API is built around contexts:

When you send a generation request, you pass a context_id. Further inputs on the same context_id will continue the generation, maintaining prosody.
Responses for a context contain the context_id you passed in so that you can match requests and responses.

Read the guide on working with contexts to learn more.

For the best performance, we recommend the following usage pattern:

Do many generations over a single WebSocket. Just use a separate context for each generation. The WebSocket scales up to dozens of concurrent generations.
Set up the WebSocket before the first generation. This ensures you don’t incur latency when you start generating speech.
Include necessary spaces and punctuation: This allows Sonic to generate speech more accurately and with better prosody.

For conversational agent use cases, we recommend the following usage pattern:

Each turn in a conversation should correspond to a context: For example, if you are using Sonic to power a voice agent, each turn in the conversation should be a new context.
Start a new context for interruptions: If the user interrupts the agent, start a new context for the agent’s response.

To learn more about managing concurrent generations and WebSocket connection limits, see the concurrency limits and timeouts page.

WSS

tts

websocket

Messages

{
  "model_id": "sonic-3",
  "transcript": "Hello, world! I'm generating audio on Cartesia!",
  "voice": {
    "mode": "id",
    "id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "language": "en",
  "context_id": "ab977222-f9e0-4563-a1c0-5a934ae8fdd6",
  "output_format": {
    "container": "raw",
    "encoding": "pcm_s16le",
    "sample_rate": 8000
  },
  "add_timestamps": true,
  "continue": false
}

{
  "type": "timestamps",
  "done": false,
  "status_code": 206,
  "context_id": "872ec12d-bc63-4e1e-a241-4f58c879d105",
  "word_timestamps": {
    "words": [
      "Hello",
      "world"
    ],
    "start": [
      0,
      0.5
    ],
    "end": [
      0.4,
      0.9
    ]
  }
}

{
  "type": "phoneme_timestamps",
  "done": false,
  "status_code": 206,
  "context_id": "872ec12d-bc63-4e1e-a241-4f58c879d105",
  "phoneme_timestamps": {
    "phonemes": [
      "h",
      "ə",
      "l",
      "oʊ"
    ],
    "start": [
      0.093,
      0.174,
      0.255,
      0.337
    ],
    "end": [
      0.174,
      0.255,
      0.337,
      0.418
    ]
  }
}

{
  "type": "error",
  "done": true,
  "title": "Invalid model",
  "message": "The model is not valid, make sure it is a valid model ID.",
  "error_code": "model_not_found",
  "status_code": 400,
  "doc_url": "https://docs.cartesia.ai/build-with-cartesia/tts-models/latest",
  "request_id": "2ff8af53-4d38-479d-8287-58940f01c701",
  "context_id": "50dc3b5e-5841-4aa1-9f94-60cfb9aead79"
}

cartesia_version

type:string

required

API version, e.g. 2026-03-01. You can specify this instead of the Cartesia-Version header. This is particularly useful in the browser, where WebSockets do not support headers. You do not need to specify this if you are passing the header.

X-API-Key

type:httpApiKey

API key passed in a header.

access_token

type:httpApiKey

A short-lived access token passed in a query param to make API requests from a client. This is particularly useful in the browser, where WebSockets do not support headers. See Authenticate client apps to generate an access token.

Generation Request

type:object

Use this to generate speech for a transcript.

Cancel Context Request

type:object

Use this to cancel a context, so that no more messages are generated for that context.

Audio Chunk Response

type:object

Audio data chunk

Flush Done Response

type:object

Acknowledgment that flush command was received

Done Response

type:object

Generation completion signal

Word Timestamps Response

type:object

Word-level timing information

Phoneme Timestamps Response

type:object

Phoneme-level timing information

Error Response

type:object

Error information for TTS WebSocket connections.

Text to Speech (SSE)

Contexts

⌘I

Use the API

API Status

TTS

STT

Agents

Voices

Voice Changer

Auth

Datasets

Fine Tunes

Infill

Pronunciation Dicts

Admin

Text to Speech (WebSocket)

Use the API

API Status

TTS

STT

Agents

Voices

Voice Changer

Auth

Datasets

Fine Tunes

Infill

Pronunciation Dicts

Admin

Documentation Index