Documentation 2026-06-15 23:02 UTC to 2026-06-17 15:58 UTC

147| Parameter | Type | Description |147| Parameter | Type | Description |

148|-----------|------|-------------|148|-----------|------|-------------|

149| `instructions` | string | System prompt |149| `instructions` | string | System prompt |

150| `reasoning_effort` | `"high"` | `"none"` | optional | Controls whether the model uses reasoning. Defaults to `"high"`. Supported only with `grok-voice-latest` and `grok-voice-think-fast-1.0`. |

150| `voice` | string | Voice selection: `eve`, `ara`, `rex`, `sal`, `leo`, or a [custom voice ID](/developers/model-capabilities/audio/custom-voices) (see [Available Voices](#available-voices)) |151| `voice` | string | Voice selection: `eve`, `ara`, `rex`, `sal`, `leo`, or a [custom voice ID](/developers/model-capabilities/audio/custom-voices) (see [Available Voices](#available-voices)) |

151| `tools` | array | Tools available to the voice agent. Supports `file_search`, `web_search`, `x_search`, `mcp`, and `function` types. See [Using Tools](#using-tools-with-grok-voice-agent-api). |152| `tools` | array | Tools available to the voice agent. Supports `file_search`, `web_search`, `x_search`, `mcp`, and `function` types. See [Using Tools](#using-tools-with-grok-voice-agent-api). |

152| `turn_detection.type` | string | null | `"server_vad"` for automatic detection, `null` for manual text turns |153| `turn_detection.type` | string | null | `"server_vad"` for automatic detection, `null` for manual text turns |

1449 1450 

1450async def main():1451async def main():

1451 async with client.realtime.connect(1452 async with client.realtime.connect(

1452 model="grok-voice-think-fast-1.0"1453 model="grok-voice-latest"

1453 ) as conn:1454 ) as conn:

1454 await conn.session.update(session={1455 await conn.session.update(session={

1455 "voice": "eve",1456 "voice": "eve",

1475});1476});

1476 1477 

1477// Pass the configured client so the connection uses the xAI base URL and key1478// Pass the configured client so the connection uses the xAI base URL and key

1478const rt = new OpenAIRealtimeWS({ model: "grok-voice-think-fast-1.0" }, client);1479const rt = new OpenAIRealtimeWS({ model: "grok-voice-latest" }, client);

1479 1480 

1480rt.on("session.created", () => {1481rt.on("session.created", () => {

1481 rt.send({1482 rt.send({

1508# headers = {"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"}1509# headers = {"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"}

1509 1510 

1510# After (xAI)1511# After (xAI)

1511url = "wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0"1512url = "wss://api.x.ai/v1/realtime?model=grok-voice-latest"

1512headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}1513headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}

1513 1514 

1514async with websockets.connect(url, additional_headers=headers) as ws:1515async with websockets.connect(url, additional_headers=headers) as ws:

1524// const headers = { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` };1525// const headers = { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` };

1525 1526 

1526// After (xAI)1527// After (xAI)

1527const url = "wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0";1528const url = "wss://api.x.ai/v1/realtime?model=grok-voice-latest";

1528const headers = { Authorization: `Bearer ${process.env.XAI_API_KEY}` };1529const headers = { Authorization: `Bearer ${process.env.XAI_API_KEY}` };

1529 1530 

1530const ws = new WebSocket(url, { headers });1531const ws = new WebSocket(url, { headers });

1540 1541 

1541```python customLanguage="pythonWithoutSDK"1542```python customLanguage="pythonWithoutSDK"

1542# Pass the model in connect()1543# Pass the model in connect()

1543async with client.realtime.connect(model="grok-voice-think-fast-1.0") as conn:1544async with client.realtime.connect(model="grok-voice-latest") as conn:

1544 ...1545 ...

1545```1546```

1546 1547 

1547```javascript customLanguage="javascriptWithoutSDK"1548```javascript customLanguage="javascriptWithoutSDK"

1548// Pass the model in the OpenAIRealtimeWS constructor1549// Pass the model in the OpenAIRealtimeWS constructor

1549const rt = new OpenAIRealtimeWS({ model: "grok-voice-think-fast-1.0" }, client);1550const rt = new OpenAIRealtimeWS({ model: "grok-voice-latest" }, client);

1550```1551```

1551 1552 

1552### Step 3 — Model-Specific Best Practices1553### Step 3 — Model-Specific Best Practices

1553 1554 

1554#### `grok-voice-think-fast-1.0` (Recommended)1555#### `grok-voice-think-fast-1.0` (Recommended)

1555 1556 

1556This is the flagship voice model — more capable and generalizable than GPT realtime models. When migrating:1557This is the flagship voice model. Use `grok-voice-latest` for new integrations so your app tracks the current recommended model. When migrating:

1557 1558 

1558* **Simplify your system prompt.** The model is significantly more capable, so your prompt should be much shorter. Ask Grok to generalize your existing system prompt rather than porting it verbatim.1559* **Simplify your system prompt.** The model is significantly more capable, so your prompt should be much shorter. Ask Grok to generalize your existing system prompt rather than porting it verbatim.

1559* **Remove workaround prompting.** Prompt hacks and edge-case fixes needed for GPT models are unnecessary. Strip out instructions added solely to patch bugs or limitations of the previous model.1560* **Remove workaround prompting.** Prompt hacks and edge-case fixes needed for GPT models are unnecessary. Strip out instructions added solely to patch bugs or limitations of the previous model.

1560* **Leverage stronger reasoning.** The model handles complex multi-step instructions, nuanced tone, and ambiguous queries out of the box.1561* **Reasoning is enabled by default.** The default `reasoning_effort` is `"high"` for complex multi-step instructions, nuanced tone, and ambiguous queries. Set it to `"none"` to disable reasoning.

1561 1562 

1562#### `grok-voice-fast-1.0`1563#### Deprecated model

1563 1564 

1564A drop-in replacement with similar prompting characteristics to GPT realtime models:1565This model remains available for existing integrations, but new applications should use `grok-voice-latest`.

1565 1566 

1566* **Minimal prompt changes required.** Your existing system prompt and instructions can be used as-is with little to no modification.1567* `grok-voice-fast-1.0`: Legacy voice model with similar prompting characteristics to GPT realtime models.

1567* **Same event flow.** All client and server events follow the same patterns — swap the URL and key, and your application should work immediately.1568 

1569The deprecated model follows the same client and server event flow as `grok-voice-latest`, so existing integrations can pin to it while migrating.

1568 1570 

1569> [!NOTE]1571> [!NOTE]

1570>1572>

133 133 

134response = client.video.generate(134response = client.video.generate(

135 prompt="Make the water crash down and slowly pan out the camera",135 prompt="Make the water crash down and slowly pan out the camera",

136 model="grok-imagine-video",136 model="grok-imagine-video-1.5",

137 image_url="https://docs.x.ai/assets/api-examples/video/waterfall-still.png",137 image_url="https://docs.x.ai/assets/api-examples/video/waterfall-still.png",

138 duration=12,138 duration=12,

139)139)

146import { experimental_generateVideo as generateVideo } from "ai";146import { experimental_generateVideo as generateVideo } from "ai";

147 147 

148const result = await generateVideo({148const result = await generateVideo({

149 model: xai.video("grok-imagine-video"),149 model: xai.video("grok-imagine-video-1.5"),

150 prompt: {150 prompt: {

151 image: "https://docs.x.ai/assets/api-examples/video/waterfall-still.png",151 image: "https://docs.x.ai/assets/api-examples/video/waterfall-still.png",

152 text: "Make the water crash down and slowly pan out the camera",152 text: "Make the water crash down and slowly pan out the camera",

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

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

166 -d '{166 -d '{

167 "model": "grok-imagine-video",167 "model": "grok-imagine-video-1.5",

168 "prompt": "Make the water crash down and slowly pan out the camera",168 "prompt": "Make the water crash down and slowly pan out the camera",

169 "image": {"url": "https://docs.x.ai/assets/api-examples/video/waterfall-still.png"},169 "image": {"url": "https://docs.x.ai/assets/api-examples/video/waterfall-still.png"},

170 "duration": 12170 "duration": 12

41| grok-imagine-image-quality | 300 | 0 |41| grok-imagine-image-quality | 300 | 0 |

42| grok-imagine-image | 300 | 0 |42| grok-imagine-image | 300 | 0 |

43| grok-imagine-video | 70 | 0 |43| grok-imagine-video | 70 | 0 |

44| grok-imagine-video-1.5-preview | 60 | 0 |44| grok-imagine-video-1.5 | 60 | 0 |

45 45 

46### What counts toward TPM46### What counts toward TPM

47 47 

10 10 

11* `data` (array\<object>, required) — A list of models with with minimalized information.11* `data` (array\<object>, required) — A list of models with with minimalized information.

12 12 

13 * `aliases` (array\<string>, required) — Alias ID(s) of the model that user can use in a request's model field.

14 

13 * `cached_prompt_text_token_price` (integer | null) — Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously.15 * `cached_prompt_text_token_price` (integer | null) — Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously.

14 16 

15 * `cached_prompt_text_token_price_long_context` (integer | null) — Price of the cached prompt text token for long context requests (USD cents per 100 million tokens).17 * `cached_prompt_text_token_price_long_context` (integer | null) — Price of the cached prompt text token for long context requests (USD cents per 100 million tokens).

18 20 

19 * `completion_text_token_price_long_context` (integer | null) — Price of the completion text token for long context requests (USD cents per 100 million tokens).21 * `completion_text_token_price_long_context` (integer | null) — Price of the completion text token for long context requests (USD cents per 100 million tokens).

20 22 

23 * `context_length` (integer | null) — The maximum context length supported by the model, in tokens.

24 

21 * `created` (integer, required) — Model creation time in Unix timestamp.25 * `created` (integer, required) — Model creation time in Unix timestamp.

22 26 

23 * `id` (string, required) — Model ID. Obtainable from \<https://console.x.ai/team/default/models> or \<https://docs.x.ai/docs/models>.27 * `id` (string, required) — Model ID. Obtainable from \<https://console.x.ai/team/default/models> or \<https://docs.x.ai/docs/models>.

45 "data": [49 "data": [

46 {50 {

47 "id": "latest",51 "id": "latest",

52 "aliases": [],

53 "context_length": 131072,

48 "created": 1776556800,54 "created": 1776556800,

49 "object": "model",55 "object": "model",

50 "owned_by": "xai",56 "owned_by": "xai",

55 },61 },

56 {62 {

57 "id": "grok-420-reasoning",63 "id": "grok-420-reasoning",

64 "aliases": [],

65 "context_length": 256000,

58 "created": 1768003200,66 "created": 1768003200,

59 "object": "model",67 "object": "model",

60 "owned_by": "xai",68 "owned_by": "xai",

68 },76 },

69 {77 {

70 "id": "grok-imagine-image",78 "id": "grok-imagine-image",

79 "aliases": [],

80 "context_length": 1024,

71 "created": 1769472000,81 "created": 1769472000,

72 "object": "model",82 "object": "model",

73 "owned_by": "xai",83 "owned_by": "xai",

90 100 

91### Response Body101### Response Body

92 102 

103* `aliases` (array\<string>, required) — Alias ID(s) of the model that user can use in a request's model field.

104 

93* `cached_prompt_text_token_price` (integer | null) — Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously.105* `cached_prompt_text_token_price` (integer | null) — Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously.

94 106 

95* `cached_prompt_text_token_price_long_context` (integer | null) — Price of the cached prompt text token for long context requests (USD cents per 100 million tokens).107* `cached_prompt_text_token_price_long_context` (integer | null) — Price of the cached prompt text token for long context requests (USD cents per 100 million tokens).

98 110 

99* `completion_text_token_price_long_context` (integer | null) — Price of the completion text token for long context requests (USD cents per 100 million tokens).111* `completion_text_token_price_long_context` (integer | null) — Price of the completion text token for long context requests (USD cents per 100 million tokens).

100 112 

113* `context_length` (integer | null) — The maximum context length supported by the model, in tokens.

114 

101* `created` (integer, required) — Model creation time in Unix timestamp.115* `created` (integer, required) — Model creation time in Unix timestamp.

102 116 

103* `id` (string, required) — Model ID. Obtainable from \<https://console.x.ai/team/default/models> or \<https://docs.x.ai/docs/models>.117* `id` (string, required) — Model ID. Obtainable from \<https://console.x.ai/team/default/models> or \<https://docs.x.ai/docs/models>.

16 16 

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

18 18 

19 * `reasoning_effort` ("high" | "none") — Controls whether the model uses reasoning. Defaults to \`high\`. Supported only with \`grok-voice-latest\` and \`grok-voice-think-fast-1.0\`.

20 

19### Response Body21### Response Body

20 22 

21* `value` (string, required) — The ephemeral token value. Use as a Bearer token in the WebSocket \`Authorization\` header, or in the \`sec-websocket-protocol\` header with prefix \`xai-client-secret.\`.23* `value` (string, required) — The ephemeral token value. Use as a Bearer token in the WebSocket \`Authorization\` header, or in the \`sec-websocket-protocol\` header with prefix \`xai-client-secret.\`.

98 100 

99* `model` (string, optional, default: grok-voice-latest) — Model to use for the session. Use grok-voice-latest for the best experience.101* `model` (string, optional, default: grok-voice-latest) — Model to use for the session. Use grok-voice-latest for the best experience.

100 102 

103* `reasoning_effort` (string, optional, default: high) — Controls whether the model uses reasoning. Defaults to \`high\`. Supported only with grok-voice-latest and grok-voice-think-fast-1.0.

104 

101### Client Messages105### Client Messages

102 106 

103* `session.update` — Update session configuration such as system prompt, voice, audio format, turn detection, and tools.107* `session.update` — Update session configuration such as system prompt, voice, audio format, turn detection, and tools.