TTS request parameters

Updated November 3, 2026, based on the xAI Text to Speech page and Voice API reference. Sources: Text to Speech · Voice API.

Fine-tune your speech synthesis

The POST /v1/tts endpoint revolves around four main parameters in the JSON request body, plus a few optional settings. Each one gives you precise control over the generated audio, and understanding them lets you tailor synthesis to your use case.

The text parameter

Along with language, text is the only required parameter. It accepts a string of up to 60,000 characters, which can contain plain text or expressive tags (covered in the next section).

{
  "text": "Hello and welcome. Today, we're going to talk about artificial intelligence."
}

Beyond 60,000 characters, the HTTP request is rejected. For longer texts, xAI recommends WebSocket, which has no total length limit (lessons 9 to 12), or splitting the text into segments whose audio you concatenate. Split at natural boundaries (ends of sentences, ends of paragraphs) for a smooth result.

The voice_id parameter

This parameter sets the voice used for synthesis. It’s optional and defaults to eve. IDs are case-insensitive: Eve, EVE, and eve are equivalent.

xAI offers 28 built-in voices (as of November 3, 2026), the same as for the voice agent, plus custom voices created with the Custom Voices API. The five original voices, as xAI describes them:

• eve: energetic and upbeat, British accent
• ara: warm and friendly
• rex: confident and clear
• sal: smooth and balanced
• leo: authoritative and powerful, British accent

The other 23 (carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora, and liora) are described, with their use cases, on the xAI Text to Speech page; GET /v1/tts/voices returns the current list (lesson 3).

{
  "text": "Welcome to this tutorial.",
  "voice_id": "rex",
  "language": "en"
}

According to xAI, every voice speaks every supported language. Your choice of voice doesn’t affect the price, which is based on the number of characters.

The language parameter

This parameter is required. It accepts a BCP-47 code or the special value auto for automatic language detection.

The 20 supported languages are:

Automatic detection (auto) works well for single-language texts, but for texts that mix several languages, state the main language explicitly.

The output_format parameter

This optional parameter is a JSON object that controls the audio output format. It has three sub-parameters.

codec

The codec sets the encoding format:

• mp3 (default): a compressed format, ideal for the web and streaming
• wav: a lossless format, better quality but larger files
• pcm: raw audio with no header, for processing pipelines
• mulaw / ulaw: the G.711 mu-law codec for telephony
• alaw: the G.711 A-law codec for telephony

sample_rate

The sample rate in hertz. Accepted values: 8000, 16000, 22050, 24000 (default), 44100, 48000.

bit_rate

The bit rate in bits per second, for the MP3 codec only. Accepted values: 32000, 64000, 96000, 128000 (default), 192000.

{
  "text": "High-quality audio for production.",
  "voice_id": "ara",
  "language": "en",
  "output_format": {
    "codec": "wav",
    "sample_rate": 48000
  }
}

The speed parameter

speed sets the playback speed: 1.0 is normal speed (the default), and the range runs from 0.7 to 1.5. A slightly slower pace helps with dense educational content; above 1.2, always listen to the result again.

Recommended combinations

Key takeaways

• text and language are the only required parameters
• voice_id is optional (default: eve) and case-insensitive
• output_format controls the codec, sample rate, and bit rate; speed sets the speed (0.7 to 1.5)
• MP3 at 24 kHz / 128 kbps is a good default balance between quality and size
• For telephony, use mulaw or alaw at 8 kHz