Skip to main content
Every synthesis request names a voice by UUID. The voice determines which model runs, so it is the first thing to settle.

​
Built-in voices

Three voices are available to every organization and are a reasonable default for most applications:

​
Listing everything available to you

List Voices returns the built-ins, anything you have cloned, and anything added from the public library:
The native /v2/tts and /v2/tts/ws surfaces require a UUID. Two voices can share a display name, so resolving one would mean guessing which you meant. The OpenAI-compatible endpoint also accepts its documented OpenAI voice aliases.

​
Prefer a BTTS_V3 voice

BTTS_V3 is the current generation: highest fidelity, and the expressiveness and stability controls are calibrated for it. It renders natively at 48 kHz, so requesting 48 kHz avoids a resample. BTTS_V2 voices still synthesize. The controls are not tuned for them and will have less predictable effects. The x-model response header tells you which model a voice resolved to.

​
Cloning a voice

A clone needs one clean sample of about ten seconds. Quality of the sample sets the ceiling on quality of the voice, so it is worth trimming properly:
  • One speaker, clearly enunciated
  • No background noise, music, or reverb
  • At least 100 ms of silence at each end, so nothing is clipped mid-word
  • Emotional variety in the delivery, which yields a more expressive clone
Both engines are single-sample by design and cover 17+ languages. BTTS_V3 is the default and what you want unless you have a specific reason to pin the previous generation. Clone from the dashboard at Voices → Studio, or programmatically with Clone Voice. A cloned voice is private to your organization and usable immediately.
If a clone sounds broken when it code-switches or speaks a language absent from the sample, the sample is the problem, not the settings. Clone again from a recording that contains the languages you need.

​
Per-voice defaults

Each voice carries its own default delivery settings, editable in Studio or through Update Voice Config. Anything you send in a request’s controls object overrides them for that request only. Set the defaults on the voice when every use should sound the same. Override per request when one flow needs a different read, such as a warm greeting and a flat account-balance readout from the same voice, for example. See Writing for speech for what the controls do.

​
The voice is fixed for a WebSocket session

On WSS /v2/tts/ws, the voice is set by init and holds for the life of the connection. That is what lets one warm synthesis session serve every turn. To change voices, open another connection.

​
Public library voices

Shared voices are published by other creators. Add one to your library with Add Library Voice before using it. Some carry a per-character creator fee on top of the standard rate. The exact charge for a request comes back in the x-cost header.
Docs for agents: llms.txt