Documentation — Spybara

model-capabilities/audio/text-to-speech.md +12 −12

Details

101 101

103|-----------|------|----------|-------------|103|-----------|------|----------|-------------|

730| Keys non-blank | — | `replace keys must not be blank` |730| Keys non-blank | — | `replace keys must not be blank` |

733 733

734The last row bounds the **rewritten** text — watch it when a short key maps to a long value across a large body of text. Your 15,000-character input cap and your billing still count what you sent.734The 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.

735 735

736The 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).736The 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).

737 737

806* **Use natural punctuation.** Commas, periods, and question marks guide pacing and intonation. `"Wait, really?"` sounds more natural than `"Wait really"`.806* **Use natural punctuation.** Commas, periods, and question marks guide pacing and intonation. `"Wait, really?"` sounds more natural than `"Wait really"`.

807* **Add emotional context.** Exclamation marks and question marks influence delivery - `"That's amazing!"` sounds enthusiastic while `"That's amazing."` is matter-of-fact.807* **Add emotional context.** Exclamation marks and question marks influence delivery - `"That's amazing!"` sounds enthusiastic while `"That's amazing."` is matter-of-fact.

808* **Break long content into paragraphs.** Paragraph breaks create natural pauses and help the model maintain consistent quality across longer text.808* **Break long content into paragraphs.** Paragraph breaks create natural pauses and help the model maintain consistent quality across longer text.

809* **Keep unary requests under 15,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.809* **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.

810 810

811### Integrating with AI coding assistants811### Integrating with AI coding assistants

812 812

917|--------|---------|--------|917|--------|---------|--------|

918| `200` | Success | Audio bytes in the response body |918| `200` | Success | Audio bytes in the response body |

919| `400` | Bad request | Check: text is non-empty, under 15,000 chars; codec and sample rate are valid |919| `400` | Bad request | Check: text is non-empty, under 60,000 chars; codec and sample rate are valid |

920| `401` | Unauthorized | API key is missing or invalid |920| `401` | Unauthorized | API key is missing or invalid |

921| `404` | Not found | Unknown `voice_id` — verify via `GET /v1/tts/voices` (built-in) or `GET /v1/custom-voices` (custom) |921| `404` | Not found | Unknown `voice_id` — verify via `GET /v1/tts/voices` (built-in) or `GET /v1/custom-voices` (custom) |

922| `429` | Rate limited | Back off and retry with exponential delay |922| `429` | Rate limited | Back off and retry with exponential delay |

1009 1009

1011|---|---:|---|1011|---|---:|---|

1014| **Concurrent sessions** | — | 50 per team |1014| **Concurrent sessions** | — | 50 per team |

1017 1017

1018For content exceeding 15,000 characters, use the [bidirectional WebSocket endpoint](#streaming-tts-websocket) which has no text length limit.1018For content exceeding 60,000 characters, use the [bidirectional WebSocket endpoint](#streaming-tts-websocket) which has no text length limit.

1019 1019

1020## Streaming TTS (WebSocket)1020## Streaming TTS (WebSocket)

1021 1021

1063 1063

1064| Event | Description |1064| Event | Description |

1065|-------|-------------|1065|-------|-------------|

1067| `text.done` | Signals the end of the current utterance. The server will finish generating audio and send `audio.done`. |1067| `text.done` | Signals the end of the current utterance. The server will finish generating audio and send `audio.done`. |

1068| `text.clear` | Cancel the current utterance. The server stops generating audio, discards any buffered data, and responds with `audio.clear`. |1068| `text.clear` | Cancel the current utterance. The server stops generating audio, discards any buffered data, and responds with `audio.clear`. |

1069| `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. |1069| `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. |

1107 1107

1108Matching runs across `text.delta` boundaries, so a phrase split over two messages still matches.1108Matching runs across `text.delta` boundaries, so a phrase split over two messages still matches.

1109 1109

1110The [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 60,000 characters ends the session, since by then the oversized text has already been accepted.1110The [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.

1111 1111

1112### Multi-Utterance Sessions1112### Multi-Utterance Sessions

1113 1113

1435| Property | Value |1435| Property | Value |

1436|----------|-------|1436|----------|-------|

1439| **Concurrent sessions** | 50 per team |1439| **Concurrent sessions** | 50 per team |

1440| **Session permit TTL** | 600 seconds |1440| **Session permit TTL** | 600 seconds |

1441| **[`replace`](#map-limits) expansion** | An utterance whose text exceeds 60,000 characters after substitution ends the session |1441| **[`replace`](#map-limits) expansion** | An utterance whose text exceeds 240,000 characters after substitution ends the session |

1442| **Moderation** | Runs asynchronously on accumulated text after audio is sent (fail-open) |1442| **Moderation** | Runs asynchronously on accumulated text after audio is sent (fail-open) |

1443| **Billing** | Recorded per session based on total input characters |1443| **Billing** | Recorded per session based on total input characters |

1444 1444

rate-limits.md +3 −3

Details

~~43| grok-imagine-image-2.0 | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |~~

~~44| grok-imagine-image | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |~~

45| grok-imagine-image-quality | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |43| grok-imagine-image-quality | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |

~~46| grok-imagine-video | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |~~44| grok-imagine-image | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |

45| grok-imagine-image-2.0 | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |

47| grok-imagine-video-1.5 | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |46| grok-imagine-video-1.5 | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |

47| grok-imagine-video | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |

48 48

49**Voice & Audio**49**Voice & Audio**

50 50

rest-api-reference/files.md +0 −1

Details

9* [Upload](/developers/rest-api-reference/files/upload)9* [Upload](/developers/rest-api-reference/files/upload)

10* [Manage](/developers/rest-api-reference/files/manage)10* [Manage](/developers/rest-api-reference/files/manage)

11* [Download](/developers/rest-api-reference/files/download)11* [Download](/developers/rest-api-reference/files/download)

~~12* [Public URLs](/developers/rest-api-reference/files/public-urls)~~

rest-api-reference/files/public-urls.md +0 −75 deleted

File Deleted View Diff

~~1#### Files API~~

~~3# Public URLs~~

~~5See the [Public URLs guide](/developers/files/public-urls) for expiry behaviour, idempotency, and end-to-end examples.~~

~~7***~~

~~9## POST /v1/files/\{file\_id}/public-url~~

~~11Create a permanent, unauthenticated public URL for an existing file. The~~

~~12underlying file is unaffected and can still be fetched through the~~

~~13authenticated content endpoint. Use this when you want to share a stored~~

~~14asset (image, video, PDF) outside your API-keyed environment. Public URLs~~

~~15can be revoked at any time via \`POST /v1/files/\{file\_id}/public-url/revoke\`.~~

~~17### Path Parameters~~

~~19* `file_id` (string, required) — The file's \`id\`.~~

~~21### Request Body~~

~~23* `expires_after` (integer | null) — Seconds from now until the public URL expires. Must be between \`3600\` (1~~

~~24 hour) and \`2592000\` (30 days). Omit to inherit the file's expiry (if it~~

~~25 has one) or to make the URL valid indefinitely.~~

~~27### Response Body~~

~~29* `expires_at` (integer | null) — Unix timestamp (seconds) when the public URL expires. Present when~~

~~30 the public URL has an expiry, either from an explicit \`expires\_after\`~~

~~31 in the request or inherited from the file's TTL. Absent when the~~

~~32 public URL is valid indefinitely.~~

~~34* `public_url` (string, required) — The full public URL.~~

~~36\*\*Response example:\*\*~~

~~38```json~~

~~39{~~

~~40 "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png",~~

~~41 "expires_at": 1755600000~~

~~42}~~

~~43```~~

~~45***~~

~~47## POST /v1/files/\{file\_id}/public-url/revoke~~

~~49Revoke the active public URL for a file. The underlying file remains~~

~~50available through the authenticated content endpoint. Revoke is idempotent~~

~~51— calling it on a file without an active public URL returns~~

~~52\`revoked: false\` without an error.~~

~~54### Path Parameters~~

~~56* `file_id` (string, required) — The file's \`id\`.~~

~~58### Response Body~~

~~60* `id` (string, required) — The file ID whose public URL was revoked.~~

~~62* `public_url` (string | null) — The full public URL that was revoked. Only present when \`revoked\` is \`true\`.~~

~~64* `revoked` (boolean, required) — Whether a public URL was actually revoked. \`false\` if the file had no~~

~~65 active public URL (no-op).~~

~~67\*\*Response example:\*\*~~

~~69```json~~

~~70{~~

~~71 "id": "file_a128090d-f0c9-4873-bd84-e499777e7417",~~

~~72 "revoked": true,~~

~~73 "public_url": "https://files-cdn.x.ai/ZsqeMtdcSYWPPHTQdxXDKQ/file_a128090d-f0c9-4873-bd84-e499777e7417.png"~~

~~74}~~

~~75```~~

rest-api-reference/inference/batches.md +1 −1

Details

303 303

304 * `presence_penalty` (number | null) — (Not supported by \`grok-3\` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.304 * `presence_penalty` (number | null) — (Not supported by \`grok-3\` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

305 305

306 * `reasoning_effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.306 * `reasoning_effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.

307 307

308 * `response_format` (object | object | object)308 * `response_format` (object | object | object)

309 309

rest-api-reference/inference/chat-completions.md +1 −1

Details

38 across requests sharing a prompt prefix. Plumbed to \`x-grok-conv-id\`,38 across requests sharing a prompt prefix. Plumbed to \`x-grok-conv-id\`,

39 same as on \`/v1/responses\`.39 same as on \`/v1/responses\`.

40 40

41* `reasoning_effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.41* `reasoning_effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.

42 42

43* `response_format` (object | object | object)43* `response_format` (object | object | object)

44 44

rest-api-reference/inference/responses.md +3 −3

Details

46 46

47* `reasoning` (object)47* `reasoning` (object)

48 48

49 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.49 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.

50 50

51 * `generate_summary` (string | null) — Only included for compatibility.51 * `generate_summary` (string | null) — Only included for compatibility.

52 52

141 141

142* `reasoning` (object)142* `reasoning` (object)

143 143

144 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.144 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.

145 145

146 * `generate_summary` (string | null) — Only included for compatibility.146 * `generate_summary` (string | null) — Only included for compatibility.

147 147

394 394

395* `reasoning` (object)395* `reasoning` (object)

396 396

397 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.397 * `effort` (string | null) — Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.

398 398

399 * `generate_summary` (string | null) — Only included for compatibility.399 * `generate_summary` (string | null) — Only included for compatibility.

400 400

rest-api-reference/inference/voice.md +2 −2

Details

393 393

394### Request Body394### Request Body

395 395

396* `text` (string, required) — The text to convert to speech. Maximum 15,000 characters. Supports inline speech tags for expressive output: \`\[pause]\`, \`\[long-pause]\`, \`\[hum-tune]\`, \`\[laugh]\`, \`\[chuckle]\`, \`\[giggle]\`, \`\[cry]\`, \`\[tsk]\`, \`\[tongue-click]\`, \`\[lip-smack]\`, \`\[breath]\`, \`\[inhale]\`, \`\[exhale]\`, \`\[sigh]\`. Also supports wrapping tags for style control: \`\<soft>\`, \`\<whisper>\`, \`\<loud>\`, \`\<build-intensity>\`, \`\<decrease-intensity>\`, \`\<higher-pitch>\`, \`\<lower-pitch>\`, \`\<slow>\`, \`\<fast>\`, \`\<sing-song>\`, \`\<singing>\`, \`\<emphasis>\`.396* `text` (string, required) — The text to convert to speech. Maximum 60,000 characters. Supports inline speech tags for expressive output: \`\[pause]\`, \`\[long-pause]\`, \`\[hum-tune]\`, \`\[laugh]\`, \`\[chuckle]\`, \`\[giggle]\`, \`\[cry]\`, \`\[tsk]\`, \`\[tongue-click]\`, \`\[lip-smack]\`, \`\[breath]\`, \`\[inhale]\`, \`\[exhale]\`, \`\[sigh]\`. Also supports wrapping tags for style control: \`\<soft>\`, \`\<whisper>\`, \`\<loud>\`, \`\<build-intensity>\`, \`\<decrease-intensity>\`, \`\<higher-pitch>\`, \`\<lower-pitch>\`, \`\<slow>\`, \`\<fast>\`, \`\<sing-song>\`, \`\<singing>\`, \`\<emphasis>\`.

397 397

398* `voice_id` (string) — Voice identifier. Use a built-in voice from \`GET /v1/tts/voices\` (e.g. \`eve\`, \`ara\`) or a custom voice ID. Defaults to \`eve\` when omitted.398* `voice_id` (string) — Voice identifier. Use a built-in voice from \`GET /v1/tts/voices\` (e.g. \`eve\`, \`ara\`) or a custom voice ID. Defaults to \`eve\` when omitted.

399 399

637 637

638### Client Messages638### Client Messages

639 639

640* `text.delta` — Send a chunk of text to be synthesized. Text is processed incrementally — audio generation begins as soon as enough text is buffered. Individual deltas are capped at 15,000 characters.640* `text.delta` — Send a chunk of text to be synthesized. Text is processed incrementally — audio generation begins as soon as enough text is buffered. Individual deltas are capped at 60,000 characters.

641 641

642* `text.done` — Signal that all text for this utterance has been sent. The server will finish generating audio and send \`audio.done\`. After receiving \`audio.done\`, you can start a new utterance with another \`text.delta\`.642* `text.done` — Signal that all text for this utterance has been sent. The server will finish generating audio and send \`audio.done\`. After receiving \`audio.done\`, you can start a new utterance with another \`text.delta\`.

643 643

Documentation 2026-09-15 17:00 UTC to 2026-09-16 19:01 UTC