Skip to content

Text to speech ​

POST /v1/audio/speech

Turn text into audio, either as a complete file or streamed while it is generated. Billed per character of input.

python
speech = client.audio.speech.create(
    model="cadence-tts",
    voice="clara",
    input="Your appointment is confirmed for Tuesday at 10am.",
    response_format="mp3",
)
speech.write_to_file("speech.mp3")
js
const speech = await client.audio.speech.create({
  model: 'cadence-tts',
  voice: 'clara',
  input: 'Your appointment is confirmed for Tuesday at 10am.',
  response_format: 'mp3',
})
fs.writeFileSync('speech.mp3', Buffer.from(await speech.arrayBuffer()))
bash
curl https://api.xvoice.dev/v1/audio/speech \
  -H "Authorization: Bearer $XVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cadence-tts",
    "voice": "clara",
    "input": "Your appointment is confirmed for Tuesday at 10am.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

The response body is the audio, with the media type of the format you asked for (audio/wav, audio/mpeg or audio/pcm).

Request body ​

FieldTypeRequiredDescription
modelstringyesA TTS model id: cadence-tts
inputstringyesThe text to speak. At most 8,000 characters
voicestringyesA voice id, such as clara. See Voices
response_formatstringnowav (default), mp3 or pcm
streambooleannoStream the audio while it is generated. Default false
stream_formatstringnoaudio or sse. Setting either also turns streaming on
speednumbernoMust be 1.0, the default
languagestringnoThe language of input, as an ISO 639-1 code such as es. Defaults to the voice's own. See Languages
instructionsstringnoDelivery guidance, at most 1,000 characters. Accepted and ignored by cadence-tts

An input over 8,000 characters is rejected before any work is done and costs nothing. Split longer text at sentence boundaries and make one request per part.

Languages ​

Every voice has a native accent, its locale, and a list of languages it can speak. On cadence-tts, every voice speaks English (en) and Spanish (es).

Set language whenever input is not in the voice's own language. Without it, the text is read as if it were in the voice's language, and sounds wrong:

python
speech = client.audio.speech.create(
    model="cadence-tts",
    voice="clara",
    input="Su cita está confirmada para el martes a las diez.",
    extra_body={"language": "es"},
)

language takes a language code (es), not a locale (es-ES): the accent comes from the voice. A language the voice does not speak fails with unsupported_language, and the message lists what it does speak. Each voice's list is on GET /v1/voices.

Output formats ​

FormatWhat you get
wav16-bit PCM WAV, 24 kHz mono. Plays anywhere
mp3MP3. The smallest download
pcmRaw 16-bit little-endian samples, 24 kHz mono, no header. Best for streaming into an audio device

Which formats and speeds a model accepts is published on the model as speech_options, and the API enforces it. Read it rather than hard-coding a list, so a model added later works without a code change:

python
model = client.models.retrieve("cadence-tts")
model.speech_options
# {"response_formats": ["wav", "pcm", "mp3"], "streamable_formats": ["wav", "pcm", "mp3"],
#  "speed": {"min": 1.0, "max": 1.0}, "instructions": false}

Asking for a format or speed the model does not offer fails with unsupported_response_format or unsupported_speed, and the message lists what the model does accept. See speech_options.

Streaming ​

A complete file is ready only once all of it has been generated. When you stream, the first audio arrives in a fraction of a second whatever the length of the text, so playback can start right away. Stream whenever someone is waiting to hear the result, as in a voice agent or a read-aloud button.

python
with client.audio.speech.with_streaming_response.create(
    model="cadence-tts",
    voice="clara",
    input=long_text,
    response_format="pcm",
    stream_format="audio",
) as response:
    for chunk in response.iter_bytes():
        player.write(chunk)
js
const response = await client.audio.speech.create({
  model: 'cadence-tts',
  voice: 'clara',
  input: longText,
  response_format: 'pcm',
  stream_format: 'audio',
})

for await (const chunk of response.body) {
  player.write(chunk)
}
bash
curl https://api.xvoice.dev/v1/audio/speech \
  -H "Authorization: Bearer $XVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "cadence-tts", "voice": "clara", "input": "...", "response_format": "pcm", "stream": true}' \
  --no-buffer | ffplay -f s16le -ar 24000 -ch_layout mono -nodisp -autoexit -

Choosing a format to stream:

  • pcm gives the lowest latency. Each chunk is raw samples that can go straight to an audio device. To save the result as a file, add a WAV header once the stream ends, or convert it with ffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wav.
  • wav starts with a header written before the clip's length is known, so its size fields hold the "unknown length" marker (0xFFFFFFFF), as ffmpeg writes when streaming. Browsers, ffmpeg, sox and soundfile play it to the end. Strict readers such as Python's wave module report a wrong length. If you need an exact header, request the file without streaming.
  • mp3 is the smallest on the wire, but arrives in larger chunks than pcm, so the first audio comes a little later.

speed must be 1.0 while streaming, on every model.

Server-sent events ​

stream_format="sse" sends the same audio as server-sent events, base64-encoded in JSON, followed by a final event:

text
event: speech.audio.delta
data: {"type":"speech.audio.delta","audio":"<base64>","response_format":"pcm"}

event: speech.audio.done
data: {"type":"speech.audio.done","usage":{...}}

Use it when the path between you and the player is easier to build on events than on a byte stream. It sends about a third more bytes than stream_format="audio".

Billing ​

You are billed per character of input. The count is taken before generation starts, so you know the cost of a request before any audio exists. Prices are on xvoice.dev.

  • A request that fails before the first audio is produced is not billed. That includes a request that produces no audio at all, which returns 500 model_error rather than an empty 200.
  • A request you disconnect from partway through a stream is billed in full, because the work has been done.

Errors ​

CodeStatusCause
validation_error422The body failed validation, such as an input over 8,000 characters. param names the field
invalid_model400No such model, or not a TTS model
invalid_voice404No such voice
voice_not_supported400The voice exists but this model cannot use it
unsupported_language400The voice does not speak language on this model
unsupported_response_format400The model does not produce this format, or cannot stream it
unsupported_speed400speed is outside the model's range, or is not 1.0 while streaming
invalid_input400The model could not process this text
input_too_long400The text is longer than the model can handle in one request
model_unavailable404The model cannot serve requests right now. Retry later
model_error500The model failed, or produced no audio. Retry once
model_overloaded503The model is at capacity. Retry after retry-after
service_unavailable503A temporary problem on our side. Retry after retry-after
stream_interrupted—Sent in band: the stream ended early. See Errors after a 200

Account-level errors (401, 402, 429) are listed on Errors.

xVoice is a product of Stochastic Inc.