Documentation 2026-10-19 23:59 UTC to 2026-10-20 23:01 UTC

107Authenticate your WebSocket connection with either method:107Authenticate your WebSocket connection with either method:

108 108 

109* **[Ephemeral Tokens](/developers/model-capabilities/audio/ephemeral-tokens)** (recommended) — Short-lived tokens for client-side apps (browsers, mobile). Keeps your API key off the client.109* **[Ephemeral Tokens](/developers/model-capabilities/audio/ephemeral-tokens)** (recommended) — Short-lived tokens for client-side apps (browsers, mobile). Keeps your API key off the client.

110* **API Key** — Pass your xAI API key directly in the `Authorization` header. Server-side only.110* **API Key** — Pass your API key directly in the `Authorization` header. Server-side only.

111 111 

112Read more in our [API documentation](/developers/rest-api-reference/inference/voice#realtime).112Read more in our [API documentation](/developers/rest-api-reference/inference/voice#realtime).

113 113 

1377 1377 

1378## Best Practices1378## Best Practices

1379 1379 

1380This section outlines key recommendations for building low-latency, reliable, and natural-feeling voice experiences using the xAI Speech to Speech API.1380This section outlines key recommendations for building low-latency, reliable, and natural-feeling voice experiences using the SpaceXSI Speech to Speech API.

1381 1381 

1382### Minimize perceived latency with parallel initialization1382### Minimize perceived latency with parallel initialization

1383 1383 

1508 1508 

1509#### Using the OpenAI SDK1509#### Using the OpenAI SDK

1510 1510 

1511If you are using the official OpenAI SDK, point the client at the SpaceXSI endpoint and supply your xAI API key:1511If you are using the official OpenAI SDK, point the client at the SpaceXSI endpoint and supply your SpaceXSI API key:

1512 1512 

1513```python customLanguage="pythonWithoutSDK"1513```python customLanguage="pythonWithoutSDK"

1514import asyncio1514import asyncio

1645 1645 

1646### Event Naming Differences1646### Event Naming Differences

1647 1647 

1648The xAI API uses different event names for a few events with different payloads:1648The SpaceXSI API uses different event names for a few events with different payloads:

1649 1649 

1650* OpenAI's `conversation.item.input_audio_transcription.delta` is named `conversation.item.input_audio_transcription.updated` in the xAI API. The `updated` event contains the cumulative transcript (which may include corrections to previous updates), rather than an incremental delta. Only emitted when `audio.input.transcription.model` is set to `"grok-transcribe"`.1650* OpenAI's `conversation.item.input_audio_transcription.delta` is named `conversation.item.input_audio_transcription.updated` in the SpaceXSI API. The `updated` event contains the cumulative transcript (which may include corrections to previous updates), rather than an incremental delta. Only emitted when `audio.input.transcription.model` is set to `"grok-transcribe"`.

1651 1651 

1652### Unsupported Client Events1652### Unsupported Client Events

1653 1653 

43 43 

44### 3. Join the call over WebSocket44### 3. Join the call over WebSocket

45 45 

46Open `wss://api.x.ai/v1/realtime?call_id={call_id}` with your xAI API key. Then send `session.update` to configure the voice agent for this call, followed by `response.create` when the agent should begin speaking.46Open `wss://api.x.ai/v1/realtime?call_id={call_id}` with your API key. Then send `session.update` to configure the voice agent for this call, followed by `response.create` when the agent should begin speaking.

47 47 

48After connecting, the WebSocket behaves like any other Speech to Speech API session. The SIP caller's audio is bridged into the session, and assistant audio is played back to the caller.48After connecting, the WebSocket behaves like any other Speech to Speech API session. The SIP caller's audio is bridged into the session, and assistant audio is played back to the caller.

49 49 

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

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

15 -d '{15 -d '{

16 "text": "Hello! Welcome to the xAI Text to Speech API.",16 "text": "Hello! Welcome to the SpaceXSI Text to Speech API.",

17 "voice_id": "eve",17 "voice_id": "eve",

18 "language": "en"18 "language": "en"

19 }' \19 }' \

31 "Content-Type": "application/json",31 "Content-Type": "application/json",

32 },32 },

33 json={33 json={

34 "text": "Hello! Welcome to the xAI Text to Speech API.",34 "text": "Hello! Welcome to the SpaceXSI Text to Speech API.",

35 "voice_id": "eve",35 "voice_id": "eve",

36 "language": "en",36 "language": "en",

37 },37 },

54 "Content-Type": "application/json",54 "Content-Type": "application/json",

55 },55 },

56 body: JSON.stringify({56 body: JSON.stringify({

57 text: "Hello! Welcome to the xAI Text to Speech API.",57 text: "Hello! Welcome to the SpaceXSI Text to Speech API.",

58 voice_id: "eve",58 voice_id: "eve",

59 language: "en",59 language: "en",

60 }),60 }),

77request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")77request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

78request.setValue("application/json", forHTTPHeaderField: "Content-Type")78request.setValue("application/json", forHTTPHeaderField: "Content-Type")

79request.httpBody = try JSONSerialization.data(withJSONObject: [79request.httpBody = try JSONSerialization.data(withJSONObject: [

80 "text": "Hello! Welcome to the xAI Text to Speech API.",80 "text": "Hello! Welcome to the SpaceXSI Text to Speech API.",

81 "voice_id": "eve",81 "voice_id": "eve",

82 "language": "en",82 "language": "en",

83])83])

26# 1. Generate an image and store it26# 1. Generate an image and store it

27gen = client.image.sample(27gen = client.image.sample(

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

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

30 storage_options={"filename": "city.jpg"}, # store privately, no public URL needed30 storage_options={"filename": "city.jpg"}, # store privately, no public URL needed

31)31)

32city = gen.file_output.file_id32city = gen.file_output.file_id

34# 2. Edit the stored image without re-uploading34# 2. Edit the stored image without re-uploading

35edit = client.image.sample(35edit = client.image.sample(

36 prompt="Add neon signs to the buildings",36 prompt="Add neon signs to the buildings",

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

38 image_file_id=city,38 image_file_id=city,

39 storage_options={"filename": "city-neon.jpg"},39 storage_options={"filename": "city-neon.jpg"},

40)40)

276 276 

277`prompt` is optional in every first & last frame request. Include one to steer motion and camera work between the frames; omit it to let the frames alone drive the clip.277`prompt` is optional in every first & last frame request. Include one to steer motion and camera work between the frames; omit it to let the frames alone drive the clip.

278 278 

279`last_frame` uses the same URL, data-URI, and `file_id` shapes as [image-to-video](/developers/model-capabilities/video/image-to-video). In the xAI Python SDK, pass `last_frame_url` (or `last_frame_file_id` for a Files API upload) alongside `image_url` (or `image_file_id`). The Vercel AI SDK does not expose `last_frame` yet; send it on the REST body.279`last_frame` uses the same URL, data-URI, and `file_id` shapes as [image-to-video](/developers/model-capabilities/video/image-to-video). Set the pins in each SDK like this:

280 

281| Pin | REST | Python SDK | Vercel AI SDK |

282|-----|------|------------|---------------|

283| First frame | `image` | `image_url` or `image_file_id` | `frameImages` entry with `frameType: "first_frame"` |

284| Last frame | `last_frame` | `last_frame_url` or `last_frame_file_id` | `frameImages` entry with `frameType: "last_frame"` |

285 

286The Vercel AI SDK options need `@ai-sdk/xai` 5.0.8 or later.

280 287 

281```python customLanguage="pythonRequests"288```python customLanguage="pythonRequests"

282import os289import os

387| Spacing | Anchors snap to a 1/3-second grid. Two keyframes that round to the same slot are rejected, so keep them at least 1/3 s apart. |394| Spacing | Anchors snap to a 1/3-second grid. Two keyframes that round to the same slot are rejected, so keep them at least 1/3 s apart. |

388| Inputs | Each `image` accepts the same URL, data-URI, and `file_id` shapes as [image-to-video](/developers/model-capabilities/video/image-to-video). |395| Inputs | Each `image` accepts the same URL, data-URI, and `file_id` shapes as [image-to-video](/developers/model-capabilities/video/image-to-video). |

389 396 

390In the xAI Python SDK, `keyframes` is a list of dicts that flatten the REST `image` object: each entry takes `image_url` (or `image_file_id`) and `timestamp`, the REST `timestamp_s` in seconds, as in `{"image_url": "<KEYFRAME_URL_1>", "timestamp": 2.0}`. Pin the endpoints with `image_url` and `last_frame_url`. The Vercel AI SDK does not expose `keyframes` yet; send it on the REST body.397The SDKs name the keyframe fields differently:

398 

399| Field | REST | Python SDK | Vercel AI SDK |

400|-------|------|------------|---------------|

401| List | `keyframes` | `keyframes` | `providerOptions.xai.keyframes` |

402| Image | `image` object | `image_url` or `image_file_id` | `imageUrl` |

403| Time in seconds | `timestamp_s` | `timestamp` | `timestampSeconds` |

404| Endpoints | `image`, `last_frame` | `image_url`, `last_frame_url` | `frameImages` |

405 

406For example, a Python SDK entry is `{"image_url": "<KEYFRAME_URL_1>", "timestamp": 2.0}`. The Vercel AI SDK options need `@ai-sdk/xai` 5.0.8 or later.

391 407 

392### Example: a year that loops408### Example: a year that loops

393 409 

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

45| grok-imagine-image | 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-2.0 | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |46| grok-imagine-image-2.0 | T0: 6, T1: 12, T2: 25, T3: 50, T4: 100 | — |

47| grok-imagine-video | 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 | — |47| grok-imagine-video-1.5 | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |

49| grok-imagine-video-1.5-lite | 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 | — |

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

50 50 

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

52 52 

2 2 

3# Overview3# Overview

4 4 

5The xAI REST API is compatible with the OpenAI REST API. This reference is generated from the OpenAPI specification and organised by resource.5The SpaceXSI REST API is compatible with the OpenAI REST API. This reference is generated from the OpenAPI specification and organised by resource.

6 6 

7## Base URLs and authentication7## Base URLs and authentication

8 8 

9| API | Base URL | Authenticate with |9| API | Base URL | Authenticate with |

10| --- | --- | --- |10| --- | --- | --- |

11| Inference (responses, chat completions, images, videos, voice, files, batches, models) | `https://api.x.ai` | `Authorization: Bearer <xAI API key>` |11| Inference (responses, chat completions, images, videos, voice, files, batches, models) | `https://api.x.ai` | `Authorization: Bearer <API key>` |

12| Collections management | `https://management-api.x.ai` | `Authorization: Bearer <xAI Management API key>` |12| Collections management | `https://management-api.x.ai` | `Authorization: Bearer <Management API key>` |

13| Collections search | `https://api.x.ai` | `Authorization: Bearer <xAI API key>` |13| Collections search | `https://api.x.ai` | `Authorization: Bearer <API key>` |

14| Management (API keys, teams, billing, audit) | `https://management-api.x.ai` | `Authorization: Bearer <xAI Management API key>` |14| Management (API keys, teams, billing, audit) | `https://management-api.x.ai` | `Authorization: Bearer <Management API key>` |

15 15 

16API keys are created on the [API Keys page](https://console.x.ai/team/default/api-keys?utm_source=docs\&utm_medium=referral\&utm_campaign=developers-rest-api-reference-inference\&utm_content=api-keys) of the xAI Console. Management keys are created on the [Management Keys page](https://console.x.ai/team/default/management-keys?utm_source=docs\&utm_medium=referral\&utm_campaign=developers-rest-api-reference-inference\&utm_content=management-keys); see [Using Management API](/developers/management-api-guide).16API keys are created on the [API Keys page](https://console.x.ai/team/default/api-keys?utm_source=docs\&utm_medium=referral\&utm_campaign=developers-rest-api-reference-inference\&utm_content=api-keys) of the SpaceXSI Console. Management keys are created on the [Management Keys page](https://console.x.ai/team/default/management-keys?utm_source=docs\&utm_medium=referral\&utm_campaign=developers-rest-api-reference-inference\&utm_content=management-keys); see [Using Management API](/developers/management-api-guide).

17 17 

18## Inference API18## Inference API

19 19