Create Speech

POST /tts/bytes

Generates audio from the input transcript. The response body is the complete audio clip in the requested format; it arrives once generation finishes. For real-time playback, use /tts/sse or the WebSocket instead.

Request Body

Parameter	Type	Required	Description
`model_id`	string	Yes	The TTS model. Currently `gepard-1.0`.
`transcript`	string	Yes	The text to synthesize.
`voice`	object	Yes	Voice specifier: `{ "mode": "id", "id": "<voice-id>" }`.
`output_format`	object	Yes	Output format (see below).
`language`	string	No	BCP-47 language tag (e.g. `en-US`). Accepted for compatibility but has no effect on synthesis.

voice is required — there is no default voice. The only accepted form is the nested object { "mode": "id", "id": "<voice-id>" }; a top-level voice_id is not supported, and mode must be "id". A request that doesn’t resolve to a voice is rejected rather than silently synthesized: missing_voice / missing_voice_id / unknown_voice_mode (400) for a bad specifier, voice_not_found (404) for an unknown id, and missing_transcript (400) for an empty transcript. See Errors for the full envelope.

Length limit

transcript can be at most 2,000 characters per request, and per message on the WebSocket. 2,000 characters is about 1.5–2 minutes of speech for typical voices. Characters are counted the same way as for billing: Unicode code points of transcript exactly as sent (after JSON decoding), with no normalization. Leading and trailing whitespace and newlines count too. You can check before sending:

Python: len(text)
JavaScript: [...text].length. Don’t use text.length: it counts UTF-16 units, so it overcounts characters outside the Basic Multilingual Plane, such as emoji ("😀".length === 2).

In scripts that attach vowel and tone marks to letters, such as Thai, Khmer, Lao and Burmese, each mark is its own code point, so the count is higher than the number of visible letters. The same applies to Vietnamese sent in decomposed form; send NFC-normalized text (text.normalize("NFC")) to keep the count down. Over the limit returns 400 with error_code: "input_too_long". It’s returned before any work starts, so nothing is billed:

{ "error": "input_too_long", "error_code": "input_too_long", "message": "transcript is 2345 characters; the maximum is 2000 per request — split longer text across requests or WebSocket messages", "detail": "transcript is 2345 characters; the maximum is 2000 per request — split longer text across requests or WebSocket messages" }

For longer content, split it into multiple requests, or stream it over WebSocket as several messages with continue: true — the limit is per message. For real-time playback, prefer streaming: /tts/bytes returns nothing until the whole clip has been generated.

The request body itself is capped at 64 KB — a body over 65536 bytes returns 413 with error_code: "payload_too_large". Normal requests are nowhere near this.

Output Format

output_format has three fields, each validated against a fixed set. Anything outside these values returns 400 — the API does not silently fall back.

Field	Allowed values
`container`	`raw`, `wav`
`encoding`	`pcm_s16le`, `pcm_mulaw`, `pcm_alaw`
`sample_rate`	`8000`, `16000`, `22050`, `24000`, `44100`, `48000`

The model is natively 48 kHz. 48000 skips resampling; lower rates are resampled on the server.
Container by endpoint: wav is available only on /tts/bytes. Streaming endpoints (/tts/sse, /tts/websocket) are raw-only — there’s no place to put a RIFF/WAV header in a chunked stream.
pcm_mulaw / pcm_alaw are 8-bit G.711 telephony codecs. Browsers can’t play them directly; decode to linear PCM first (or hand them straight to your telephony stack).

// WAV (PCM) — /tts/bytes only
{ "container": "wav", "encoding": "pcm_s16le", "sample_rate": 22050 }
// Raw PCM — lowest latency for streaming pipelines
{ "container": "raw", "encoding": "pcm_s16le", "sample_rate": 22050 }

Telephony (G.711)

For Twilio / SIP media streams, request 8 kHz μ-law or A-law raw. G.711 encodings aren’t forced to 8 kHz, so always send sample_rate: 8000 with pcm_mulaw / pcm_alaw:

// μ-law @ 8 kHz (US/telephony)
{ "container": "raw", "encoding": "pcm_mulaw", "sample_rate": 8000 }
// A-law @ 8 kHz (EU/telephony)
{ "container": "raw", "encoding": "pcm_alaw", "sample_rate": 8000 }

Unsupported formats. mp3 (container) and pcm_f32le (encoding) are not supported and return 400. Request wav + pcm_s16le and transcode client-side if you need another format.

Models

Model	Description
`gepard-1.0`	Dialogue-native model, tuned for conversational speech and low-latency streaming.

Billing

1 credit = 1 character of transcript, counted as described in Length limit (whitespace included). Billing is postpaid: a request starts only while your org’s balance is above 0. Because the balance is checked only when a request starts, your last request can take it slightly below zero.

/tts/bytes is all-or-nothing. The clip is returned only after generation finishes, so any failure is an HTTP error with no audio and isn’t charged. A successful response is charged, even if your client disconnects while downloading it.
/tts/sse is charged for the full transcript once at least one audio chunk has been delivered, including a stream that later fails with an error event. A stream that fails before its first audio chunk isn’t charged.
WebSocket turns are billed per turn and in 1,000-character batches. See WebSocket Streaming.

Examples

curl -N https://api.nineninesix.ai/tts/bytes \
  -H "Authorization: Bearer sk_996_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "gepard-1.0",
    "transcript": "Today is a wonderful day to build something people love!",
    "voice": { "mode": "id", "id": "<voice-id>" },
    "output_format": { "container": "wav", "encoding": "pcm_s16le", "sample_rate": 22050 }
  }' --output speech.wav

from cartesia import Cartesia

client = Cartesia(api_key="sk_996_your_api_key", base_url="https://api.nineninesix.ai")

audio = client.tts.bytes(
    model_id="gepard-1.0",
    transcript="Today is a wonderful day to build something people love!",
    voice={"mode": "id", "id": "<voice-id>"},
    output_format={"container": "wav", "encoding": "pcm_s16le", "sample_rate": 22050},
)

with open("speech.wav", "wb") as f:
    f.write(audio)

import { Cartesia } from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: "sk_996_your_api_key", baseURL: "https://api.nineninesix.ai" });

const res = await client.tts.generate({
  model_id: "gepard-1.0",
  transcript: "Today is a wonderful day to build something people love!",
  voice: { mode: "id", id: "<voice-id>" },
  output_format: { container: "wav", encoding: "pcm_s16le", sample_rate: 22050 },
});

const buffer = Buffer.from(await res.arrayBuffer());
fs.writeFileSync("speech.wav", buffer);

POST /tts/sse

Streams audio over Server-Sent Events for low time-to-first-audio without opening a WebSocket. The request body is identical to /tts/bytes, except the container must be raw (SSE can’t wrap a WAV/RIFF header):

{ "container": "raw", "encoding": "pcm_s16le", "sample_rate": 22050 }

Each event’s data is a JSON object. chunk events carry a base64-encoded slice of raw PCM; a final done event closes the stream:

data: {"type":"chunk","data":"<base64 pcm>","context_id":"..."}
data: {"type":"chunk","data":"<base64 pcm>","context_id":"..."}
data: {"type":"done","context_id":"..."}

The same length limit and 64 KB body cap apply. input_too_long (400) and payload_too_large (413) are returned as a normal HTTP error response before the event stream opens. Generation errors — overloaded (429), engine_error (usually 502), engine_unavailable (503), and the rare catch-all generation_failed (500) — can also arrive mid-stream as an error event. The HTTP status is already 200, and the stream ends after this event with no done, so handle error events as well as chunk and done:

data: {"type": "error", "context_id": "<context_id>", "done": true, "error_code": "overloaded", "status_code": 429, "title": "Overloaded", "message": "too many active streams; retry later", "doc_url": "", "request_id": "<request_id>"}

A stream is charged for the full transcript once its first audio chunk has been delivered, even if it later ends with an error event (see Billing). See Errors for every code.

import { Cartesia } from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: "sk_996_your_api_key", baseURL: "https://api.nineninesix.ai" });

const stream = await client.tts.generateSSE({
  model_id: "gepard-1.0",
  transcript: "Streaming speech, chunk by chunk.",
  voice: { mode: "id", id: "<voice-id>" },
  output_format: { container: "raw", encoding: "pcm_s16le", sample_rate: 22050 },
});

for await (const message of stream) {
  if (message.type === "chunk") {
    const pcm = Buffer.from(message.data, "base64"); // feed into your audio sink
  }
}

import base64
from cartesia import Cartesia

client = Cartesia(api_key="sk_996_your_api_key", base_url="https://api.nineninesix.ai")

for message in client.tts.sse(
    model_id="gepard-1.0",
    transcript="Streaming speech, chunk by chunk.",
    voice={"mode": "id", "id": "<voice-id>"},
    output_format={"container": "raw", "encoding": "pcm_s16le", "sample_rate": 22050},
):
    if message.type == "chunk":
        pcm = base64.b64decode(message.data)  # feed into your audio sink

WebSocket Streaming

For real-time, low-latency generation over a persistent connection — wss://api.nineninesix.ai/tts/websocket — see the WebSocket Streaming page, which includes the send/receive message schemas and an interactive Connect playground.

Getting Started

Guides

Resources

POST /tts/bytes

Request Body

Length limit

Output Format

Telephony (G.711)

Models

Billing

Examples

POST /tts/sse

WebSocket Streaming

​POST /tts/bytes

​Request Body

​Length limit

​Output Format

​Telephony (G.711)

​Models

​Billing

​Examples

​POST /tts/sse

​WebSocket Streaming

POST /tts/bytes

Request Body

Length limit

Output Format

Telephony (G.711)

Models

Billing

Examples

POST /tts/sse

WebSocket Streaming