Documentation 2026-08-03 23:00 UTC to 2026-08-06 20:01 UTC

530 530 

531The default limit is 30 custom voices per team. If you need more, contact us to discuss higher limits.531The default limit is 30 custom voices per team. If you need more, contact us to discuss higher limits.

532 532 

533[Request more custom voices](https://x.ai/api/voice/contact-us?category=voice-api)533[Request more custom voices](https://x.ai/contact-sales)

534 534 

535## Error Handling535## Error Handling

536 536 

538|--------|---------|--------|538|--------|---------|--------|

539| `201` | Voice created | Save `voice_id` and start using it. |539| `201` | Voice created | Save `voice_id` and start using it. |

540| `200` | Successful read / update / delete | - |540| `200` | Successful read / update / delete | - |

541| `400` | Bad request | Check: audio under 120 s; label values are within the allowed enums; PATCH does not contain empty strings. Also returned when the team's 30-voice limit is reached — delete an existing voice or [request more](https://x.ai/api/voice/contact-us?category=voice-api). |541| `400` | Bad request | Check: audio under 120 s; label values are within the allowed enums; PATCH does not contain empty strings. Also returned when the team's 30-voice limit is reached — delete an existing voice or [request more](https://x.ai/contact-sales). |

542| `401` | Unauthorized | API key is missing or invalid. |542| `401` | Unauthorized | API key is missing or invalid. |

543| `403` | Custom voices not enabled for this team, or `POST /v1/custom-voices` was called without an Enterprise contract | Create voices in the [console playground](https://console.x.ai/team/default/voice/voice-library?campaign=voice-docs-custom-voices), or [contact sales](https://x.ai/api/voice/contact-us?category=voice-api) to enable the create API. |543| `403` | Custom voices not enabled for this team, or `POST /v1/custom-voices` was called without an Enterprise contract | Create voices in the [console playground](https://console.x.ai/team/default/voice/voice-library?campaign=voice-docs-custom-voices), or [contact sales](https://x.ai/contact-sales) to enable the create API. |

544| `404` | Voice not found | The id does not exist or is owned by another team. |544| `404` | Voice not found | The id does not exist or is owned by another team. |

545| `500` | Server error | Retry with exponential backoff. |545| `500` | Server error | Retry with exponential backoff. |

4 4 

5Generate videos from text prompts with Grok video models. The API supports configurable duration, aspect ratio, and resolution, and the SDK handles asynchronous polling automatically. On `grok-imagine-video-1.5`, text-to-video supports native 1080p.5Generate videos from text prompts with Grok video models. The API supports configurable duration, aspect ratio, and resolution, and the SDK handles asynchronous polling automatically. On `grok-imagine-video-1.5`, text-to-video supports native 1080p.

6 6 

7> [!NOTE]

8>

9> On , text-to-video uses text-to-image then image-to-video under the hood: the model generates a first frame from your prompt, then animates it. You still make a single text-to-video request; the intermediate image is not returned.

10 

7## Quick Start11## Quick Start

8 12 

9Generate a video with a single API call:13Generate a video with a single API call:

230 234 

231> [!WARNING]235> [!WARNING]

232>236>

233> Reference audio is currently only available in the **United States**, for trusted partners. .237> Preset voices are generally available. Voice references with your own audio files are available to trusted partners, on request. .

234 238 

235On `grok-imagine-video-1.5`, [reference-to-video](/developers/model-capabilities/video/reference-to-video#reference-audio) can carry a voice via `reference_audios`. Voices come from the built-in roster and are named by `voice_id`; you cannot upload your own audio clips:239On `grok-imagine-video-1.5`, [reference-to-video](/developers/model-capabilities/video/reference-to-video#reference-audio) can carry a voice via `reference_audios`. Voices come from the built-in roster and are named by `voice_id`; voice references with your own audio files are available to trusted partners [on request](https://x.ai/contact-sales?interest=imagine):

236 240 

237| Property | Description |241| Property | Description |

238|----------|-------------|242|----------|-------------|

141 141 

142> [!WARNING]142> [!WARNING]

143>143>

144> Reference audio is currently only available in the **United States**, for trusted partners. .144> Preset voices are generally available. Voice references with your own audio files are available to trusted partners, on request. .

145 145 

146On `grok-imagine-video-1.5`, give your subject a voice by passing up to **3** preset voices with `reference_audios`. Each entry names a voice by `voice_id`, drawn from the same built-in roster as [Text to Speech](/developers/model-capabilities/audio/text-to-speech#voices), so `{"voice_id": "eve"}` speaks in Eve's voice. Identifiers are case-insensitive; an unknown one returns `400` with the list of available voices. You can hear every voice in the [flagship voices announcement](https://x.ai/news/new-flagship-voices).146On `grok-imagine-video-1.5`, give your subject a voice by passing up to **3** preset voices with `reference_audios`. Each entry names a voice by `voice_id`, drawn from the same built-in roster as [Text to Speech](/developers/model-capabilities/audio/text-to-speech#voices), so `{"voice_id": "eve"}` speaks in Eve's voice. Identifiers are case-insensitive; an unknown one returns `400` with the list of available voices. You can hear every voice in the [flagship voices announcement](https://x.ai/news/new-flagship-voices).

147 147 

148`reference_audios` accepts preset voices only; you cannot upload your own audio clips. Use a voice alongside reference images or on its own, and tag voices in the prompt as `<AUDIO_0>`, `<AUDIO_1>`, and `<AUDIO_2>` (with `<IMAGE_0>`… when you also pass images).148`reference_audios` accepts preset voices; voice references with your own audio files are available to trusted partners [on request](https://x.ai/contact-sales?interest=imagine). Use a voice alongside reference images or on its own, and tag voices in the prompt as `<AUDIO_0>`, `<AUDIO_1>`, and `<AUDIO_2>` (with `<IMAGE_0>`… when you also pass images).

149 149 

150```python customLanguage="pythonRequests"150```python customLanguage="pythonRequests"

151import os151import os

41| grok-4.20-multi-agent-0309 | T0: 9, T1: 12, T2: 18, T3: 31, T4: 56 | T0: 2.5M, T1: 3.7M, T2: 6.2M, T3: 11M, T4: 21M |41| grok-4.20-multi-agent-0309 | T0: 9, T1: 12, T2: 18, T3: 31, T4: 56 | T0: 2.5M, T1: 3.7M, T2: 6.2M, T3: 11M, T4: 21M |

42| grok-imagine-image | 5 | — |42| grok-imagine-image | 5 | — |

43| grok-imagine-image-quality | 5 | — |43| grok-imagine-image-quality | 5 | — |

44| grok-imagine-video | 10 | — |

45| grok-imagine-video-1.5 | 10 | — |44| grok-imagine-video-1.5 | 10 | — |

45| grok-imagine-video | 10 | — |

46 46 

47### What counts toward TPM47### What counts toward TPM

48 48