Documentation 2026-10-13 23:59 UTC to 2026-10-14 23:01 UTC

180* One connection processes turns serially — sending a second `response.create` while one is180* One connection processes turns serially — sending a second `response.create` while one is

181 in-flight will queue, not multiplex.181 in-flight will queue, not multiplex.

182* Need parallel turns? Open multiple connections.182* Need parallel turns? Open multiple connections.

183* A single connection can stay open for up to 25 minutes. After that, the server closes it and183* A single connection can stay open for up to 59 minutes. After that, the server closes it and

184 you'll need to reconnect.184 you'll need to reconnect.

185 185 

186## Reconnecting186## Reconnecting

187 187 

188When the socket drops (network blip, deploy, hitting the 25-minute cap), open a new connection188When the socket drops (network blip, deploy, hitting the 59-minute cap), open a new connection

189and pick whichever recovery path applies:189and pick whichever recovery path applies:

190 190 

1911. If you used `store=true` and still have a valid response ID, just continue with1911. If you used `store=true` and still have a valid response ID, just continue with

217 217 

218### `websocket_connection_limit_reached`218### `websocket_connection_limit_reached`

219 219 

220Sent right before the server closes a connection that has been open for the maximum 25 minutes.220Sent right before the server closes a connection that has been open for the maximum 59 minutes.

221Open a fresh WebSocket and reconnect using one of the patterns above.221Open a fresh WebSocket and reconnect using one of the patterns above.

222 222 

223```json223```json

227 "error": {227 "error": {

228 "type": "invalid_request_error",228 "type": "invalid_request_error",

229 "code": "websocket_connection_limit_reached",229 "code": "websocket_connection_limit_reached",

230 "message": "Responses websocket connection limit reached (25 minutes). Create a new websocket connection to continue."230 "message": "Responses websocket connection limit reached (59 minutes). Create a new websocket connection to continue."

231 }231 }

232}232}

233```233```

133 133 

134| Model | Description |134| Model | Description |

135|-------|-------------|135|-------|-------------|

136| `grok-voice-latest` | Alias for `grok-voice-think-fast-2.0` |136| `grok-voice-latest` | Alias for `grok-voice-3.0` |

137| `grok-voice-think-fast-2.0` | Flagship voice model |137| `grok-voice-3.0` | Flagship voice model |

138| `grok-voice-2.0` | Previous-generation voice model |

139 

140### Upgrading from Grok Voice 2.0

141 

142`grok-voice-latest` points to `grok-voice-3.0`, so sessions that use the alias already run on Grok Voice 3.0. Grok Voice 2.0 is deprecated: if you pin `grok-voice-2.0`, set `model` to `grok-voice-3.0`.

143 

144The API is unchanged: Grok Voice 3.0 uses the same endpoint, session parameters, and events as Grok Voice 2.0, at the same price.

138 145 

139## Session Parameters146## Session Parameters

140 147 

1620 1627 

1621### Step 3 — Model-Specific Best Practices1628### Step 3 — Model-Specific Best Practices

1622 1629 

1623#### `grok-voice-think-fast-2.0` (Recommended)1630#### `grok-voice-3.0` (Recommended)

1624 1631 

1625This is the newest voice model. Use `grok-voice-latest` for new integrations so your app tracks the current recommended model. When migrating:1632This is the newest voice model. Use `grok-voice-latest` for new integrations so your app tracks the current recommended model. When migrating:

1626 1633 

1630 1637 

1631> [!NOTE]1638> [!NOTE]

1632>1639>

1633> `grok-voice-latest` always points to the newest model (currently `grok-voice-think-fast-2.0`). Pin to a versioned model name in production for stability.1640> `grok-voice-latest` always points to the newest model (currently `grok-voice-3.0`). Pin to a versioned model name in production for stability.

1634 1641 

1635## OpenAI Realtime API Compatibility1642## OpenAI Realtime API Compatibility

1636 1643 

2 2 

3# Voice Overview3# Voice Overview

4 4 

5The xAI Voice APIs offer a range of powerful voice capabilities, all powered by Grok, with enterprise-grade reliability and sub-second latency.5The SpaceXSI Voice APIs offer a range of powerful voice capabilities, all powered by Grok, with enterprise-grade reliability and sub-second latency.

6 6 

7## Speech to Speech7## Speech to Speech

8 8 

271 271 

272### Enterprise Compliance & Security272### Enterprise Compliance & Security

273 273 

274The xAI Voice APIs are built for production workloads with strict security and compliance requirements. All audio data is processed in real time and never stored or used for training.274The SpaceXSI Voice APIs are built for production workloads with strict security and compliance requirements. All audio data is processed in real time and never stored or used for training.

275 275 

276* **SOC 2 Type II** — Audited controls for security, availability, and confidentiality276* **SOC 2 Type II** — Audited controls for security, availability, and confidentiality

277 277 

15 -H "Authorization: Bearer $XAI_API_KEY" \15 -H "Authorization: Bearer $XAI_API_KEY" \

16 -H "Content-Type: application/json" \16 -H "Content-Type: application/json" \

17 -d '{17 -d '{

18 "model": "grok-imagine-image-quality",18 "model": "grok-imagine-image-2.0",

19 "prompt": "A serene Japanese garden in winter",19 "prompt": "A serene Japanese garden in winter",

20 "response_format": "url",20 "response_format": "url",

21 "storage_options": {21 "storage_options": {

33 33 

34response = client.image.sample(34response = client.image.sample(

35 prompt="A serene Japanese garden in winter",35 prompt="A serene Japanese garden in winter",

36 model="grok-imagine-image-quality",36 model="grok-imagine-image-2.0",

37 storage_options={"filename": "garden.jpg", "public_url": True},37 storage_options={"filename": "garden.jpg", "public_url": True},

38)38)

39 39 

86 -H "Authorization: Bearer $XAI_API_KEY" \86 -H "Authorization: Bearer $XAI_API_KEY" \

87 -H "Content-Type: application/json" \87 -H "Content-Type: application/json" \

88 -d '{88 -d '{

89 "model": "grok-imagine-image-quality",89 "model": "grok-imagine-image-2.0",

90 "prompt": "A red circle on a white background",90 "prompt": "A red circle on a white background",

91 "response_format": "url",91 "response_format": "url",

92 "storage_options": {"filename": "circle.jpg"}92 "storage_options": {"filename": "circle.jpg"}

96```python customLanguage="pythonXAI"96```python customLanguage="pythonXAI"

97response = client.image.sample(97response = client.image.sample(

98 prompt="A red circle on a white background",98 prompt="A red circle on a white background",

99 model="grok-imagine-image-quality",99 model="grok-imagine-image-2.0",

100 storage_options={"filename": "circle.jpg"}, # store privately, no public URL100 storage_options={"filename": "circle.jpg"}, # store privately, no public URL

101)101)

102 102 

117 -H "Authorization: Bearer $XAI_API_KEY" \117 -H "Authorization: Bearer $XAI_API_KEY" \

118 -H "Content-Type: application/json" \118 -H "Content-Type: application/json" \

119 -d '{119 -d '{

120 "model": "grok-imagine-image-quality",120 "model": "grok-imagine-image-2.0",

121 "prompt": "A futuristic city skyline at night",121 "prompt": "A futuristic city skyline at night",

122 "response_format": "url",122 "response_format": "url",

123 "storage_options": {123 "storage_options": {

131 -H "Authorization: Bearer $XAI_API_KEY" \131 -H "Authorization: Bearer $XAI_API_KEY" \

132 -H "Content-Type: application/json" \132 -H "Content-Type: application/json" \

133 -d '{133 -d '{

134 "model": "grok-imagine-image-quality",134 "model": "grok-imagine-image-2.0",

135 "prompt": "A futuristic city skyline at night",135 "prompt": "A futuristic city skyline at night",

136 "response_format": "url",136 "response_format": "url",

137 "storage_options": {137 "storage_options": {

151# Permanent file, public URL expires in 24h.151# Permanent file, public URL expires in 24h.

152response = client.image.sample(152response = client.image.sample(

153 prompt="A futuristic city skyline at night",153 prompt="A futuristic city skyline at night",

154 model="grok-imagine-image-quality",154 model="grok-imagine-image-2.0",

155 storage_options={"filename": "skyline.jpg", "public_url": {"expires_after": 86400}}, # 24h155 storage_options={"filename": "skyline.jpg", "public_url": {"expires_after": 86400}}, # 24h

156)156)

157print(response.file_output.file_id) # file_...157print(response.file_output.file_id) # file_...

161# File and public URL both expire in 2h (URL inherits the file's expiry).161# File and public URL both expire in 2h (URL inherits the file's expiry).

162response = client.image.sample(162response = client.image.sample(

163 prompt="A futuristic city skyline at night",163 prompt="A futuristic city skyline at night",

164 model="grok-imagine-image-quality",164 model="grok-imagine-image-2.0",

165 storage_options={"filename": "skyline.jpg", "expires_after": 7200, "public_url": True},165 storage_options={"filename": "skyline.jpg", "expires_after": 7200, "public_url": True},

166)166)

167print(response.file_output.file_id) # file_...167print(response.file_output.file_id) # file_...

172# File expires in 24h, public URL expires in 1h (independent, shorter).172# File expires in 24h, public URL expires in 1h (independent, shorter).

173response = client.image.sample(173response = client.image.sample(

174 prompt="A futuristic city skyline at night",174 prompt="A futuristic city skyline at night",

175 model="grok-imagine-image-quality",175 model="grok-imagine-image-2.0",

176 storage_options={176 storage_options={

177 "filename": "skyline.jpg",177 "filename": "skyline.jpg",

178 "expires_after": 86400,178 "expires_after": 86400,

209 -H "Authorization: Bearer $XAI_API_KEY" \209 -H "Authorization: Bearer $XAI_API_KEY" \

210 -H "Content-Type: application/json" \210 -H "Content-Type: application/json" \

211 -d '{211 -d '{

212 "model": "grok-imagine-image-quality",212 "model": "grok-imagine-image-2.0",

213 "prompt": "A cat wearing a hat, four different art styles",213 "prompt": "A cat wearing a hat, four different art styles",

214 "n": 4,214 "n": 4,

215 "response_format": "url",215 "response_format": "url",

225 225 

226responses = client.image.sample_batch(226responses = client.image.sample_batch(

227 prompt="A cat wearing a hat, four different art styles",227 prompt="A cat wearing a hat, four different art styles",

228 model="grok-imagine-image-quality",228 model="grok-imagine-image-2.0",

229 n=4,229 n=4,

230 storage_options={"filename": "cat-styles.jpg", "public_url": True},230 storage_options={"filename": "cat-styles.jpg", "public_url": True},

231)231)

243 -H "Authorization: Bearer $XAI_API_KEY" \243 -H "Authorization: Bearer $XAI_API_KEY" \

244 -H "Content-Type: application/json" \244 -H "Content-Type: application/json" \

245 -d '{245 -d '{

246 "model": "grok-imagine-image-quality",246 "model": "grok-imagine-image-2.0",

247 "prompt": "Add a party hat to the dog",247 "prompt": "Add a party hat to the dog",

248 "image": {248 "image": {

249 "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png"249 "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png"

261 261 

262response = client.image.sample(262response = client.image.sample(

263 prompt="Add a party hat to the dog",263 prompt="Add a party hat to the dog",

264 model="grok-imagine-image-quality",264 model="grok-imagine-image-2.0",

265 image_url="https://docs.x.ai/assets/api-examples/images/style-realistic.png",265 image_url="https://docs.x.ai/assets/api-examples/images/style-realistic.png",

266 storage_options={"filename": "party-dog.png", "public_url": True},266 storage_options={"filename": "party-dog.png", "public_url": True},

267)267)

352 352 

353response = client.image.sample(353response = client.image.sample(

354 prompt="A vintage poster",354 prompt="A vintage poster",

355 model="grok-imagine-image-quality",355 model="grok-imagine-image-2.0",

356 storage_options={"filename": "poster.jpg", "public_url": True},356 storage_options={"filename": "poster.jpg", "public_url": True},

357)357)

358 358 

396 396 

397response = client.image.sample(397response = client.image.sample(

398 prompt="A futuristic city",398 prompt="A futuristic city",

399 model="grok-imagine-image-quality",399 model="grok-imagine-image-2.0",

400 storage_options={"filename": "city.jpg", "public_url": True},400 storage_options={"filename": "city.jpg", "public_url": True},

401)401)

402file_id = response.file_output.file_id402file_id = response.file_output.file_id

41| grok-4.20-0309-non-reasoning | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |41| grok-4.20-0309-non-reasoning | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |

42| grok-build-0.1 | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |42| grok-build-0.1 | T0: 37, T1: 50, T2: 75, T3: 125, T4: 208 | T0: 10M, T1: 15M, T2: 25M, T3: 45M, T4: 85M |

43| 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 |43| 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 |

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

44| grok-imagine-image-2.0 | 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 | — |

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

46| grok-imagine-image-quality | 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 | — |

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

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

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

50 50 

51**Voice & Audio**51**Voice & Audio**

52 52 

53| Model | RPS | Concurrent sessions |53| Model | RPS | Concurrent sessions |

54| --- | --- | --- |54| --- | --- | --- |

55| grok-voice-think-fast-2.0 | — | T0: 10, T1: 20, T2: 50, T3: 100, T4: 200 |55| grok-voice-3.0 | — | T0: 10, T1: 20, T2: 50, T3: 100, T4: 200 |

56| Text to Speech | T0: 50, T1: 50, T2: 100, T3: 250, T4: 500 | T0: 100, T1: 200, T2: 200, T3: 300, T4: 500 |56| Text to Speech | T0: 50, T1: 50, T2: 100, T3: 250, T4: 500 | T0: 100, T1: 200, T2: 200, T3: 300, T4: 500 |

57| Speech to Text | T0: 10, T1: 10, T2: 20, T3: 30, T4: 40 | T0: 100, T1: 200, T2: 200, T3: 300, T4: 500 |57| Speech to Text | T0: 10, T1: 10, T2: 20, T3: 30, T4: 40 | T0: 100, T1: 200, T2: 200, T3: 300, T4: 500 |

58 58 

14 14 

15* `session` (object | null) — Optional initial session configuration to bind to the client secret. This JSON value is stored alongside the secret and applied when the WebSocket connection opens.15* `session` (object | null) — Optional initial session configuration to bind to the client secret. This JSON value is stored alongside the secret and applied when the WebSocket connection opens.

16 16 

17 * `model` ("grok-voice-latest" | "grok-voice-think-fast-2.0") — Model to use for the session. Use grok-voice-latest for the best experience.17 * `model` ("grok-voice-latest" | "grok-voice-3.0" | "grok-voice-2.0") — Model to use for the session. Use grok-voice-latest for the best experience.

18 18 

19 * `reasoning` (object) — Reasoning settings for models that support them.19 * `reasoning` (object) — Reasoning settings for models that support them.

20 20