Skip to main content

Documentation Index

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

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

If your Cartesia integration already has a provider adapter, migrating to Gradium should be a small change: point the adapter at Gradium, send your Gradium API key in x-api-key, and map Cartesia’s transcript and voice.id fields to Gradium’s text and voice_id. The shape stays familiar:
  • Complete utterance: one POST, one audio response body.
  • Streaming utterance: one WebSocket connection, text in, audio chunks out.

​
Endpoint swap

FlowCartesiaGradium
One-shot TTSPOST https://api.cartesia.ai/tts/bytesPOST https://api.gradium.ai/api/post/speech/tts
Streaming TTSwss://api.cartesia.ai/tts/websocketwss://api.gradium.ai/api/speech/tts

​
POST migration

Cartesia’s bytes endpoint sends a full transcript and returns audio bytes. Gradium’s POST endpoint does the same when only_audio is true. 
curl -L -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-2",
    "transcript": "Hello from Cartesia.",
    "voice": {"mode": "id", "id": "cartesia_voice_id"},
    "output_format": {"container": "wav", "encoding": "pcm_f32le", "sample_rate": 44100}
  }' \
  > output.wav

​
Field mapping

Cartesia conceptGradium field
transcripttext
voice.idvoice_id
model_idmodel_name
output_format.containeroutput_format
Cartesia-VersionNot required by Gradium
Authorization bearer token or X-API-Key headerx-api-key header
For most integrations, your existing “write response body to file” or “pipe response body to player” code can stay where it is.

​
WebSocket migration

For a single streaming utterance, Gradium does not require Cartesia’s context id flow. Open the socket, send setup, send text, then end the stream. 
{
  "model_id": "sonic-2",
  "transcript": "Hello from Cartesia.",
  "voice": {"mode": "id", "id": "cartesia_voice_id"},
  "context_id": "ctx-1",
  "output_format": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100}
}
Cartesia streaming stepGradium streaming step
Connect to Cartesia WebSocketConnect to wss://api.gradium.ai/api/speech/tts
Send request with transcript and voiceSend setup, then text
Read audio chunksRead audio messages
Finish the utteranceSend end_of_stream
Gradium audio messages contain base64-encoded audio chunks. Decode and append them in the same place your Cartesia adapter handled audio chunk payloads. If you use multiple simultaneous utterances on one connection, see Multiplexing.

​
Checklist

  • Replace the Cartesia URL with the Gradium endpoint.
  • Change auth to x-api-key.
  • Rename transcript to text.
  • Flatten voice.id to voice_id.
  • Change Cartesia’s structured output_format to a Gradium format string such as wav, pcm, or opus.
  • Keep your audio output path.

​
Next steps

Gradium TTS REST guide

Full POST schema, response modes, and output formats.

Gradium TTS WebSocket guide

Streaming setup messages, audio messages, flush, and timestamps.