Appearance
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.mp3The response body is the audio, with the media type of the format you asked for (audio/wav, audio/mpeg or audio/pcm).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | A TTS model id: cadence-tts |
input | string | yes | The text to speak. At most 8,000 characters |
voice | string | yes | A voice id, such as clara. See Voices |
response_format | string | no | wav (default), mp3 or pcm |
stream | boolean | no | Stream the audio while it is generated. Default false |
stream_format | string | no | audio or sse. Setting either also turns streaming on |
speed | number | no | Must be 1.0, the default |
language | string | no | The language of input, as an ISO 639-1 code such as es. Defaults to the voice's own. See Languages |
instructions | string | no | Delivery 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
| Format | What you get |
|---|---|
wav | 16-bit PCM WAV, 24 kHz mono. Plays anywhere |
mp3 | MP3. The smallest download |
pcm | Raw 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:
pcmgives 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 withffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wav.wavstarts 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 andsoundfileplay it to the end. Strict readers such as Python'swavemodule report a wrong length. If you need an exact header, request the file without streaming.mp3is the smallest on the wire, but arrives in larger chunks thanpcm, 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_errorrather than an empty200. - A request you disconnect from partway through a stream is billed in full, because the work has been done.
Errors
| Code | Status | Cause |
|---|---|---|
validation_error | 422 | The body failed validation, such as an input over 8,000 characters. param names the field |
invalid_model | 400 | No such model, or not a TTS model |
invalid_voice | 404 | No such voice |
voice_not_supported | 400 | The voice exists but this model cannot use it |
unsupported_language | 400 | The voice does not speak language on this model |
unsupported_response_format | 400 | The model does not produce this format, or cannot stream it |
unsupported_speed | 400 | speed is outside the model's range, or is not 1.0 while streaming |
invalid_input | 400 | The model could not process this text |
input_too_long | 400 | The text is longer than the model can handle in one request |
model_unavailable | 404 | The model cannot serve requests right now. Retry later |
model_error | 500 | The model failed, or produced no audio. Retry once |
model_overloaded | 503 | The model is at capacity. Retry after retry-after |
service_unavailable | 503 | A 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.