Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/audio/text-to-speech (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Model Capabilities34# Text to Speech56Convert text into spoken audio with a single API call. The API supports a rich set of expressive voices, inline speech tags for fine-grained delivery control, and output formats from high-fidelity MP3 to telephony-optimized μ-law.78## Quick Start910Generate speech with a single API call:1112```bash13curl -X POST https://api.x.ai/v1/tts \14 -H "Authorization: Bearer $XAI_API_KEY" \15 -H "Content-Type: application/json" \16 -d '{17 "text": "Hello! Welcome to the xAI Text to Speech API.",18 "voice_id": "eve",19 "language": "en"20 }' \21 --output hello.mp322```2324```python customLanguage="pythonWithoutSDK"25import os26import requests2728response = requests.post(29 "https://api.x.ai/v1/tts",30 headers={31 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",32 "Content-Type": "application/json",33 },34 json={35 "text": "Hello! Welcome to the xAI Text to Speech API.",36 "voice_id": "eve",37 "language": "en",38 },39)40response.raise_for_status()4142with open("hello.mp3", "wb") as f:43 f.write(response.content)4445print(f"Saved {len(response.content):,} bytes to hello.mp3")46```4748```javascript customLanguage="javascriptWithoutSDK"49import fs from "fs";5051const response = await fetch("https://api.x.ai/v1/tts", {52 method: "POST",53 headers: {54 Authorization: `Bearer ${process.env.XAI_API_KEY}`,55 "Content-Type": "application/json",56 },57 body: JSON.stringify({58 text: "Hello! Welcome to the xAI Text to Speech API.",59 voice_id: "eve",60 language: "en",61 }),62});6364if (!response.ok) throw new Error(`TTS error ${response.status}`);6566const buffer = Buffer.from(await response.arrayBuffer());67fs.writeFileSync("hello.mp3", buffer);68console.log(`Saved ${buffer.length.toLocaleString()} bytes to hello.mp3`);69```7071```swift72import Foundation7374let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!75let url = URL(string: "https://api.x.ai/v1/tts")!76var request = URLRequest(url: url)77request.httpMethod = "POST"78request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")79request.setValue("application/json", forHTTPHeaderField: "Content-Type")80request.httpBody = try JSONSerialization.data(withJSONObject: [81 "text": "Hello! Welcome to the xAI Text to Speech API.",82 "voice_id": "eve",83 "language": "en",84])8586let (data, _) = try await URLSession.shared.data(for: request)87let fileURL = URL(fileURLWithPath: "hello.mp3")88try data.write(to: fileURL)8990print("Saved \(data.count) bytes to hello.mp3")91```9293The response body contains raw audio bytes. Save directly to a file or pipe to an audio player.9495[Try the Playground →](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech)9697[Live Voice Demos](https://x.ai/api/voice)9899[Get API Key](https://console.x.ai/team/default/api-keys?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=api-keys)100101## Request Body102103| Parameter | Type | Required | Description |104|-----------|------|----------|-------------|105| `text` | string | ✓ | The text to convert to speech. Maximum **60,000 characters**. Supports [speech tags](#speech-tags). |106| `voice_id` | string | | Voice to use for synthesis. Defaults to `eve`. See [Voices](#voices). |107| `language` | string | ✓ | BCP-47 language code (e.g. `en`, `zh`, `pt-BR`) or `auto` for automatic language detection. See [Supported Languages](#supported-languages). |108| `output_format` | object | | Output format configuration. Defaults to MP3 at 24 kHz / 128 kbps. See [Output Formats](#output-formats). |109| `speed` | number | | Speech speed multiplier. `1.0` is normal speed. Values below `1.0` slow down speech, values above `1.0` speed it up. Range: `0.7` to `1.5`. Defaults to `1.0`. |110| `optimize_streaming_latency` | integer | | Latency optimization level for streaming synthesis. `0` (default): No optimization — best audio quality. `1`: Reduced first-chunk size for lower time-to-first-audio, with minor quality tradeoff at chunk boundaries. `2`: Further reduced first-chunk size for lowest time-to-first-audio, with more noticeable quality tradeoff at chunk boundaries. |111| `text_normalization` | boolean | | Enable text normalization before synthesis. When `true`, the model normalizes written-form text (e.g. numbers, abbreviations, symbols) into spoken-form before generating audio. Defaults to `false`. |112| `with_timestamps` | boolean | | Return character-level timing metadata alongside the audio. When `true`, the response is a JSON envelope containing base64-encoded audio plus per-character start/end times. Adds latency for the post-synthesis alignment pass. Defaults to `false`. See [Character-level timestamps](#character-level-timestamps). |113| `replace` | object | | Map of phrases to spoken substitutions applied before synthesis. Values may be respellings (`{"Acme Mobile": "Acme Mobull"}`) or [IPA](#phonetic-pronunciations-with-ipa) phonetics (`{"nginx": "/ˈɛndʒɪn ˈɛks/"}`). See [Pronunciation Replacements](#pronunciation-replacements). |114115### Example with all options116117```json118{119 "text": "Hello! This is a high-fidelity text to speech example.",120 "voice_id": "ara",121 "language": "en",122 "output_format": {123 "codec": "mp3",124 "sample_rate": 44100,125 "bit_rate": 192000126 },127 "speed": 1.2128}129```130131## Voices132133Each voice has a distinct personality. Listen to samples and choose the best fit for your use case (`eve` is the default):134135Voice IDs are **case-insensitive** - `eve`, `Eve`, and `EVE` all work. [Preview all voices in the playground →](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech)136137### Custom voices138139Clone any voice from a short reference clip with the [Custom Voices API](/developers/model-capabilities/audio/custom-voices), or create one for free in the [console](https://console.x.ai/team/default/voice/voice-library?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=voice-library). To find your custom voice ID in the console, click the three-dot menu on the voice card and select **Copy Voice ID**. Then pass it as `voice_id`:140141```bash142# Replace YOUR_VOICE_ID with your custom voice ID from the console143# or the GET /v1/custom-voices endpoint.144curl -X POST https://api.x.ai/v1/tts \145 -H "Authorization: Bearer $XAI_API_KEY" \146 -H "Content-Type: application/json" \147 -d '{148 "text": "Hello! This is my custom voice.",149 "voice_id": "YOUR_VOICE_ID",150 "language": "en"151 }' \152 --output hello.mp3153```154155```python customLanguage="pythonWithoutSDK"156import os157import requests158159response = requests.post(160 "https://api.x.ai/v1/tts",161 headers={162 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",163 "Content-Type": "application/json",164 },165 json={166 "text": "Hello! This is my custom voice.",167 "voice_id": "YOUR_VOICE_ID", # replace with your custom voice ID168 "language": "en",169 },170)171response.raise_for_status()172with open("hello.mp3", "wb") as f:173 f.write(response.content)174```175176```javascript customLanguage="javascriptWithoutSDK"177import fs from "fs";178179const response = await fetch("https://api.x.ai/v1/tts", {180 method: "POST",181 headers: {182 Authorization: `Bearer ${process.env.XAI_API_KEY}`,183 "Content-Type": "application/json",184 },185 body: JSON.stringify({186 text: "Hello! This is my custom voice.",187 voice_id: "YOUR_VOICE_ID", // replace with your custom voice ID188 language: "en",189 }),190});191if (!response.ok) throw new Error(`TTS error ${response.status}: ${await response.text()}`);192fs.writeFileSync("hello.mp3", Buffer.from(await response.arrayBuffer()));193```194195You can also list voices programmatically with the [Text to speech - List voices](/developers/rest-api-reference/inference/voice#text-to-speech---list-voices) endpoint:196197```bash198curl -s https://api.x.ai/v1/tts/voices \199 -H "Authorization: Bearer $XAI_API_KEY"200```201202```python customLanguage="pythonWithoutSDK"203import os204import requests205206response = requests.get(207 "https://api.x.ai/v1/tts/voices",208 headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},209)210for voice in response.json()["voices"]:211 print(f"{voice['voice_id']:5s} {voice['name']}")212```213214```javascript customLanguage="javascriptWithoutSDK"215const response = await fetch("https://api.x.ai/v1/tts/voices", {216 headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },217});218const { voices } = await response.json();219voices.forEach((v) => console.log(`${v.voice_id} ${v.name}`));220```221222```swift223import Foundation224225let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!226let url = URL(string: "https://api.x.ai/v1/tts/voices")!227var request = URLRequest(url: url)228request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")229230let (data, _) = try await URLSession.shared.data(for: request)231let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]232let voices = json["voices"] as! [[String: Any]]233for voice in voices {234 print("\(voice["voice_id"]!) \(voice["name"]!)")235}236```237238## Supported Languages239240The TTS API supports 20 languages via BCP-47 language codes. Use `auto` for automatic language detection, or specify a language code explicitly for consistent results.241242Language code validation is **case-insensitive** — `en`, `EN`, and `En` all work.243244| Language | Language Code |245|----------|---------------|246| Auto-detect | `auto` |247| English | `en` |248| Arabic (Egypt) | `ar-EG` |249| Arabic (Saudi Arabia) | `ar-SA` |250| Arabic (United Arab Emirates) | `ar-AE` |251| Bengali | `bn` |252| Chinese (Simplified) | `zh` |253| French | `fr` |254| German | `de` |255| Hindi | `hi` |256| Indonesian | `id` |257| Italian | `it` |258| Japanese | `ja` |259| Korean | `ko` |260| Portuguese (Brazil) | `pt-BR` |261| Portuguese (Portugal) | `pt-PT` |262| Russian | `ru` |263| Spanish (Mexico) | `es-MX` |264| Spanish (Spain) | `es-ES` |265| Turkish | `tr` |266| Vietnamese | `vi` |267268The model is also capable of generating speech in additional languages beyond those listed above, with varying degrees of accuracy.269270## Speech Tags271272*Example:* So I walked in and \[pause] there it was. \[laugh] I honestly could not believe it! \<whisper>It was a secret the whole time.\</whisper> Pretty cool, right?273274Add inline speech tags to your text for expressive delivery. There are two types of tags:275276* **Inline tags** `[tag]` — placed at a specific point in the text to produce a vocal expression (e.g. a laugh or pause)277* **Wrapping tags** `<tag>text</tag>` — wrap a section of text to change how it is delivered (e.g. whispering, singing)278279### Inline Tags280281Insert these where the expression should occur. Click any tag to hear an example:282283| Category | Tags |284|----------|------|285| **Pauses** | |286| **Laughter & crying** | |287| **Mouth sounds** | |288| **Breathing** | |289290### Wrapping Tags291292Wrap text to change delivery style. Use an opening tag and a matching closing tag. Click any tag to hear an example:293294| Category | Tags |295|----------|------|296| **Volume & intensity** | |297| **Pitch & speed** | |298| **Vocal style** | |299300### Examples301302```bash303# Inline tags304curl -X POST https://api.x.ai/v1/tts \305 -H "Authorization: Bearer $XAI_API_KEY" \306 -H "Content-Type: application/json" \307 -d '{308 "text": "So I walked in and [pause] there it was. [laugh] I honestly could not believe it!",309 "voice_id": "eve",310 "language": "en"311 }' \312 --output expressive.mp3313314# Wrapping tags315curl -X POST https://api.x.ai/v1/tts \316 -H "Authorization: Bearer $XAI_API_KEY" \317 -H "Content-Type: application/json" \318 -d '{319 "text": "I need to tell you something. <whisper>It is a secret.</whisper> Pretty cool, right?",320 "voice_id": "eve",321 "language": "en"322 }' \323 --output whisper.mp3324```325326```python customLanguage="pythonWithoutSDK"327import os328import requests329330# Inline tags331response = requests.post(332 "https://api.x.ai/v1/tts",333 headers={334 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",335 "Content-Type": "application/json",336 },337 json={338 "text": "So I walked in and [pause] there it was. [laugh] I honestly could not believe it!",339 "voice_id": "eve",340 "language": "en",341 },342)343response.raise_for_status()344345with open("expressive.mp3", "wb") as f:346 f.write(response.content)347348# Wrapping tags349response = requests.post(350 "https://api.x.ai/v1/tts",351 headers={352 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",353 "Content-Type": "application/json",354 },355 json={356 "text": "I need to tell you something. <whisper>It is a secret.</whisper> Pretty cool, right?",357 "voice_id": "eve",358 "language": "en",359 },360)361response.raise_for_status()362363with open("whisper.mp3", "wb") as f:364 f.write(response.content)365```366367```javascript customLanguage="javascriptWithoutSDK"368// Inline tags369const response = await fetch("https://api.x.ai/v1/tts", {370 method: "POST",371 headers: {372 Authorization: `Bearer ${process.env.XAI_API_KEY}`,373 "Content-Type": "application/json",374 },375 body: JSON.stringify({376 text: "So I walked in and [pause] there it was. [laugh] I honestly could not believe it!",377 voice_id: "eve",378 language: "en",379 }),380});381382// Wrapping tags383const whisperResponse = await fetch("https://api.x.ai/v1/tts", {384 method: "POST",385 headers: {386 Authorization: `Bearer ${process.env.XAI_API_KEY}`,387 "Content-Type": "application/json",388 },389 body: JSON.stringify({390 text: "I need to tell you something. <whisper>It is a secret.</whisper> Pretty cool, right?",391 voice_id: "eve",392 language: "en",393 }),394});395```396397```swift398import Foundation399400let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!401let url = URL(string: "https://api.x.ai/v1/tts")!402403// Inline tags404var request = URLRequest(url: url)405request.httpMethod = "POST"406request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")407request.setValue("application/json", forHTTPHeaderField: "Content-Type")408request.httpBody = try JSONSerialization.data(withJSONObject: [409 "text": "So I walked in and [pause] there it was. [laugh] I honestly could not believe it!",410 "voice_id": "eve",411 "language": "en",412])413414let (data, _) = try await URLSession.shared.data(for: request)415try data.write(to: URL(fileURLWithPath: "expressive.mp3"))416417// Wrapping tags418request.httpBody = try JSONSerialization.data(withJSONObject: [419 "text": "I need to tell you something. <whisper>It is a secret.</whisper> Pretty cool, right?",420 "voice_id": "eve",421 "language": "en",422])423424let (whisperData, _) = try await URLSession.shared.data(for: request)425try whisperData.write(to: URL(fileURLWithPath: "whisper.mp3"))426```427428**Tips for speech tags:**429430* Place inline tags where the expression would naturally occur in conversation431* Combine tags with punctuation — `"Really? [laugh] That's incredible!"` produces more natural results than stacking tags432* Use `[pause]` or `[long-pause]` to add dramatic timing or let a thought land433* Wrapping tags work best around complete phrases — `<whisper>It is a secret.</whisper>` reads more naturally than wrapping individual words434* Combine styles for effect — `<slow><soft>Goodnight, sleep well.</soft></slow>`435436## Output Formats437438Control the audio codec, sample rate, and bit rate with the `output_format` object. When omitted, the default is **MP3 at 24 kHz / 128 kbps**.439440### Codecs441442| Codec | Content-Type | Best for |443|-------|-------------|----------|444| `mp3` | `audio/mpeg` | General use - wide compatibility, good compression |445| `wav` | `audio/wav` | Lossless audio - editing, post-production |446| `pcm` | `audio/pcm` | Raw audio - real-time processing pipelines |447| `mulaw` | `audio/basic` | Telephony (G.711 μ-law) |448| `alaw` | `audio/alaw` | Telephony (G.711 A-law) |449450### Sample Rates451452| Rate | Description |453|------|-------------|454| `8000` | Narrowband - telephony |455| `16000` | Wideband - speech recognition |456| `22050` | Standard - balanced quality |457| `24000` | High quality - **default**, recommended for most use cases |458| `44100` | CD quality - media production |459| `48000` | Professional - studio-grade audio |460461### Bit Rates (MP3 only)462463| Rate | Quality |464|------|---------|465| `32000` | Low - smallest file size |466| `64000` | Medium - good for speech |467| `96000` | Standard - balanced |468| `128000` | High - **default**, recommended |469| `192000` | Maximum - highest fidelity |470471### Example: High-fidelity MP3472473```json474{475 "text": "Crystal clear audio at maximum quality.",476 "voice_id": "rex",477 "language": "en",478 "output_format": {479 "codec": "mp3",480 "sample_rate": 44100,481 "bit_rate": 192000482 }483}484```485486### Example: Telephony (μ-law)487488```json489{490 "text": "Hello, thank you for calling. How can I help you today?",491 "voice_id": "ara",492 "language": "en",493 "output_format": {494 "codec": "mulaw",495 "sample_rate": 8000496 }497}498```499500## Character-level timestamps501502Set `with_timestamps` to `true` to receive per-character start and end timestamps. Ideal for syncing captions, karaoke highlights, real-time lip-sync, or other time-aligned applications.503504The response then changes from raw audio bytes to a JSON envelope (`Content-Type: application/json`) carrying the base64-encoded audio plus the character timings.505506### Requesting timestamps507508Add the flag to a normal request. The audio comes back inside the JSON body, not as raw bytes:509510```bash511curl -X POST https://api.x.ai/v1/tts \512 -H "Authorization: Bearer $XAI_API_KEY" \513 -H "Content-Type: application/json" \514 -d '{515 "text": "Hello world.",516 "voice_id": "eve",517 "language": "en",518 "with_timestamps": true519 }' \520 --output response.json521```522523```python customLanguage="pythonWithoutSDK"524import base64525import os526import requests527528response = requests.post(529 "https://api.x.ai/v1/tts",530 headers={531 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",532 "Content-Type": "application/json",533 },534 json={535 "text": "Hello world.",536 "voice_id": "eve",537 "language": "en",538 "with_timestamps": True,539 },540)541response.raise_for_status()542payload = response.json()543544# The audio is base64-encoded — decode it exactly like a normal response545with open("hello.mp3", "wb") as f:546 f.write(base64.b64decode(payload["audio"]))547548ts = payload["audio_timestamps"]549for char, (start, end) in zip(ts["graph_chars"], ts["graph_times"]):550 print(f"{char!r:>5} {start:.2f}s – {end:.2f}s")551print(f"duration: {payload['duration']:.2f}s")552```553554```javascript customLanguage="javascriptWithoutSDK"555import fs from "fs";556557const response = await fetch("https://api.x.ai/v1/tts", {558 method: "POST",559 headers: {560 Authorization: `Bearer ${process.env.XAI_API_KEY}`,561 "Content-Type": "application/json",562 },563 body: JSON.stringify({564 text: "Hello world.",565 voice_id: "eve",566 language: "en",567 with_timestamps: true,568 }),569});570if (!response.ok) throw new Error(`TTS error ${response.status}`);571572const payload = await response.json();573574// The audio is base64-encoded — decode it exactly like a normal response575fs.writeFileSync("hello.mp3", Buffer.from(payload.audio, "base64"));576577const { graph_chars, graph_times } = payload.audio_timestamps;578graph_chars.forEach((char, i) => {579 const [start, end] = graph_times[i];580 console.log(`${JSON.stringify(char).padStart(5)} ${start.toFixed(2)}s – ${end.toFixed(2)}s`);581});582console.log(`duration: ${payload.duration.toFixed(2)}s`);583```584585```swift586import Foundation587588// snake_case JSON keys map to camelCase via the decoder strategy below589struct TimedTts: Decodable {590 let audio: String591 let contentType: String592 let duration: Double593 let audioTimestamps: AudioTimestamps?594595 struct AudioTimestamps: Decodable {596 let graphChars: [String]597 let graphTimes: [[Double]]598 }599}600601let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!602var request = URLRequest(url: URL(string: "https://api.x.ai/v1/tts")!)603request.httpMethod = "POST"604request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")605request.setValue("application/json", forHTTPHeaderField: "Content-Type")606request.httpBody = try JSONSerialization.data(withJSONObject: [607 "text": "Hello world.",608 "voice_id": "eve",609 "language": "en",610 "with_timestamps": true,611])612613let (data, _) = try await URLSession.shared.data(for: request)614let decoder = JSONDecoder()615decoder.keyDecodingStrategy = .convertFromSnakeCase616let payload = try decoder.decode(TimedTts.self, from: data)617618// The audio is base64-encoded — decode it exactly like a normal response619try Data(base64Encoded: payload.audio)!.write(to: URL(fileURLWithPath: "hello.mp3"))620621if let ts = payload.audioTimestamps {622 for (char, time) in zip(ts.graphChars, ts.graphTimes) {623 print(String(format: "%5@ %.2fs – %.2fs", char as NSString, time[0], time[1]))624 }625}626print(String(format: "duration: %.2fs", payload.duration))627```628629### Response shape630631```json632{633 "audio": "<base64-encoded audio in the requested codec>",634 "content_type": "audio/mpeg",635 "duration": 0.92,636 "audio_timestamps": {637 "graph_chars": ["H", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d", "."],638 "graph_times": [639 [0.00, 0.06],640 [0.06, 0.12],641 [0.12, 0.18],642 [0.18, 0.24],643 [0.24, 0.34],644 [0.34, 0.40],645 [0.40, 0.48],646 [0.48, 0.54],647 [0.54, 0.62],648 [0.62, 0.68],649 [0.68, 0.78],650 [0.78, 0.92]651 ]652 }653}654```655656| Field | Type | Description |657|-------|------|-------------|658| `audio` | string | Base64-encoded audio in the requested codec. Decode and play like a normal response. |659| `content_type` | string | MIME type of the decoded audio (e.g. `audio/mpeg`, `audio/wav`). |660| `duration` | number | Total audio duration in seconds. |661| `audio_timestamps.graph_chars` | string\[] | Each input character, in order, including spaces, punctuation, and speech tags. |662| `audio_timestamps.graph_times` | number\[]\[] | Parallel array of `[start, end]` pairs in seconds. |663664`graph_chars` and `graph_times` are aligned by index, they match position by position. So graph\_chars\[i] is the character spoken during the time interval graph\_times\[i]. For `"Hello world."`:665666```text667char: H e l l o ␣ w o r l d .668start: 0.00 0.06 0.12 0.18 0.24 0.34 0.40 0.48 0.54 0.62 0.68 0.78669 └──────────── "Hello" ───────────┘ └──────────── "world." ──────────┘6700s ─────────────────────────────────────────────────────────────────────▶ 0.92s671```672673### Special characters674675`graph_chars` mirrors your input one-for-one, including spaces, punctuation, and speech tags. When one written token is spoken as several words, its timing is assigned to the first character. The rest of the characters interpolate within that same time span.676677This mostly happens with [`text_normalization`](#request-body) enabled, which expands symbols and numbers into words. With normalization on, `$5` is spoken as "five dollars" but is still only two characters: the `$` gets the full span for "five dollars", and the `5` gets an interpolated time inside it. So always step through `graph_chars` in order rather than slicing the input text by index.678679## Pronunciation Replacements680681Use `replace` to fix how specific words or phrases are pronounced. Each key is matched in your text and swapped for its replacement value **before** synthesis, so only the audio changes — you keep sending your original text, and you are billed on it.682683This is useful for brand names, acronyms, and domain terms. Mapping `"Acme Mobile"` to `"Acme Mobull"` makes the audio say it correctly while your request body still reads "Acme Mobile".684685```python customLanguage="pythonWithoutSDK"686response = requests.post(687 "https://api.x.ai/v1/tts",688 headers={"Authorization": f"Bearer {XAI_API_KEY}"},689 json={690 "text": "Welcome to Acme Mobile.",691 "voice_id": "eve",692 "language": "en",693 "replace": {"Acme Mobile": "Acme Mobull"},694 },695)696```697698```javascript customLanguage="javascriptWithoutSDK"699const response = await fetch("https://api.x.ai/v1/tts", {700 method: "POST",701 headers: {702 Authorization: `Bearer ${XAI_API_KEY}`,703 "Content-Type": "application/json"704 },705 body: JSON.stringify({706 text: "Welcome to Acme Mobile.",707 voice_id: "eve",708 language: "en",709 replace: { "Acme Mobile": "Acme Mobull" }710 })711});712```713714Matching behavior:715716* Matching is case-insensitive; the replacement is spoken using the casing you provide.717* Whole-word boundaries are required, so `Acme, Mobile`, `Acme-Mobile`, and `Acme Mobiles` do **not** match. In scripts written without spaces — Chinese, Japanese, Thai, Lao, Khmer, Burmese — matching is per character, so a one-character key also matches inside a longer word.718* When multiple keys share a prefix, the longest match wins.719* Keys match the text exactly as you send it, so write them as they appear in your input.720721#### Map limits722723The map is validated before any audio is generated, so a broken rule fails the request rather than silently dropping an entry:724725| Constraint | Limit | Error (`400`) |726|---|---|---|727| Entries per map | 200 | `replace has too many entries` |728| Key length | 100 characters | `replace key "…" is too long` |729| Value length | 128 characters | `replace value for "…" is too long` |730| Key characters | letters, digits, apostrophes, spaces | `replace key "C++" may not contain punctuation or symbols` |731| Keys non-blank | — | `replace keys must not be blank` |732| Keys distinct as phrases | compared case- and whitespace-insensitively | `replace keys "ACME" and "Acme" are the same phrase; keep one` |733| Text after substitution | 240,000 characters | `` `replace` expands the text to … characters `` |734735The last row bounds the **rewritten** text — watch it when a short key maps to a long value across a large body of text. Your 60,000-character input cap and your billing still count what you sent.736737The same `replace` map is available on the [Speech to Speech API](/developers/model-capabilities/audio/speech-to-speech#pronunciation-replacements) and on the [WebSocket endpoint](#session-configuration).738739> [!NOTE]740>741> Replacements change the text that is spoken. With `with_timestamps` enabled, `graph_chars` describes the **spoken** text, so it will contain the replacement characters rather than the characters you sent.742743### Phonetic pronunciations with IPA744745The model reads [IPA](https://www.internationalphoneticalphabet.org) directly in `text`:746747```json748{"text": "Restart /ˈɛndʒɪn ˈɛks/ on the edge nodes."}749```750751Put it in a `replace` value to keep phonetics out of the text you send — when the text is generated upstream, or when one entry should cover every occurrence in a document or a session.752753Phonetics earn their keep where pronunciation is a convention rather than something derivable from spelling: `nginx` is "engine X", `kubectl` is "kube cuttle", and `SQL` is "sequel" or "S-Q-L" by house style. Left alone the model spells these out, and not the same way twice; an entry makes the reading deterministic.754755```python customLanguage="pythonWithoutSDK"756response = requests.post(757 "https://api.x.ai/v1/tts",758 headers={"Authorization": f"Bearer {XAI_API_KEY}"},759 json={760 "text": "nginx is returning errors on the Acme Mobile edge nodes.",761 "voice_id": "eve",762 "language": "en",763 "replace": {764 "nginx": "/ˈɛndʒɪn ˈɛks/",765 "Acme Mobile": "Acme Mobull",766 },767 },768)769```770771```javascript customLanguage="javascriptWithoutSDK"772const response = await fetch("https://api.x.ai/v1/tts", {773 method: "POST",774 headers: {775 Authorization: `Bearer ${XAI_API_KEY}`,776 "Content-Type": "application/json"777 },778 body: JSON.stringify({779 text: "nginx is returning errors on the Acme Mobile edge nodes.",780 voice_id: "eve",781 language: "en",782 replace: {783 nginx: "/ˈɛndʒɪn ˈɛks/",784 "Acme Mobile": "Acme Mobull"785 }786 })787});788```789790Phonetic and respelled entries can share one map, as above.791792* Synthesize the word first. Well-known names are usually already right — `IEEE` comes out "I triple E" unprompted — and a redundant entry is upkeep with no benefit.793* Slashes are convention, not a marker: `/ˈɛndʒɪn ˈɛks/` and `ˈɛndʒɪn ˈɛks` are spoken identically and never read aloud.794* IPA belongs in the value. Keys stay the ordinary spelling you want to catch.795* Phonetics are unaffected by [`text_normalization`](#request-body), and work in any supported language.796797> [!WARNING]798>799> IPA is interpreted per symbol, so a typo yields a confidently wrong pronunciation rather than an error. Check symbols against the [IPA sound chart](https://www.internationalphoneticalphabet.org/ipa-sounds/) and listen to each new entry once before shipping it.800801## Best Practices802803Tips for getting the highest quality output from the TTS API.804805### Writing effective text806807* **Use natural punctuation.** Commas, periods, and question marks guide pacing and intonation. `"Wait, really?"` sounds more natural than `"Wait really"`.808* **Add emotional context.** Exclamation marks and question marks influence delivery - `"That's amazing!"` sounds enthusiastic while `"That's amazing."` is matter-of-fact.809* **Break long content into paragraphs.** Paragraph breaks create natural pauses and help the model maintain consistent quality across longer text.810* **Keep unary requests under 60,000 characters.** For longer content, use the [bidirectional WebSocket endpoint](#streaming-tts-websocket) which has no text length limit, or split into logical segments (by paragraph or sentence) and concatenate the audio output.811812### Integrating with AI coding assistants813814The [Cloud Console playground](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech) includes ready-made **agent instructions** you can copy and paste into tools like Cursor, GitHub Copilot, or Windsurf. The instructions are pre-configured with your current voice and format settings - open the playground, tweak your settings, and copy the prompt to get a tailored integration guide for your coding agent.815816### Optimizing for production817818* **Proxy requests server-side.** Never expose your API key in client-side code. Route TTS requests through your backend.819* **Cache generated audio.** If the same text is requested repeatedly, cache the audio bytes to save API calls and reduce latency.820* **Match the format to the use case.** Use `mulaw` or `alaw` at 8 kHz for telephony; `mp3` at 24 kHz for web; `wav` at 44.1+ kHz for post-production.821822## Browser Playback823824To play TTS audio in the browser, proxy the request through your backend and use the Web Audio API or an `<audio>` element:825826```javascript customLanguage="javascriptWithoutSDK"827// Client-side: fetch from your backend proxy, then play828async function speakText(text, voiceId = "eve") {829 const response = await fetch("/api/tts", {830 method: "POST",831 headers: { "Content-Type": "application/json" },832 body: JSON.stringify({ text, voice_id: voiceId }),833 });834835 if (!response.ok) throw new Error("TTS request failed");836837 const blob = await response.blob();838 const url = URL.createObjectURL(blob);839840 const audio = new Audio(url);841 audio.addEventListener("ended", () => URL.revokeObjectURL(url));842 await audio.play();843}844845// Usage846await speakText("Hello from the browser!");847```848849> [!WARNING]850>851> **Never call the TTS API directly from the browser** - this would expose your API key. Always proxy through your backend.852853### Browser gotchas854855**Safari returns `Infinity` for `audio.duration` on blob URLs.** The `loadedmetadata` event fires but `audio.duration` is `Infinity`, breaking seek bars and time displays. Use `AudioContext.decodeAudioData()` instead:856857```javascript customLanguage="javascriptWithoutSDK"858async function getAudioDuration(arrayBuffer) {859 const AudioCtx = window.AudioContext || window.webkitAudioContext;860 const ctx = new AudioCtx();861 // Clone the buffer - decodeAudioData detaches the original862 const decoded = await ctx.decodeAudioData(arrayBuffer.slice(0));863 const durationMs = Math.round(decoded.duration * 1000);864 await ctx.close();865 return durationMs;866}867```868869**`AudioContext` must be created during a user gesture on Safari.** Safari permanently suspends an `AudioContext` created outside a click/tap handler, with no way to resume it. Chrome is more lenient. Always create or resume the context in your button's click handler, before any `await`:870871```javascript customLanguage="javascriptWithoutSDK"872// Create the AudioContext once, in a click handler873let audioCtx;874button.addEventListener("click", async () => {875 // This MUST happen synchronously in the click handler for Safari876 if (!audioCtx) audioCtx = new AudioContext();877 if (audioCtx.state === "suspended") await audioCtx.resume();878879 // Now it's safe to fetch and play audio asynchronously880 const response = await fetch("/api/tts", { /* ... */ });881 const arrayBuffer = await response.arrayBuffer();882 const decoded = await audioCtx.decodeAudioData(arrayBuffer);883 const source = audioCtx.createBufferSource();884 source.buffer = decoded;885 source.connect(audioCtx.destination);886 source.start();887});888```889890**Raw codecs (pcm, mulaw, alaw) are not playable in the browser.** `AudioContext.decodeAudioData()` and `<audio>` elements only support container formats like MP3 and WAV. Use `mp3` or `wav` for browser playback. If you're working with raw formats server-side (e.g., piping to telephony), estimate duration from byte count:891892```javascript customLanguage="javascriptWithoutSDK"893// PCM = 16-bit LE (2 bytes/sample), mulaw/alaw = 8-bit (1 byte/sample)894const bytesPerSample = codec === "pcm" ? 2 : 1;895const durationMs = Math.round((byteLength / bytesPerSample / sampleRate) * 1000);896```897898**Revoke blob URLs to avoid memory leaks.** Each `URL.createObjectURL()` call allocates memory that persists until explicitly freed. Revoke URLs when playback ends. For downloads, delay revocation so the browser finishes saving the file:899900```javascript customLanguage="javascriptWithoutSDK"901// Playback: revoke when done902const url = URL.createObjectURL(blob);903const audio = new Audio(url);904audio.addEventListener("ended", () => URL.revokeObjectURL(url));905906// Downloads: delay revocation907const downloadUrl = URL.createObjectURL(blob);908const a = document.createElement("a");909a.href = downloadUrl;910a.download = "speech.mp3";911a.click();912setTimeout(() => URL.revokeObjectURL(downloadUrl), 10_000);913```914915## Error Handling916917| Status | Meaning | Action |918|--------|---------|--------|919| `200` | Success | Audio bytes in the response body |920| `400` | Bad request | Check: text is non-empty, under 60,000 chars; codec and sample rate are valid |921| `401` | Unauthorized | API key is missing or invalid |922| `404` | Not found | Unknown `voice_id` — verify via `GET /v1/tts/voices` (built-in) or `GET /v1/custom-voices` (custom) |923| `429` | Rate limited | Back off and retry with exponential delay |924| `503` | Service unavailable | TTS service is temporarily unavailable - retry |925| `500` | Server error | Retry with exponential backoff |926927### Retry with backoff928929```python customLanguage="pythonWithoutSDK"930import os931import time932import requests933934def generate_speech(text, language="en", voice_id="eve", max_retries=3):935 for attempt in range(max_retries):936 response = requests.post(937 "https://api.x.ai/v1/tts",938 headers={939 "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",940 "Content-Type": "application/json",941 },942 json={"text": text, "language": language, "voice_id": voice_id},943 )944 if response.ok:945 return response.content946 if response.status_code in (429, 500, 503):947 wait = 2 ** attempt948 time.sleep(wait)949 continue950 response.raise_for_status() # Non-retryable error951 raise RuntimeError("Max retries exceeded")952```953954```javascript customLanguage="javascriptWithoutSDK"955async function generateSpeech(text, language = "en", voiceId = "eve", maxRetries = 3) {956 for (let attempt = 0; attempt < maxRetries; attempt++) {957 const response = await fetch("https://api.x.ai/v1/tts", {958 method: "POST",959 headers: {960 Authorization: `Bearer ${process.env.XAI_API_KEY}`,961 "Content-Type": "application/json",962 },963 body: JSON.stringify({ text, language, voice_id: voiceId }),964 });965966 if (response.ok) return Buffer.from(await response.arrayBuffer());967968 if ([429, 500, 503].includes(response.status)) {969 await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));970 continue;971 }972 throw new Error(`TTS error ${response.status}: ${await response.text()}`);973 }974 throw new Error("Max retries exceeded");975}976```977978```swift979import Foundation980981func generateSpeech(text: String, language: String = "en", voiceId: String = "eve", maxRetries: Int = 3) async throws -> Data {982 let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!983 let url = URL(string: "https://api.x.ai/v1/tts")!984985 for attempt in 0..<maxRetries {986 var request = URLRequest(url: url)987 request.httpMethod = "POST"988 request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")989 request.setValue("application/json", forHTTPHeaderField: "Content-Type")990 request.httpBody = try JSONSerialization.data(withJSONObject: [991 "text": text, "language": language, "voice_id": voiceId,992 ])993994 let (data, response) = try await URLSession.shared.data(for: request)995 let status = (response as! HTTPURLResponse).statusCode996 if status == 200 { return data }997 if [429, 500, 503].contains(status) {998 try await Task.sleep(nanoseconds: UInt64(pow(2.0, Double(attempt))) * 1_000_000_000)999 continue1000 }1001 throw URLError(.badServerResponse)1002 }1003 throw URLError(.timedOut)1004}1005```10061007## Limits10081009The unary/server-streamed endpoints and the bidirectional WebSocket endpoint have different limits:10101011| | Unary & server-streamed (`POST /v1/tts`) | Bidirectional WebSocket (`wss://api.x.ai/v1/tts`) |1012|---|---:|---|1013| **Max text length** | 60,000 characters per request | No limit — individual `text.delta` messages capped at 60,000 characters each |1014| **Request timeout** | 15 minutes | No timeout (connection stays open) |1015| **Concurrent sessions** | — | 50 per team |1016| **[`replace`](#map-limits) map** | 200 entries; keys ≤ 100 and values ≤ 128 characters | Same, per `session.update` |1017| **Text after `replace`** | 240,000 characters | 240,000 characters per utterance |10181019For content exceeding 60,000 characters, use the [bidirectional WebSocket endpoint](#streaming-tts-websocket) which has no text length limit.10201021## Streaming TTS (WebSocket)10221023For real-time audio generation, open a WebSocket connection to the streaming TTS endpoint. Text is streamed in as deltas and audio is streamed back as base64-encoded chunks — ideal for interactive applications where you want audio to start playing before the full text is available.10241025**Endpoint:** `wss://api.x.ai/v1/tts`10261027> [!NOTE]1028>1029> **Never expose your API key in client-side code.** Always proxy WebSocket connections through your backend.10301031### Connection10321033Open a WebSocket connection with query parameters to configure language, voice, and audio format:10341035```1036GET /v1/tts?language=en&voice=eve&codec=mp3&sample_rate=24000&bit_rate=1280001037Upgrade: websocket1038Authorization: Bearer $XAI_API_KEY1039```10401041| Parameter | Required | Default | Accepted values |1042|-----------|----------|---------|-----------------|1043| `voice` | | | Any built-in voice ID (see [Voices](#voices)) or a [custom voice ID](/developers/model-capabilities/audio/custom-voices) |1044| `language` | ✓ | | `auto` or BCP-47 codes (e.g. `en`, `zh`, `pt-BR`). See [Supported Languages](#supported-languages). |1045| `codec` | | `mp3` | `mp3`, `wav`, `pcm`, `mulaw` (or `ulaw`), `alaw` |1046| `sample_rate` | | `24000` | `8000`, `16000`, `22050`, `24000`, `44100`, `48000` |1047| `bit_rate` | | `128000` | `32000`, `64000`, `96000`, `128000`, `192000` (MP3 only) |1048| `speed` | | `1.0` | Speech speed multiplier (`0.7` to `1.5`) |1049| `optimize_streaming_latency` | | `0` | `0` (off, best quality), `1` (moderate, lower time-to-first-audio), `2` (aggressive, lowest time-to-first-audio) |1050| `text_normalization` | | `false` | `true`, `false` |1051| `with_timestamps` | | `false` | `true`, `false`. When `true`, each `audio.delta` carries `audio_timestamps` and `audio_duration` for the characters in that chunk. |10521053An invalid `voice`, `language`, `codec`, or `sample_rate` is rejected **before** the WebSocket upgrade with an HTTP 400 or 404.10541055### Client → Server Messages10561057Send text to the server as JSON text frames. Split your text across multiple `text.delta` messages, then signal the end of the utterance with `text.done`:10581059```json1060{"type": "text.delta", "delta": "Here is some text. "}1061{"type": "text.delta", "delta": "More text follows."}1062{"type": "text.done"}1063```10641065| Event | Description |1066|-------|-------------|1067| `text.delta` | A chunk of text to synthesize. Individual deltas are capped at **60,000 characters**. |1068| `text.done` | Signals the end of the current utterance. The server will finish generating audio and send `audio.done`. |1069| `text.clear` | Cancel the current utterance. The server stops generating audio, discards any buffered data, and responds with `audio.clear`. |1070| `session.update` | Set or change the [`replace`](#session-configuration) map for the session. Accepted at any point; it takes effect on the next utterance to begin. |10711072### Server → Client Messages10731074The server responds with base64-encoded audio chunks and a completion event:10751076```json1077{"type": "audio.delta", "delta": "<base64-encoded audio bytes>"}1078{"type": "audio.done", "trace_id": "uuid"}1079{"type": "audio.clear"}1080{"type": "error", "message": "description"}1081```10821083| Event | Description |1084|-------|-------------|1085| `audio.delta` | A chunk of base64-encoded audio in the codec specified at connection time. Decode and enqueue for playback. When the connection was opened with `with_timestamps=true`, also carries `audio_timestamps` (`graph_chars` + `graph_times`) and `audio_duration` for the characters in that chunk. See [Character-level timestamps](#character-level-timestamps). |1086| `audio.done` | All audio for the current utterance has been sent. Includes a `trace_id` for debugging. |1087| `audio.clear` | Confirms that the current utterance was cancelled in response to `text.clear`. The connection is ready for the next utterance. |1088| `session.updated` | Acknowledges a `session.update` and echoes the `replace` map now in effect. |1089| `error` | An error occurred. The `message` field contains a human-readable description. |10901091### Session Configuration10921093[Pronunciation replacements](#pronunciation-replacements) are configured with a `session.update` message. Send it before the first `text.delta` to have it cover the whole connection:10941095```json1096{"type": "session.update", "replace": {"Acme Mobile": "Acme Mobull"}}1097{"type": "text.delta", "delta": "Welcome to Acme Mobile."}1098{"type": "text.done"}1099```11001101The server replies with `{"type": "session.updated", "replace": {...}}` echoing the map now in effect. Values may be respellings or [IPA](#phonetic-pronunciations-with-ipa), exactly as over HTTP.11021103The map applies to **every utterance** for the life of the connection, including after `text.clear`. Send another `session.update` at any point to change it; no reconnect needed. Which utterance it reaches is decided by arrival:11041105> An utterance is spoken with the map that was in effect when its **first text** arrived.11061107An update landing mid-utterance therefore takes effect on the next one, so a phrase is never matched under two maps.11081109Matching runs across `text.delta` boundaries, so a phrase split over two messages still matches.11101111The [same map limits](#map-limits) apply. A map that fails validation is answered with an `error` frame, leaves the map in effect unchanged, and keeps the connection open — but a map that expands a turn past 240,000 characters ends the session, since by then the oversized text has already been accepted.11121113### Multi-Utterance Sessions11141115The connection stays open after `audio.done`. You can immediately send another round of `text.delta` → `text.done` messages to synthesize additional text without reconnecting. This is useful for conversational UIs where you generate audio for each assistant response in sequence.11161117**Flow for multi-turn sessions:**111811191. **Turn 1:** Client sends `text.delta` → `text.done`11202. Server responds with `audio.delta` chunks → `audio.done`11213. Connection stays open11224. **Turn 2:** Client sends `text.delta` → `text.done`11235. Server responds with `audio.delta` chunks → `audio.done`11246. Repeat as needed11251126Each `text.done` flushes the accumulated text to generate audio. Once you receive `audio.done`, you can send more text for the next turn. The audio from each turn is independent — content from turn 1 does not bleed into turn 2.11271128```python customLanguage="pythonWithoutSDK"1129import asyncio1130import base641131import json1132import os11331134import websockets # pip install websockets11351136XAI_API_KEY = os.environ["XAI_API_KEY"]11371138async def multi_turn_tts(language: str = "en", voice: str = "eve", codec: str = "mp3"):1139 uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec={codec}"11401141 async with websockets.connect(1142 uri,1143 additional_headers={"Authorization": f"Bearer {XAI_API_KEY}"},1144 ) as ws:1145 # Turn 11146 await ws.send(json.dumps({"type": "text.delta", "delta": "Hello from turn one."}))1147 await ws.send(json.dumps({"type": "text.done"}))11481149 turn1_audio = bytearray()1150 async for msg in ws:1151 event = json.loads(msg)1152 if event["type"] == "audio.delta":1153 turn1_audio.extend(base64.b64decode(event["delta"]))1154 elif event["type"] == "audio.done":1155 print(f"Turn 1: {len(turn1_audio):,} bytes")1156 break1157 elif event["type"] == "error":1158 raise RuntimeError(event["message"])11591160 # Connection is still open — send turn 21161 await ws.send(json.dumps({"type": "text.delta", "delta": "And hello from turn two."}))1162 await ws.send(json.dumps({"type": "text.done"}))11631164 turn2_audio = bytearray()1165 async for msg in ws:1166 event = json.loads(msg)1167 if event["type"] == "audio.delta":1168 turn2_audio.extend(base64.b64decode(event["delta"]))1169 elif event["type"] == "audio.done":1170 print(f"Turn 2: {len(turn2_audio):,} bytes")1171 break1172 elif event["type"] == "error":1173 raise RuntimeError(event["message"])11741175asyncio.run(multi_turn_tts())1176```11771178```javascript customLanguage="javascriptWithoutSDK"1179// npm install ws1180// Node.js 22+ has a built-in WebSocket global — you can skip1181// the "ws" package and remove this import if you're on v22+.1182import WebSocket from "ws";11831184const apiKey = process.env.XAI_API_KEY;1185const language = "en";1186const voice = "eve";1187const codec = "mp3";1188const uri = `wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=${codec}`;11891190const ws = new WebSocket(uri, {1191 headers: { Authorization: `Bearer ${apiKey}` },1192});11931194let turn = 1;1195let audioChunks = [];11961197ws.on("open", () => {1198 // Start turn 11199 ws.send(JSON.stringify({ type: "text.delta", delta: "Hello from turn one." }));1200 ws.send(JSON.stringify({ type: "text.done" }));1201});12021203ws.on("message", (data) => {1204 const event = JSON.parse(data);12051206 if (event.type === "audio.delta") {1207 audioChunks.push(Buffer.from(event.delta, "base64"));1208 } else if (event.type === "audio.done") {1209 const audio = Buffer.concat(audioChunks);1210 console.log(`Turn ${turn}: ${audio.length.toLocaleString()} bytes`);1211 audioChunks = [];12121213 if (turn === 1) {1214 // Connection still open — send turn 21215 turn = 2;1216 ws.send(JSON.stringify({ type: "text.delta", delta: "And hello from turn two." }));1217 ws.send(JSON.stringify({ type: "text.done" }));1218 } else {1219 ws.close();1220 }1221 } else if (event.type === "error") {1222 console.error("Error:", event.message);1223 ws.close();1224 }1225});1226```12271228```swift1229import Foundation12301231let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!1232let language = "en"1233let voice = "eve"1234let codec = "mp3"1235let url = URL(string: "wss://api.x.ai/v1/tts?language=\(language)&voice=\(voice)&codec=\(codec)")!12361237var request = URLRequest(url: url)1238request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")12391240let task = URLSession.shared.webSocketTask(with: request)1241task.resume()12421243// Turn 11244try await task.send(.string("{\"type\":\"text.delta\",\"delta\":\"Hello from turn one.\"}"))1245try await task.send(.string("{\"type\":\"text.done\"}"))12461247var turn1Audio = Data()1248while true {1249 let message = try await task.receive()1250 guard case .string(let text) = message,1251 let json = try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any],1252 let type = json["type"] as? String else { continue }12531254 if type == "audio.delta", let delta = json["delta"] as? String,1255 let chunk = Data(base64Encoded: delta) {1256 turn1Audio.append(chunk)1257 } else if type == "audio.done" {1258 print("Turn 1: \(turn1Audio.count) bytes")1259 break1260 } else if type == "error" {1261 print("Error: \(json["message"] ?? "unknown")")1262 break1263 }1264}12651266// Connection still open — send turn 21267try await task.send(.string("{\"type\":\"text.delta\",\"delta\":\"And hello from turn two.\"}"))1268try await task.send(.string("{\"type\":\"text.done\"}"))12691270var turn2Audio = Data()1271while true {1272 let message = try await task.receive()1273 guard case .string(let text) = message,1274 let json = try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any],1275 let type = json["type"] as? String else { continue }12761277 if type == "audio.delta", let delta = json["delta"] as? String,1278 let chunk = Data(base64Encoded: delta) {1279 turn2Audio.append(chunk)1280 } else if type == "audio.done" {1281 print("Turn 2: \(turn2Audio.count) bytes")1282 break1283 } else if type == "error" {1284 print("Error: \(json["message"] ?? "unknown")")1285 break1286 }1287}12881289task.cancel(with: .normalClosure, reason: nil)1290```12911292### Cancellation (Barge-in)12931294Send `text.clear` to cancel the current utterance and start a new one on the same connection — no reconnect needed. This eliminates the WebSocket handshake latency (~600ms for distant clients) on every interruption.12951296**Flow for barge-in:**129712981. Client sends `text.delta` → `text.done`12992. Server starts streaming `audio.delta` chunks13003. User interrupts — client sends `text.clear`13014. Server responds with `audio.clear`13025. Client sends new `text.delta` → `text.done`13036. Server streams fresh `audio.delta` chunks → `audio.done`13041305`text.clear` is safe to send at any time — if no utterance is in progress, the server responds with `audio.clear` immediately. Clear your local audio playback buffer when you receive `audio.clear` to prevent stale audio from playing.13061307```python customLanguage="pythonWithoutSDK"1308import asyncio1309import base641310import json1311import os13121313import websockets # pip install websockets13141315XAI_API_KEY = os.environ["XAI_API_KEY"]13161317async def tts_with_barge_in(language: str = "en", voice: str = "eve", codec: str = "mp3"):1318 uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec={codec}"13191320 async with websockets.connect(1321 uri,1322 additional_headers={"Authorization": f"Bearer {XAI_API_KEY}"},1323 ) as ws:1324 # Start first utterance1325 await ws.send(json.dumps({"type": "text.delta", "delta": "The answer to your question is a long explanation..."}))1326 await ws.send(json.dumps({"type": "text.done"}))13271328 # Wait for audio to start, then cancel1329 event = json.loads(await ws.recv())1330 print(f"Got {event['type']} — cancelling")1331 await ws.send(json.dumps({"type": "text.clear"}))13321333 async for msg in ws:1334 if json.loads(msg)["type"] == "audio.clear":1335 break13361337 # New utterance on the same connection1338 await ws.send(json.dumps({"type": "text.delta", "delta": "Actually, let me start over."}))1339 await ws.send(json.dumps({"type": "text.done"}))13401341 audio = bytearray()1342 async for msg in ws:1343 event = json.loads(msg)1344 if event["type"] == "audio.delta":1345 audio.extend(base64.b64decode(event["delta"]))1346 elif event["type"] == "audio.done":1347 print(f"New utterance: {len(audio):,} bytes")1348 break13491350asyncio.run(tts_with_barge_in())1351```13521353```javascript customLanguage="javascriptWithoutSDK"1354// npm install ws1355import WebSocket from "ws";13561357const apiKey = process.env.XAI_API_KEY;1358const uri = `wss://api.x.ai/v1/tts?language=en&voice=eve&codec=mp3`;13591360const ws = new WebSocket(uri, {1361 headers: { Authorization: `Bearer ${apiKey}` },1362});13631364let phase = "first-utterance";13651366ws.on("open", () => {1367 ws.send(JSON.stringify({ type: "text.delta", delta: "The answer to your question is a long explanation..." }));1368 ws.send(JSON.stringify({ type: "text.done" }));1369});13701371ws.on("message", (data) => {1372 const event = JSON.parse(data);13731374 if (phase === "first-utterance" && event.type === "audio.delta") {1375 console.log("Audio started — cancelling");1376 ws.send(JSON.stringify({ type: "text.clear" }));1377 phase = "waiting-clear";1378 } else if (phase === "waiting-clear" && event.type === "audio.clear") {1379 phase = "second-utterance";1380 ws.send(JSON.stringify({ type: "text.delta", delta: "Actually, let me start over." }));1381 ws.send(JSON.stringify({ type: "text.done" }));1382 } else if (phase === "second-utterance" && event.type === "audio.done") {1383 console.log("New utterance complete");1384 ws.close();1385 }1386});1387```13881389```swift1390import Foundation13911392let apiKey = ProcessInfo.processInfo.environment["XAI_API_KEY"]!1393let url = URL(string: "wss://api.x.ai/v1/tts?language=en&voice=eve&codec=mp3")!1394var request = URLRequest(url: url)1395request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")13961397let task = URLSession.shared.webSocketTask(with: request)1398task.resume()13991400// Start first utterance1401try await task.send(.string("{\"type\":\"text.delta\",\"delta\":\"The answer is a long explanation...\"}"))1402try await task.send(.string("{\"type\":\"text.done\"}"))14031404// Wait for first audio chunk, then cancel1405if case .string(let text) = try await task.receive(),1406 let json = try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any],1407 json["type"] as? String == "audio.delta" {1408 try await task.send(.string("{\"type\":\"text.clear\"}"))1409}14101411// Wait for audio.clear1412while true {1413 guard case .string(let text) = try await task.receive(),1414 let json = try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any] else { continue }1415 if json["type"] as? String == "audio.clear" { break }1416}14171418// New utterance on the same connection1419try await task.send(.string("{\"type\":\"text.delta\",\"delta\":\"Actually, let me start over.\"}"))1420try await task.send(.string("{\"type\":\"text.done\"}"))14211422var audio = Data()1423while true {1424 guard case .string(let text) = try await task.receive(),1425 let json = try? JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any],1426 let type = json["type"] as? String else { continue }1427 if type == "audio.delta", let d = json["delta"] as? String, let c = Data(base64Encoded: d) { audio.append(c) }1428 else if type == "audio.done" { print("New utterance: \(audio.count) bytes"); break }1429}14301431task.cancel(with: .normalClosure, reason: nil)1432```14331434### Limits and Behavior14351436| Property | Value |1437|----------|-------|1438| **Total text length** | No limit — send as many `text.delta` messages as needed |1439| **Delta size** | Individual `text.delta` messages capped at 60,000 characters |1440| **Concurrent sessions** | 50 per team |1441| **Session permit TTL** | 600 seconds |1442| **[`replace`](#map-limits) expansion** | An utterance whose text exceeds 240,000 characters after substitution ends the session |1443| **Moderation** | Runs asynchronously on accumulated text after audio is sent (fail-open) |1444| **Billing** | Recorded per session based on total input characters |14451446## Related14471448* [TTS Playground](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech) - Try voices and speech tags in your browser1449* [Create an API Key](https://console.x.ai/team/default/api-keys?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=api-keys) - Get started with the API1450* [Voice Overview](/developers/model-capabilities/audio/voice) - Overview of all xAI voice capabilities1451* [Speech to Speech API](/developers/model-capabilities/audio/speech-to-speech) - Real-time voice conversations via WebSocket1452* [API Reference](/developers/rest-api-reference/inference/voice#text-to-speech---rest) - Full TTS endpoint specification1453* [List Voices](/developers/rest-api-reference/inference/voice#text-to-speech---list-voices) - Programmatically discover available voices1454