153 -H "Authorization: Bearer $XAI_API_KEY"153 -H "Authorization: Bearer $XAI_API_KEY"
154```154```
155 155
156156A successful response confirms both your certificate and API key are working. If you see `403 Forbidden`, check that your certificate is signed by the CA you provided to xAI.A successful response confirms both your certificate and API key are working. If you see `403 Forbidden`, check that your certificate is signed by the CA you provided to SpaceXAI.
2 2
3# Docs MCP Server3# Docs MCP Server
4 4
55xAI hosts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants and agents direct access to the xAI documentation. Instead of copy-pasting docs into a prompt, you can point any MCP-compatible client at the server and let it pull the information it needs.SpaceXAI hosts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants and agents direct access to the SpaceXAI documentation. Instead of copy-pasting docs into a prompt, you can point any MCP-compatible client at the server and let it pull the information it needs.
6 6
7You can use this with all popular IDEs/Editors of your choice.7You can use this with all popular IDEs/Editors of your choice.
8 8
727| `created_at` | integer | Upload time as a Unix timestamp (seconds). |727| `created_at` | integer | Upload time as a Unix timestamp (seconds). |
728| `expires_at` | integer or null | Unix timestamp at which the file will be deleted. `null` for permanent files; set when the file was uploaded with `expires_after`. |728| `expires_at` | integer or null | Unix timestamp at which the file will be deleted. `null` for permanent files; set when the file was uploaded with `expires_after`. |
729| `object` | string | Always `"file"`. Returned for OpenAI compatibility. |729| `object` | string | Always `"file"`. Returned for OpenAI compatibility. |
730730| `purpose` | string | Echoes the `purpose` value sent at upload time. xAI does not enforce or interpret this field; it is stored for OpenAI SDK compatibility. Setting `"assistants"` is the conventional choice. || `purpose` | string | Echoes the `purpose` value sent at upload time. SpaceXAI does not enforce or interpret this field; it is stored for OpenAI SDK compatibility. Setting `"assistants"` is the conventional choice. |
731 731
732## Limitations and Considerations732## Limitations and Considerations
733 733
2 2
3# Public URLs3# Public URLs
4 4
55Every file you upload through the [Files API](/developers/files/managing-files) lives in private storage by default — fetching it requires your API key. **Public URLs** turn a stored file into a permanent, shareable link on the xAI CDN that anyone can open — no API key required.Every file you upload through the [Files API](/developers/files/managing-files) lives in private storage by default — fetching it requires your API key. **Public URLs** turn a stored file into a permanent, shareable link on the SpaceXAI CDN that anyone can open — no API key required.
6 6
7You stay in control after creation:7You stay in control after creation:
8 8
6 6
7## How It Works7## How It Works
8 8
991. Your **server** requests an ephemeral token from xAI using your API key1. Your **server** requests an ephemeral token from SpaceXAI using your API key
102. Your server passes the ephemeral token to the **client**102. Your server passes the ephemeral token to the **client**
113. The **client** uses the ephemeral token to authenticate the WebSocket connection113. The **client** uses the ephemeral token to authenticate the WebSocket connection
124. The token expires automatically after the configured duration124. The token expires automatically after the configured duration
17 17
18## Creating Ephemeral Tokens18## Creating Ephemeral Tokens
19 19
2020You need to set up a server endpoint to fetch the ephemeral token from xAI. The ephemeral token gives the holder scoped access to resources.You need to set up a server endpoint to fetch the ephemeral token from SpaceXAI. The ephemeral token gives the holder scoped access to resources.
21 21
22**Endpoint:** `POST https://api.x.ai/v1/realtime/client_secrets`22**Endpoint:** `POST https://api.x.ai/v1/realtime/client_secrets`
23 23
756 756
757### Remote MCP Tools757### Remote MCP Tools
758 758
759759Use the `mcp` tool type to connect your voice agent to external [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers. This lets you extend your voice agent with third-party or custom tools without implementing them as client-side functions — xAI manages the MCP server connection and tool execution on your behalf.Use the `mcp` tool type to connect your voice agent to external [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers. This lets you extend your voice agent with third-party or custom tools without implementing them as client-side functions — SpaceXAI manages the MCP server connection and tool execution on your behalf.
760 760
761```pythonWithoutSDK761```pythonWithoutSDK
762session_config = {762session_config = {
899 899
900> [!NOTE]900> [!NOTE]
901>901>
902902> MCP tools are server-side tools — xAI handles the connection and execution automatically. Unlike custom function tools, you don't need to handle tool call responses in your client code. For more details on MCP tool configuration, see the [Remote MCP Tools](/developers/tools/remote-mcp) guide.> MCP tools are server-side tools — SpaceXAI handles the connection and execution automatically. Unlike custom function tools, you don't need to handle tool call responses in your client code. For more details on MCP tool configuration, see the [Remote MCP Tools](/developers/tools/remote-mcp) guide.
903 903
904### Custom Function Tools904### Custom Function Tools
905 905
1051 1051
1052> [!NOTE]1052> [!NOTE]
1053>1053>
10541054> Server-side tools (web search, X search, collections, and MCP) are executed automatically by xAI — you don't need to handle their responses. Only custom function tools require client-side handling. For more details, see [Collections](/developers/rest-api-reference/collections), [Web Search](/developers/tools/web-search), [X Search](/developers/tools/x-search), and [Remote MCP Tools](/developers/tools/remote-mcp).> Server-side tools (web search, X search, collections, and MCP) are executed automatically by SpaceXAI — you don't need to handle their responses. Only custom function tools require client-side handling. For more details, see [Collections](/developers/rest-api-reference/collections), [Web Search](/developers/tools/web-search), [X Search](/developers/tools/x-search), and [Remote MCP Tools](/developers/tools/remote-mcp).
1055 1055
1056### Handling Function Call Responses1056### Handling Function Call Responses
1057 1057
1279 1279
1280> [!NOTE]1280> [!NOTE]
1281>1281>
12821282> `force_message` is an xAI extension. It is not part of the OpenAI Realtime API.> `force_message` is an SpaceXAI extension. It is not part of the OpenAI Realtime API.
1283 1283
1284## Per-Response Instructions1284## Per-Response Instructions
1285 1285
1504 1504
1505#### Using the OpenAI SDK1505#### Using the OpenAI SDK
1506 1506
15071507If you are using the official OpenAI SDK, point the client at the xAI endpoint and supply your xAI API key:If you are using the official OpenAI SDK, point the client at the SpaceXAI endpoint and supply your xAI API key:
1508 1508
1509```python customLanguage="pythonWithoutSDK"1509```python customLanguage="pythonWithoutSDK"
1510import asyncio1510import asyncio
1637 1637
1638## OpenAI Realtime API Compatibility1638## OpenAI Realtime API Compatibility
1639 1639
16401640The Grok Speech to Speech API is compatible with the [OpenAI Realtime API](https://developers.openai.com/api/docs/guides/realtime-conversations). Most OpenAI client libraries and SDKs work with the xAI endpoint by changing the base URL to `wss://api.x.ai/v1/realtime`. This section documents event naming differences and unsupported events.The Grok Speech to Speech API is compatible with the [OpenAI Realtime API](https://developers.openai.com/api/docs/guides/realtime-conversations). Most OpenAI client libraries and SDKs work with the SpaceXAI endpoint by changing the base URL to `wss://api.x.ai/v1/realtime`. This section documents event naming differences and unsupported events.
1641 1641
1642### Event Naming Differences1642### Event Naming Differences
1643 1643
1665| `output_audio_buffer.cleared` | WebRTC/SIP only. |1665| `output_audio_buffer.cleared` | WebRTC/SIP only. |
1666| `rate_limits.updated` | Not emitted. |1666| `rate_limits.updated` | Not emitted. |
1667 1667
16681668### xAI Extensions### SpaceXAI Extensions
1669 1669
16701670These events and features are xAI-specific and not part of the OpenAI Realtime API:These events and features are SpaceXAI-specific and not part of the OpenAI Realtime API:
1671 1671
1672| Event / Feature | Description |1672| Event / Feature | Description |
1673|---|---|1673|---|---|
6 6
7### 1. Register the phone number7### 1. Register the phone number
8 8
99Create a Direct SIP phone number and include the webhook details that should receive incoming-call events. Use `origin: "byo_trunk"` for a customer-owned number. Provisioning xAI phone numbers via API is not supported. xAI returns the webhook signing secret in the response.Create a Direct SIP phone number and include the webhook details that should receive incoming-call events. Use `origin: "byo_trunk"` for a customer-owned number. Provisioning SpaceXAI phone numbers via API is not supported. SpaceXAI returns the webhook signing secret in the response.
10 10
11Choose one SIP authentication method.11Choose one SIP authentication method.
12 12
1313The response includes a signing secret after you register the phone number. Store it securely; xAI returns it only once.The response includes a signing secret after you register the phone number. Store it securely; SpaceXAI returns it only once.
14 14
15Configure your carrier or PBX to route calls to:15Configure your carrier or PBX to route calls to:
16 16
17 17
18 18
1919If you provide `allowed_addresses`, make sure the list contains your provider's SIP signaling CIDR ranges. If you provide SIP digest credentials, configure your carrier with the same username and password; xAI never returns the password after creation.If you provide `allowed_addresses`, make sure the list contains your provider's SIP signaling CIDR ranges. If you provide SIP digest credentials, configure your carrier with the same username and password; SpaceXAI never returns the password after creation.
20 20
21### 2. Handle the incoming-call webhook21### 2. Handle the incoming-call webhook
22 22
2323When a caller dials the number, xAI sends a signed `realtime.call.incoming` webhook to the webhook URL. Verify the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers using the signing secret returned after you register the phone number, then read `data.call_id` from the payload.When a caller dials the number, SpaceXAI sends a signed `realtime.call.incoming` webhook to the webhook URL. Verify the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers using the signing secret returned after you register the phone number, then read `data.call_id` from the payload.
24 24
25The webhook has this shape:25The webhook has this shape:
26 26
101});101});
102```102```
103 103
104## Remove a phone number
105
106Delete the registration when SpaceXAI should stop answering the number. `phone_number_id` is in the create response. To find it later, list the team's numbers and match `phone_number`:
107
108```bash customLanguage="bash"
109curl "https://api.x.ai/v2/phone-numbers" \
110 -H "Authorization: Bearer $XAI_API_KEY"
111```
112
113```bash customLanguage="bash"
114curl -X DELETE "https://api.x.ai/v2/phone-numbers/phone_abc123" \
115 -H "Authorization: Bearer $XAI_API_KEY"
116```
117
118A successful delete returns `204` with an empty body. SpaceXAI deletes that number's inbound SIP trunk and dispatch rule. The webhook record stays, and the phone number stays in your carrier account. A SpaceXAI-provisioned number is not deleted; the API returns `403`. See [Delete phone number](/developers/rest-api-reference/inference/voice#delete-phone-number).
119
104## Call control120## Call control
105 121
106Use `refer` to transfer the caller to another PSTN or SIP destination. The request blocks until the transfer resolves; the HTTP status reports whether the destination answered. See [FAQ](#faq) for status codes, failed-transfer session behavior, and conversation resumption.122Use `refer` to transfer the caller to another PSTN or SIP destination. The request blocks until the transfer resolves; the HTTP status reports whether the destination answered. See [FAQ](#faq) for status codes, failed-transfer session behavior, and conversation resumption.
149 165
150## Telephony providers166## Telephony providers
151 167
152168In every provider, the destination is the xAI SIP URI for your registered number:In every provider, the destination is the SpaceXAI SIP URI for your registered number:
153 169
154 170
155 171
211 227
212### Does the session stay usable if a transfer fails?228### Does the session stay usable if a transfer fails?
213 229
214230Yes. While the REFER is pending, the WebSocket stays open and the caller hears dialtone. After a `502`, that same realtime session stays connected. The failed transfer is a no-op on the xAI side: the caller remains on the call, and the agent can keep talking.Yes. While the REFER is pending, the WebSocket stays open and the caller hears dialtone. After a `502`, that same realtime session stays connected. The failed transfer is a no-op on the SpaceXAI side: the caller remains on the call, and the agent can keep talking.
215 231
216This path does not automatically start a new session or inject a failure-reason prompt. If the agent should tell the caller why the transfer failed, read the `refer` HTTP response and continue on this session, or resume later as below.232This path does not automatically start a new session or inject a failure-reason prompt. If the agent should tell the caller why the transfer failed, read the `refer` HTTP response and continue on this session, or resume later as below.
217 233
473 473
474## Related474## Related
475 475
476476* [Voice Overview](/developers/model-capabilities/audio/voice) — Overview of all xAI voice capabilities* [Voice Overview](/developers/model-capabilities/audio/voice) — Overview of all SpaceXAI voice capabilities
477* [Text to Speech](/developers/model-capabilities/audio/text-to-speech) — Convert text to speech477* [Text to Speech](/developers/model-capabilities/audio/text-to-speech) — Convert text to speech
478* [API Reference — Speech to text](/developers/rest-api-reference/inference/voice#speech-to-text---rest) — Full REST endpoint specification478* [API Reference — Speech to text](/developers/rest-api-reference/inference/voice#speech-to-text---rest) — Full REST endpoint specification
479* [API Reference — Streaming](/developers/rest-api-reference/inference/voice#speech-to-text---streaming) — WebSocket streaming specification479* [API Reference — Streaming](/developers/rest-api-reference/inference/voice#speech-to-text---streaming) — WebSocket streaming specification
1446 1446
1447* [TTS Playground](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech) - Try voices and speech tags in your browser1447* [TTS Playground](https://console.x.ai/team/default/voice/text-to-speech?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=text-to-speech) - Try voices and speech tags in your browser
1448* [Create an API Key](https://console.x.ai/team/default/api-keys?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=api-keys) - Get started with the API1448* [Create an API Key](https://console.x.ai/team/default/api-keys?campaign=voice-docs-tts\&utm_source=docs\&utm_medium=referral\&utm_campaign=developers-model-capabilities-audio-text-to-speech\&utm_content=api-keys) - Get started with the API
14491449* [Voice Overview](/developers/model-capabilities/audio/voice) - Overview of all xAI voice capabilities* [Voice Overview](/developers/model-capabilities/audio/voice) - Overview of all SpaceXAI voice capabilities
1450* [Speech to Speech API](/developers/model-capabilities/audio/speech-to-speech) - Real-time voice conversations via WebSocket1450* [Speech to Speech API](/developers/model-capabilities/audio/speech-to-speech) - Real-time voice conversations via WebSocket
1451* [API Reference](/developers/rest-api-reference/inference/voice#text-to-speech---rest) - Full TTS endpoint specification1451* [API Reference](/developers/rest-api-reference/inference/voice#text-to-speech---rest) - Full TTS endpoint specification
1452* [List Voices](/developers/rest-api-reference/inference/voice#text-to-speech---list-voices) - Programmatically discover available voices1452* [List Voices](/developers/rest-api-reference/inference/voice#text-to-speech---list-voices) - Programmatically discover available voices
2 2
3# Comparison with Chat Completions API3# Comparison with Chat Completions API
4 4
55The Responses API is the recommended way to interact with xAI models. Here's how it compares to the legacy Chat Completions API:The Responses API is the recommended way to interact with SpaceXAI models. Here's how it compares to the legacy Chat Completions API:
6 6
7| Feature | Responses API | Chat Completions API (Deprecated) |7| Feature | Responses API | Chat Completions API (Deprecated) |
8|---------|---------------|-----------------------------------|8|---------|---------------|-----------------------------------|
3# Generate Text3# Generate Text
4 4
5The Responses API is the preferred way of interacting with our models via API. It allows optional **stateful interactions** with our models,5The Responses API is the preferred way of interacting with our models via API. It allows optional **stateful interactions** with our models,
66where **previous input prompts, reasoning content, and model responses are saved and stored on xAI's servers**. You can continue the interaction by appending newwhere **previous input prompts, reasoning content, and model responses are saved and stored on SpaceXAI's servers**. You can continue the interaction by appending new
7prompt messages instead of resending the full conversation. This behavior is on by default. If you would like to store your request/response locally, please see [Disable storing previous request/response on server](#disable-storing-previous-requestresponse-on-server).7prompt messages instead of resending the full conversation. This behavior is on by default. If you would like to store your request/response locally, please see [Disable storing previous request/response on server](#disable-storing-previous-requestresponse-on-server).
8 8
9**The responses will be stored for 30 days, after which they will be removed. This means you can use the response ID to retrieve or continue a conversation within 30 days of sending the request.**9**The responses will be stored for 30 days, after which they will be removed. This means you can use the response ID to retrieve or continue a conversation within 30 days of sending the request.**
149 149
150### Built-in Tools Support150### Built-in Tools Support
151 151
152152xAI provides a set of built-in tools you can enable in the request to help with the most common use cases, e.g., `web_search`, `x_search`, `code_execution`, `collections_search`. Check out [this doc](/developers/tools/overview) for more information.SpaceXAI provides a set of built-in tools you can enable in the request to help with the most common use cases, e.g., `web_search`, `x_search`, `code_execution`, `collections_search`. Check out [this doc](/developers/tools/overview) for more information.
153 153
154Once you enable those tools in the request, the server will perform the agent loop to invoke those tools on the server side based on your query until the final answer is generated.154Once you enable those tools in the request, the server will perform the agent loop to invoke those tools on the server side based on your query until the final answer is generated.
155 155
15> [!NOTE]15> [!NOTE]
16> Always returned for grok-4.716> Always returned for grok-4.7
17>17>
1818> On the Responses API, `grok-4.7` returns `reasoning.encrypted_content` on every response, whether or not `include` lists it, together with the encrypted outputs of any server-side tools. Reasoning items in the output carry an `encrypted_content` field; pass them back unchanged in the next request's `input` so the model keeps its reasoning across turns even when you manage conversation history yourself. Unlike an explicit `include`, this default does not stop xAI from storing the thinking trace server-side for rehydration, so clients that ignore the field keep working as before; whether the response itself is stored for `previous_response_id` is governed by `store`, not by this setting. Chat Completions is unaffected; it has no field for the ciphertext.> On the Responses API, `grok-4.7` returns `reasoning.encrypted_content` on every response, whether or not `include` lists it, together with the encrypted outputs of any server-side tools. Reasoning items in the output carry an `encrypted_content` field; pass them back unchanged in the next request's `input` so the model keeps its reasoning across turns even when you manage conversation history yourself. Unlike an explicit `include`, this default does not stop SpaceXAI from storing the thinking trace server-side for rehydration, so clients that ignore the field keep working as before; whether the response itself is stored for `previous_response_id` is governed by `store`, not by this setting. Chat Completions is unaffected; it has no field for the ciphertext.
19 19
20> [!TIP]20> [!TIP]
21>21>
15 15
16The primary and most flexible method is to use the `response_format` parameter. By setting `response_format.type` to `"json_schema"` and providing your schema under `response_format.json_schema`, you can define exactly what structured output the model should return. The parameter also accepts `"json_object"` for any well-formed JSON when you don't need a specific structure, or `"text"` (the default) for free-form text.16The primary and most flexible method is to use the `response_format` parameter. By setting `response_format.type` to `"json_schema"` and providing your schema under `response_format.json_schema`, you can define exactly what structured output the model should return. The parameter also accepts `"json_object"` for any well-formed JSON when you don't need a specific structure, or `"text"` (the default) for free-form text.
17 17
1818The second way is through tool calling. When you define tools, xAI models will always generate tool call arguments that strictly conform to the tool’s input JSON Schema (the `strict` flag is implicitly always `true`).The second way is through tool calling. When you define tools, SpaceXAI models will always generate tool call arguments that strictly conform to the tool’s input JSON Schema (the `strict` flag is implicitly always `true`).
19 19
20> [!NOTE]20> [!NOTE]
21>21>
127done127done
128```128```
129 129
130130Video editing uses the `/v1/videos/edits` endpoint and `client.video.generate(video_url=...)` in the Python SDK. In the AI SDK, set `providerOptions.xai.mode` to `"edit-video"` or `"extend-video"` and pass `providerOptions.xai.videoUrl`. The same asynchronous polling pattern applies to both flows, and the AI SDK returns the xAI-hosted output URL in `providerMetadata.xai.videoUrl`.Video editing uses the `/v1/videos/edits` endpoint and `client.video.generate(video_url=...)` in the Python SDK. In the AI SDK, set `providerOptions.xai.mode` to `"edit-video"` or `"extend-video"` and pass `providerOptions.xai.videoUrl`. The same asynchronous polling pattern applies to both flows, and the AI SDK returns the SpaceXAI-hosted output URL in `providerMetadata.xai.videoUrl`.
131 131
132## Related132## Related
133 133
193}193}
194```194```
195 195
196196Videos are returned as temporary URLs. Access the xAI-hosted URL directly when you need it, or download/process it promptly if you need to keep a copy.Videos are returned as temporary URLs. Access the SpaceXAI-hosted URL directly when you need it, or download/process it promptly if you need to keep a copy.
197 197
198## Configuration198## Configuration
199 199
666| `permission_denied` | The API key or team does not have permission for the requested video operation. | Confirm the API key belongs to the right team and that the team has access to the requested capability. |666| `permission_denied` | The API key or team does not have permission for the requested video operation. | Confirm the API key belongs to the right team and that the team has access to the requested capability. |
667| `failed_precondition` | The requested operation is not available for the selected model or settings, such as video editing, video extension, or a requested resolution that the model cannot process. | Change the model, mode, resolution, or other request settings. |667| `failed_precondition` | The requested operation is not available for the selected model or settings, such as video editing, video extension, or a requested resolution that the model cannot process. | Change the model, mode, resolution, or other request settings. |
668| `service_unavailable` | Video generation is temporarily overloaded. | Retry the request later. |668| `service_unavailable` | Video generation is temporarily overloaded. | Retry the request later. |
669669| `internal_error` | The service could not complete the generation because of an internal failure. | Retry the request. If the error persists, contact xAI support with the `request_id`. || `internal_error` | The service could not complete the generation because of an internal failure. | Retry the request. If the error persists, contact SpaceXAI support with the `request_id`. |
670 670
671Authentication errors, missing models, and rate limits are returned synchronously as standard API errors before a video job is created, so they do not appear in the `error.code` field of a failed video result.671Authentication errors, missing models, and rate limits are returned synchronously as standard API errors before a video job is created, so they do not appear in the `error.code` field of a failed video result.
672 672
694 694
695## Response Details695## Response Details
696 696
697697The SDK response includes the generated video and provider-specific metadata. In the AI SDK, the xAI-hosted output URL is available at `providerMetadata.xai.videoUrl`.The SDK response includes the generated video and provider-specific metadata. In the AI SDK, the SpaceXAI-hosted output URL is available at `providerMetadata.xai.videoUrl`.
698 698
699```python customLanguage="pythonXAI"699```python customLanguage="pythonXAI"
700if response.respect_moderation:700if response.respect_moderation:
10 10
11> [!WARNING]11> [!WARNING]
12 12
1313Refer to reference images in the prompt by their position in the list, starting at `<IMAGE_0>` for the first image, then `<IMAGE_1>`, and so on.Refer to reference images in the prompt by their position in the list, starting at `<IMAGE_0>` for the first image, then `<IMAGE_1>`, and so on. If you also set `image` to pin the first frame, it takes `<IMAGE_0>` and your reference images start at `<IMAGE_1>`.
14 14
15```python customLanguage="pythonXAI"15```python customLanguage="pythonXAI"
16import os16import os
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 | 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-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 | — |
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 | — |47| grok-imagine-video-1.5 | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |
48| grok-imagine-video | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |48| grok-imagine-video | T0: 10, T1: 20, T2: 39, T3: 79, T4: 158 | — |
49 49
193 193
194***194***
195 195
196## GET /v2/phone-numbers
197
198List phone numbers for the authenticated team.
199
200### Query Parameters
201
202* `limit` (integer) — Page size. Defaults to 20. Values above 100 are clamped to 100.
203
204* `pagination_token` (string) — \`phone\_number\_id\` of the last number on the previous page. Omit for the first page.
205
206* `agent_id` (string) — When set, only numbers routed to this agent are returned.
207
208### Response Body
209
210* `phone_numbers` (array\<object>)
211
212 * `phone_number_id` (string)
213
214 * `team_id` (string)
215
216 * `phone_number` (string) — Phone number in E.164 format.
217
218 * `name` (string)
219
220 * `agent_id` (string) — Agent this number routes to.
221
222 * `webhook_id` (string) — Webhook endpoint this number dispatches \`realtime.call.incoming\` events to.
223
224 * `origin` ("xai\_provisioned" | "byo\_trunk")
225
226 * `sip_host` (string) — SIP host your carrier or PBX should route calls to.
227
228 * `inbound_trunk_id` (string) — Read-only SIP trunk identifier.
229
230 * `sip_auth` (object)
231
232 * `auth_username` (string) — SIP digest username. Present only when digest auth is configured.
233
234 * `allowed_addresses` (array\<string>) — Source CIDR ranges permitted to send INVITEs.
235
236 * `created_at` (string)
237
238 * `updated_at` (string)
239
240 * `agent_name` (string)
241
242* `pagination_token` (string) — Present when another page exists. Pass it back as the pagination\_token query parameter.
243
244\*\*Response example:\*\*
245
246```json
247{
248 "phone_numbers": [
249 {
250 "phone_number_id": "phone_abc123",
251 "team_id": "00000000-0000-0000-0000-000000000000",
252 "phone_number": "+18005550199",
253 "name": "Support SIP trunk",
254 "webhook_id": "webhook_abc123",
255 "origin": "byo_trunk",
256 "sip_host": "sip.voice.x.ai",
257 "created_at": "2026-06-19T00:00:00Z",
258 "updated_at": "2026-06-19T00:00:00Z"
259 }
260 ]
261}
262```
263
264***
265
266## DELETE /v2/phone-numbers/\{phone\_number\_id}
267
268Remove a Direct SIP or Twilio-imported phone number.
269
270### Path Parameters
271
272* `phone_number_id` (string, required) — ID of the phone number to remove. Returned as \`phone\_number.phone\_number\_id\` on create, and as \`phone\_numbers\[].phone\_number\_id\` from \`GET /v2/phone-numbers\`.
273
274***
275
196## Realtime276## Realtime
197 277
198WebSocket endpoint: `wss://api.x.ai/v1/realtime`278WebSocket endpoint: `wss://api.x.ai/v1/realtime`
19 19
20### How It Works20### How It Works
21 21
2222The key difference when mixing server-side and client-side tools is that **server-side tools are executed automatically by xAI**, while **client-side tools require developer intervention**:The key difference when mixing server-side and client-side tools is that **server-side tools are executed automatically by SpaceXAI**, while **client-side tools require developer intervention**:
23 23
241. Define your client-side tools using [standard function calling patterns](/developers/tools/function-calling)241. Define your client-side tools using [standard function calling patterns](/developers/tools/function-calling)
252. Include both server-side and client-side tools in your request252. Include both server-side and client-side tools in your request
26263. **xAI automatically executes any server-side tools** the model decides to use (web search, code execution, etc.)3. **SpaceXAI automatically executes any server-side tools** the model decides to use (web search, code execution, etc.)
27274. **When the model calls client-side tools, execution pauses** - xAI returns the tool calls to you instead of executing them4. **When the model calls client-side tools, execution pauses** - SpaceXAI returns the tool calls to you instead of executing them
285. **Detect and execute client-side tool calls yourself**, then append the results back to continue the conversation285. **Detect and execute client-side tool calls yourself**, then append the results back to continue the conversation
296. **Repeat this process** until the model generates a final response with no additional client-side tool calls296. **Repeat this process** until the model generates a final response with no additional client-side tool calls
30 30
364 364
365### Store the Conversation History Remotely365### Store the Conversation History Remotely
366 366
367367You can choose to store the conversation history remotely on the xAI server, and every time you want to continue the conversation, you can pick up from the last response where you want to resume from.You can choose to store the conversation history remotely on the SpaceXAI server, and every time you want to continue the conversation, you can pick up from the last response where you want to resume from.
368 368
369There are only 2 extra steps:369There are only 2 extra steps:
370 370
3713711. Add the parameter `store_messages=True` when making the first agentic request. This tells the service to store the entire conversation history on xAI servers, including the model's reasoning, server-side tool calls, and corresponding responses.1. Add the parameter `store_messages=True` when making the first agentic request. This tells the service to store the entire conversation history on SpaceXAI servers, including the model's reasoning, server-side tool calls, and corresponding responses.
3722. Pass `previous_response_id=response.id` when creating the follow-up conversation, where `response` is the response returned by `chat.sample()` or `chat.stream()` from the conversation that you wish to continue.3722. Pass `previous_response_id=response.id` when creating the follow-up conversation, where `response` is the response returned by `chat.sample()` or `chat.stream()` from the conversation that you wish to continue.
373 373
374Note that the follow-up conversation does not need to use the same tools, model parameters, or any other configuration as the initial conversation—it will still be fully hydrated with the complete agentic state from the previous interaction.374Note that the follow-up conversation does not need to use the same tools, model parameters, or any other configuration as the initial conversation—it will still be fully hydrated with the complete agentic state from the previous interaction.
409 409
410### Append the Encrypted Agentic Tool Calling States410### Append the Encrypted Agentic Tool Calling States
411 411
412412There is another option for the ZDR (Zero Data Retention) users, or the users who don't want to use the above option, that is to let the xAI server also returnThere is another option for the ZDR (Zero Data Retention) users, or the users who don't want to use the above option, that is to let the SpaceXAI server also return
413the encrypted reasoning and the encrypted tool output besides the final content to the client side, and those encrypted contents can be included as a part of the context413the encrypted reasoning and the encrypted tool output besides the final content to the client side, and those encrypted contents can be included as a part of the context
414in the next turn conversation.414in the next turn conversation.
415 415
351 351
352When mixing tools:352When mixing tools:
353 353
354354* **Built-in tools** execute automatically on xAI servers* **Built-in tools** execute automatically on SpaceXAI servers
355* **Custom tools** pause execution and return to you for handling355* **Custom tools** pause execution and return to you for handling
356 356
357See [Advanced Usage](/developers/tools/advanced-usage#mixing-server-side-and-client-side-tools) for complete examples with tool loops.357See [Advanced Usage](/developers/tools/advanced-usage#mixing-server-side-and-client-side-tools) for complete examples with tool loops.
385| Field | Required | Description |385| Field | Required | Description |
386|-------|----------|-------------|386|-------|----------|-------------|
387| `name` | Yes | Unique identifier (max 350 tools per request) |387| `name` | Yes | Unique identifier (max 350 tools per request) |
388388| `description` | Yes | What the tool does — helps the model decide when to use it || `description` | No | What the tool does. Treated as empty if omitted; a clear description helps the model decide when to use it |
389| `parameters` | Yes | JSON Schema defining function inputs |389| `parameters` | Yes | JSON Schema defining function inputs |
390 390
391### Parameter Schema391### Parameter Schema
10 10
11| Type | Description | Examples |11| Type | Description | Examples |
12|------|-------------|----------|12|------|-------------|----------|
1313| **Built-in Tools** | Server-side tools managed by xAI that execute automatically | Web Search, X Search, Code Interpreter, Image Generation, Collections Search || **Built-in Tools** | Server-side tools managed by SpaceXAI that execute automatically | Web Search, X Search, Code Interpreter, Image Generation, Collections Search |
14| **Function Calling** | Custom functions you define that the model can invoke | Database queries, API calls, custom business logic |14| **Function Calling** | Custom functions you define that the model can invoke | Database queries, API calls, custom business logic |
15 15
1616Built-in tools run on xAI's servers—you provide the tool configuration, and the API handles execution and returns results. Function calling lets you define your own tools that the model can request, giving you full control over what happens when they're invoked.Built-in tools run on SpaceXAI's servers—you provide the tool configuration, and the API handles execution and returns results. Function calling lets you define your own tools that the model can request, giving you full control over what happens when they're invoked.
17 17
18## Pricing18## Pricing
19 19
2 2
3# Remote MCP Tools3# Remote MCP Tools
4 4
55Remote MCP Tools allow Grok to connect to external MCP (Model Context Protocol) servers, extending its capabilities with custom tools from third parties or your own implementations. Simply specify a server URL and optional configuration - xAI manages the MCP server connection and interaction on your behalf.Remote MCP Tools allow Grok to connect to external MCP (Model Context Protocol) servers, extending its capabilities with custom tools from third parties or your own implementations. Simply specify a server URL and optional configuration - SpaceXAI manages the MCP server connection and interaction on your behalf.
6 6
7## SDK Support7## SDK Support
8 8
169| Tool call types | Description |169| Tool call types | Description |
170|---------------|-------------|170|---------------|-------------|
171| `"client_side_tool"` | Client-side tool call - requires local execution |171| `"client_side_tool"` | Client-side tool call - requires local execution |
172172| `"web_search_tool"` | Web-search tool - handled by xAI server || `"web_search_tool"` | Web-search tool - handled by SpaceXAI server |
173173| `"x_search_tool"` | X-search tool - handled by xAI server || `"x_search_tool"` | X-search tool - handled by SpaceXAI server |
174174| `"code_execution_tool"` | Code-execution tool - handled by xAI server || `"code_execution_tool"` | Code-execution tool - handled by SpaceXAI server |
175175| `"collections_search_tool"` | Collections-search tool - handled by xAI server || `"collections_search_tool"` | Collections-search tool - handled by SpaceXAI server |
176176| `"mcp_tool"` | MCP tool - handled by xAI server || `"mcp_tool"` | MCP tool - handled by SpaceXAI server |
177 177
178### Using Responses API178### Using Responses API
179 179
182| Types | Description |182| Types | Description |
183|-------|-------------|183|-------|-------------|
184| `"function_call"` | Client-side tool - requires local execution |184| `"function_call"` | Client-side tool - requires local execution |
185185| `"web_search_call"` | Web-search tool - handled by xAI server || `"web_search_call"` | Web-search tool - handled by SpaceXAI server |
186186| `"x_search_call"` | X-search tool - handled by xAI server || `"x_search_call"` | X-search tool - handled by SpaceXAI server |
187187| `"code_interpreter_call"` | Code-execution tool - handled by xAI server || `"code_interpreter_call"` | Code-execution tool - handled by SpaceXAI server |
188188| `"file_search_call"` | Collections-search tool - handled by xAI server || `"file_search_call"` | Collections-search tool - handled by SpaceXAI server |
189189| `"mcp_call"` | MCP tool - handled by xAI server || `"mcp_call"` | MCP tool - handled by SpaceXAI server |
120|-----------|-------------|120|-----------|-------------|
121| `allowed_x_handles` | Only consider posts from specific X handles (max 20) |121| `allowed_x_handles` | Only consider posts from specific X handles (max 20) |
122| `excluded_x_handles` | Exclude posts from specific X handles (max 20) |122| `excluded_x_handles` | Exclude posts from specific X handles (max 20) |
123123| `from_date` | Start date for search range (ISO8601 format) || `from_date` | Start date for search range (`YYYY-MM-DD` date only) |
124124| `to_date` | End date for search range (ISO8601 format) || `to_date` | End date for search range (`YYYY-MM-DD` date only) |
125| `enable_image_understanding` | Enable analysis of images in posts |125| `enable_image_understanding` | Enable analysis of images in posts |
126| `enable_video_understanding` | Enable analysis of videos in posts |126| `enable_video_understanding` | Enable analysis of videos in posts |
127 127
219 219
220You can restrict the date range of search data used by specifying `from_date` and `to_date`. This limits the data to the period from `from_date` to `to_date`, including both dates.220You can restrict the date range of search data used by specifying `from_date` and `to_date`. This limits the data to the period from `from_date` to `to_date`, including both dates.
221 221
222222Both fields need to be in ISO8601 format, e.g., "YYYY-MM-DD". If you're using the xAI Python SDK, the `from_date` and `to_date` fields can be passed as `datetime.datetime` objects.Use `YYYY-MM-DD` for both fields, e.g., `"2025-10-01"`. Dates in any other format, including full date-times, aren't applied. If you're using the SpaceXAI Python SDK, you can pass `from_date` and `to_date` as `datetime.datetime` objects, but only the date (UTC) is used.
223 223
224```pythonXAI224```pythonXAI
225import os225import os
