SPB Git

Repository Public

text-to-speech.md 57.0 KB 1,454 lines markdown

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
Files main
Menu

Theme