xAI Grok API

https://docs.x.ai/
Admin
xAI Grok API is a developer platform that provides access to Grok, a frontier AI model designed to...
Tokens:511,036
Snippets:3,339
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### ngrok: Install, Authenticate, and Start Tunnel

Source: https://docs.x.ai/grok/connectors/custom-mcp-tunneling

Commands to install ngrok on macOS or Windows, authenticate with a free account, and start a tunnel to port 3001. The Forwarding URL from the output is used as the server URL in Grok.

```bash
# macOS
brew install ngrok

# Windows
winget install ngrok -s msstore

# Authenticate (free account required)
ngrok config add-authtoken YOUR_AUTH_TOKEN

```

```bash
ngrok http 3001

```

--------------------------------

### GET /v1/videos/{request_id} - JavaScript example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

JavaScript fetch example to retrieve video generation results using environment variables for the request ID and API key.

```javascript
const response = await fetch(
  `https://api.x.ai/v1/videos/${process.env.VIDEO_REQUEST_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    },
  },
);

console.log(JSON.stringify(await response.json(), null, 2));
```

--------------------------------

### GET /v1/videos/{request_id} - Python example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

Python requests example to retrieve video generation results using environment variables for the request ID and API key.

```python
import json
import os

import requests

request_id = os.environ["VIDEO_REQUEST_ID"]

response = requests.get(
    f"https://api.x.ai/v1/videos/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))
```

--------------------------------

### Manual polling for video generation with start() and get()

Source: https://docs.x.ai/developers/model-capabilities/video/generation

Manual polling workflow for video generation using start() and get() methods. The Python SDK example uses xai_sdk.Client and deferred_pb2 statuses; the Requests, JavaScript, and Bash examples use the REST API endpoints. Poll until status is done, expired, or failed, printing the video URL when ready.

```python
import os
import time
import xai_sdk
from xai_sdk.proto import deferred_pb2

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Start the generation request
start_response = client.video.start(
    prompt="A cat lounging in a sunbeam, tail gently swishing",
    model="grok-imagine-video-1.5",
    duration=5,
)

print(f"Request ID: {start_response.request_id}")

# Poll for results
while True:
    result = client.video.get(start_response.request_id)
    
    if result.status == deferred_pb2.DeferredStatus.DONE:
        print(f"Video URL: {result.response.video.url}")
        break
    elif result.status == deferred_pb2.DeferredStatus.EXPIRED:
        print("Request expired")
        break
    elif result.status == deferred_pb2.DeferredStatus.FAILED:
        print("Video generation failed")
        break
    elif result.status == deferred_pb2.DeferredStatus.PENDING:
        print("Still processing...")
        time.sleep(5)

```

```python
import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

# Step 1: Start generation
response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "A cat lounging in a sunbeam, tail gently swishing",
        "duration": 5,
    },
)

request_id = response.json()["request_id"]
print(f"Request ID: {request_id}")

# Step 2: Poll for results
while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()

    if data["status"] == "done":
        print(f"Video URL: {data['video']['url']}")
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    else:
        print("Still processing...")
        time.sleep(5)

```

```javascript
// Step 1: Start generation
const response = await fetch("https://api.x.ai/v1/videos/generations", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    },
    body: JSON.stringify({
        model: "grok-imagine-video-1.5",
        prompt: "A cat lounging in a sunbeam, tail gently swishing",
        duration: 5,
    }),
});

const { request_id } = await response.json();
console.log(`Request ID: ${request_id}`);

// Step 2: Poll for results
while (true) {
    const result = await fetch(`https://api.x.ai/v1/videos/${request_id}`, {
        headers: { "Authorization": `Bearer ${process.env.XAI_API_KEY}` },
    });

    const data = await result.json();

    if (data.status === "done") {
        console.log(`Video URL: ${data.video.url}`);
        break;
    } else if (data.status === "expired") {
        console.log("Request expired");
        break;
    } else if (data.status === "failed") {
        console.log("Video generation failed");
        break;
    } else {
        console.log("Still processing...");
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

```

```bash
# Step 1: Start generation
REQUEST_ID=$(curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A cat lounging in a sunbeam, tail gently swishing",
    "duration": 5
  }' | jq -r '.request_id')

echo "Request ID: $REQUEST_ID"

# Step 2: Poll for results
while true; do
  RESULT=$(curl -s https://api.x.ai/v1/videos/$REQUEST_ID \
    -H "Authorization: Bearer $XAI_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    echo "$RESULT" | jq -r '.video.url'
    break
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  echo "Still processing..."
  sleep 5
done

```

--------------------------------

### Import dependencies and define client-side tool

Source: https://docs.x.ai/developers/tools/advanced-usage

Sets up the OpenAI client with the xAI base URL and API key, defines a client-side get_weather function, and declares the tools list containing a function tool and a web_search tool. This is the prerequisite setup for the tool loop examples.

```python
import os
import json

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# Define client-side tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    # In a real app, this would query your database
    return f"The weather in {city} is sunny."

model = "grok-4.7"
tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the weather for a given city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "The name of the city",
                },
            },
            "required": ["city"],
        },
    },
    {
        "type": "web_search",
    },
]

```

--------------------------------

### 4-Agent Setup with OpenAI SDK (Python)

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the OpenAI client with base_url https://api.x.ai/v1 and reasoning.effort set to "low" for 4 agents. Prints the response output_text.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-multi-agent",
    reasoning={"effort": "low"},
    input=[
        {
            "role": "user",
            "content": "What are the key differences between TCP and UDP?",
        },
    ],
)

print(response.output_text)

```

--------------------------------

### Get video generation results with manual polling

Source: https://docs.x.ai/developers/grpc-api-reference/video

Manually poll for video generation results using start() and get() in the Python SDK, or via gRPC GetDeferredVideo. The Python example checks for DONE or FAILED status and sleeps 5 seconds between polls.

```python
import os
import time
import xai_sdk
from xai_sdk.proto import deferred_pb2

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Manual polling (alternative to generate() which does this automatically)
start = client.video.start(
    prompt="A cat lounging in a sunbeam",
    model="grok-imagine-video-1.5",
)

while True:
    result = client.video.get(start.request_id)
    if result.status == deferred_pb2.DeferredStatus.DONE:
        print(result.response.video.url)
        break
    elif result.status == deferred_pb2.DeferredStatus.FAILED:
        print("Generation failed")
        break
    time.sleep(5)

```

```bash
buf curl --schema . --protocol grpc \
  -H "Authorization: Bearer $XAI_API_KEY" \
  --data '{"request_id": "REQUEST_ID"}' \
  https://api.x.ai/xai_api.Video/GetDeferredVideo

```

--------------------------------

### Example config.toml for Grok Build

Source: https://docs.x.ai/build/settings

Copy this TOML into $GROK_HOME/config.toml or ~/.grok/config.toml when GROK_HOME is unset. It configures models, MCP servers, and UI options. Prefer /settings for UI, notifications, and other in-app options.

```toml
[models]
default = "grok-build"                       # recommended for coding / agent sessions
web_search = "grok-4.7"                      # model used by client-side web_search tool

[model."grok-4.7"]
model = "grok-4.7"                           # id sent to the API
base_url = "https://api.x.ai/v1"             # provider endpoint
name = "Grok 4.7"                            # shown in model picker
description = "Grok 4.7 from xAI"
env_key = "XAI_API_KEY"                      # env var holding the API key
api_backend = "responses"                    # chat_completions | responses | messages
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
context_window = 500000
extra_headers = { "x-api-key" = "xai-..." }
supports_backend_search = true               # if the endpoint supports Grok-hosted server-side search tools

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { "Authorization" = "Bearer ${LINEAR_API_KEY}", "x-mcp-session-id" = "{{session_id}}" }

[ui]
compact_mode = false
theme = "auto"
show_thinking_blocks = true

```

--------------------------------

### GET /v1/models - Example Request

Source: https://docs.x.ai/developers/rest-api-reference/inference/models

The request has no parameters. It is a GET request to the /v1/models endpoint.

```http
GET
/v1/models
```

--------------------------------

### 4-Agent Setup with xAI SDK (Python)

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the xai_sdk Client to create a chat with agent_count=4 and streams the response. Requires XAI_API_KEY environment variable.

```python
import os

from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.20-multi-agent",
    agent_count=4,
)

chat.append(user("What are the key differences between TCP and UDP?"))
for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="", flush=True)

```

--------------------------------

### Team Setup manifest JSON for private-network

Source: https://docs.x.ai/grok-bot/private-networks

JSON structure for a Team Setup manifest that installs a networking client. The setup script is a placeholder that you replace with your provider's Linux install commands and your network connection configuration. The check script uses `command -v <your-client>` to skip the setup on computers that already have the client.

```json
{
  "manifestId": "private-network",
  "entries": [
    {
      "id": "install-network-client",
      "setup": "#!/usr/bin/env bash\nset -euo pipefail\n# 1) Install your networking client per your provider's Linux install docs\n# 2) Start the client and connect it to your network per your configuration",
      "check": "command -v <your-client>"
    }
  ]
}
```

--------------------------------

### Python example using OpenAI SDK for /v1/responses/compact

Source: https://docs.x.ai/docs/api-reference

Uses the OpenAI Python client with base_url set to https://api.x.ai/v1 and the XAI_API_KEY environment variable. Calls client.responses.compact with the model and input, then prints the compacted response as JSON.

```python
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

compacted = client.responses.compact(
    model="grok-4.7",
    input=[
        {"role": "system", "content": "You are a concise and knowledgeable science tutor."},
        {"role": "user", "content": "What is the Higgs boson and why is it important?"},
        {
            "role": "assistant",
            "content": (
                "The Higgs boson is an elementary particle in the Standard Model, predicted by "
                "Peter Higgs in 1964 and confirmed at CERN in 2012. It is the quantum excitation "
                "of the Higgs field, which gives mass to fundamental particles via the Higgs mechanism."
            ),
        },
        {"role": "user", "content": "How does the Higgs mechanism actually work?"},
        {
            "role": "assistant",
            "content": (
                "Through spontaneous symmetry breaking. The Higgs field has a nonzero vacuum value, "
                "and particles acquire mass in proportion to how strongly they couple to it. Photons "
                "do not couple, which is why they remain massless."
            ),
        },
    ],
)

print(compacted.model_dump_json(indent=2))
```

--------------------------------

### Example server_side_tool_usage output

Source: https://docs.x.ai/developers/tools/tool-usage-details

Example output of response.server_side_tool_usage showing invocation counts for X Search and Web Search tools.

```output
{'SERVER_SIDE_TOOL_X_SEARCH': 3, 'SERVER_SIDE_TOOL_WEB_SEARCH': 2}

```

--------------------------------

### GetDeferredVideo

Source: https://docs.x.ai/developers/grpc-api-reference/video

Gets the result of a video generation started by calling GenerateVideo or ExtendVideo. Video generation is asynchronous. The SDK's `generate()` and `extend()` methods handle polling automatically. For manual control, use `start()` / `extend_start()` and `get()`.

```APIDOC
## GetDeferredVideo

### Description
Gets the result of a video generation started by calling GenerateVideo or ExtendVideo. Video generation is asynchronous. The SDK's `generate()` and `extend()` methods handle polling automatically. For manual control, use `start()` / `extend_start()` and `get()`.

### Method
unary

### Endpoint
xai_api.Video/GetDeferredVideo

### Parameters
#### Request Body
- **request_id** (string) - Required - The request ID returned from GenerateVideo or ExtendVideo.

### Request Example
{
  "request_id": "REQUEST_ID"
}

### Response
#### Success Response
Returns the result of the video generation, including the video URL and status.

#### Response Example
{
  "status": "DONE",
  "response": {
    "video": {
      "url": "https://example.com/video.mp4"
    }
  }
}
```

--------------------------------

### Useful first prompts for Grok

Source: https://docs.x.ai/build/overview

Example prompts to try in the Grok TUI. The @src/main.rs syntax references a file in the project.

```text
Explain this repo.
@src/main.rs Walk me through this file.

```

--------------------------------

### Response from start generation request

Source: https://docs.x.ai/developers/model-capabilities/video/generation

Example JSON response from the start generation request, containing the request_id used for polling.

```json
{"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"}
```

--------------------------------

### Define tool combinations with xai_sdk

Source: https://docs.x.ai/developers/tools/advanced-usage

Shows how to define tool combinations using the xai_sdk Python package. The example creates three setups: research (web_search + code_execution), news (web_search + x_search), and comprehensive (all three tools).

```python
from xai_sdk.tools import web_search, x_search, code_execution

# Example tool combinations for different scenarios
research_setup = [web_search(), code_execution()]
news_setup = [web_search(), x_search()]
comprehensive_setup = [web_search(), x_search(), code_execution()]
```

--------------------------------

### GET /v1/custom-voices/{voice_id} - Example response

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON response for the GET /v1/custom-voices/{voice_id} endpoint. Shows the voice metadata fields returned, including voice_id, name, description, gender, accent, age, language, use_case, tone, and created_at.

```json
{
  "voice_id": "nlbqfwie",
  "name": "Friendly Narrator",
  "description": "Warm, conversational tone for narration.",
  "gender": "female",
  "accent": "American",
  "age": "young",
  "language": "en",
  "use_case": "narration",
  "tone": "warm",
  "created_at": "2026-04-26T18:56:34.872993+00:00"
}

```

--------------------------------

### JavaScript example using OpenAI SDK for /v1/responses/compact

Source: https://docs.x.ai/docs/api-reference

Uses the OpenAI JavaScript client with baseURL set to https://api.x.ai/v1 and the XAI_API_KEY environment variable. Calls client.responses.compact with the model and input, then logs the compacted response as JSON.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const compacted = await client.responses.compact({
  model: "grok-4.7",
  input: [
    { role: "system", content: "You are a concise and knowledgeable science tutor." },
    { role: "user", content: "What is the Higgs boson and why is it important?" },
    {
      role: "assistant",
      content:
        "The Higgs boson is an elementary particle in the Standard Model, predicted by Peter Higgs in 1964 and confirmed at CERN in 2012. It is the quantum excitation of the Higgs field, which gives mass to fundamental particles via the Higgs mechanism.",
    },
    { role: "user", content: "How does the Higgs mechanism actually work?" },
    {
      role: "assistant",
      content:
        "Through spontaneous symmetry breaking. The Higgs field has a nonzero vacuum value, and particles acquire mass in proportion to how strongly they couple to it. Photons do not couple, which is why they remain massless.",
    },
  ],
});

console.log(JSON.stringify(compacted, null, 2));
```

--------------------------------

### Cloudflare Tunnel: Install and Start Quick Tunnel

Source: https://docs.x.ai/grok/connectors/custom-mcp-tunneling

Commands to install cloudflared on macOS or Windows and start a quick tunnel to localhost:3001. The generated *.trycloudflare.com URL is used as the server URL in Grok. Note: Cloudflare quick tunnels do not support SSE.

```bash
# macOS
brew install cloudflared

# Windows
winget install --id Cloudflare.cloudflared

# Start a quick tunnel
cloudflared tunnel --url http://localhost:3001

```

--------------------------------

### GET /v1/models/{model_id} 200 response

Source: https://docs.x.ai/developers/rest-api-reference/inference/models

Example 200 response for GET /v1/models/{model_id}. Shows model metadata and pricing fields.

```json
{
  "id": "latest",
  "created": 1776556800,
  "object": "model",
  "owned_by": "xai",
  "prompt_text_token_price": 12500,
  "cached_prompt_text_token_price": 2000,
  "prompt_image_token_price": 12500,
  "completion_text_token_price": 25000
}
```

--------------------------------

### GetDeferredCompletion

Source: https://docs.x.ai/developers/grpc-api-reference/chat

Gets the result of a deferred completion started by calling StartDeferredCompletion.

```APIDOC
## GetDeferredCompletion

### Description
Gets the result of a deferred completion started by calling StartDeferredCompletion.

### Method
unary

### Endpoint
xai_api.Chat/GetDeferredCompletion
```

--------------------------------

### Sample reasoning output

Source: https://docs.x.ai/developers/model-capabilities/text/reasoning

Example output showing the reasoning text streamed for a projectile motion problem. Demonstrates the format of the reasoning summary.

```text
--------- Reasoning ---------
The problem is: A projectile is launched at 30 m/s at 37° above horizontal from a 45 m cliff. Find its speed on impact. (g=10 m/s²)
I need to find the speed when the projectile hits the ground. It's launched at 30 m/s at 37° from a 45 m cliff, with g=10 m/s².

Conservation of energy is a good approach. The initial kinetic energy is (1/2)mv² with v=30 m/s, and initial potential energy is mgh with h=45 m, taking ground as zero.

At impact, potential energy is zero, so initial KE + initial PE = final KE.

Thus, (1/2)m(30)² + mg(45) = (1/2)m v_f²

v_f² = 900 + 2*10*45 = 900 + 900 = 1800

v_f = sqrt(1800) = 30√2 m/s ≈ 42.4 m/s

The angle doesn't affect the final speed because the initial kinetic energy and potential energy change are the same regardless of direction, as long as the speed and height are the same.

Yes, that makes sense. The final speed is sqrt(v0² + 2gh), independent of the launch angle.

```

--------------------------------

### Image understanding example - Python (xAI SDK)

Source: https://docs.x.ai/developers/model-capabilities/legacy/chat-completions

Uses the xai_sdk to create a chat with an image and text, then prints the response.

```Python
import os

from xai_sdk import Client
from xai_sdk.chat import user, image

client = Client(api_key=os.getenv('XAI_API_KEY'))

image_url = "https://science.nasa.gov/wp-content/uploads/2023/09/web-first-images-release.png"

chat = client.chat.create(model="grok-4")
chat.append(
    user(
        "What's in this image?",
        image(image_url=image_url, detail="high"),
    )
)

response = chat.sample()
print(response.content)

```

--------------------------------

### 200 Response for GET /v1/language-models/{model_id}

Source: https://docs.x.ai/developers/rest-api-reference/inference/models

Example 200 response for GET /v1/language-models/{model_id}. Shows model metadata including pricing fields, aliases, and modalities.

```json
{
  "id": "latest",
  "fingerprint": "fp_156d35dcaa",
  "created": 1743724800,
  "object": "model",
  "owned_by": "xai",
  "version": "1.0.0",
  "input_modalities": [
    "text"
  ],
  "output_modalities": [
    "text"
  ],
  "prompt_text_token_price": 20000,
  "cached_prompt_text_token_price": 0,
  "prompt_image_token_price": 0,
  "completion_text_token_price": 100000,
  "aliases": [
    "grok-4",
    "grok-4-latest"
  ]
}
```

--------------------------------

### GET /v1/language-models 200 response

Source: https://docs.x.ai/developers/rest-api-reference/inference/models

Example 200 response for GET /v1/language-models. Shows full model information including modalities, fingerprint, aliases, and pricing.

```json
{
  "models": [
    {
      "id": "latest",
      "fingerprint": "fp_777a9f8466",
      "created": 1776556800,
      "object": "model",
      "owned_by": "xai",
      "version": "1.0",
      "input_modalities": [
        "text",
        "image"
      ],
      "output_modalities": [
        "text"
      ],
      "prompt_text_token_price": 12500,
      "cached_prompt_text_token_price": 2000,
      "prompt_image_token_price": 12500,
      "completion_text_token_price": 25000,
      "search_price": 0,
      "prompt_text_token_price_long_context": 0,
      "cached_prompt_text_token_price_long_context": 0,
      "completion_text_token_price_long_context": 0,
      "long_context_threshold": 0,
      "aliases": [
        "grok-4.3-latest"
      ]
    },
    {
      "id": "grok-420-reasoning",
      "fingerprint": "fp_5319828d69",
      "created": 1768003200,
      "object": "model",
      "owned_by": "xai",
      "version": "1.0",
      "input_modalities": [
        "text"
      ],
      "output_modalities": [
        "text"
      ],
      "prompt_text_token_price": 20000,
      "cached_prompt_text_token_price": 2000,
      "prompt_image_token_price": 0,
      "completion_text_token_price": 80000,
      "search_price": 0,
      "prompt_text_token_price_long_context": 40000,
      "cached_prompt_text_token_price_long_context": 0,
      "completion_text_token_price_long_context": 160000,
      "long_context_threshold": 128000,
      "aliases": [],
      "capabilities": {
        "reasoning_effort": [
          "low",
          "medium",
          "high",
          "xhigh"
        ],
        "default_reasoning_effort": "high"
      }
    }
  ]
}
```

--------------------------------

### JavaScript fetch example for /v1/videos/edits

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

Use this JavaScript fetch example to edit a video. It sends a POST request to /v1/videos/edits with the model, prompt, and video URL from environment variables. The response is logged as pretty-printed JSON.

```javascript
const response = await fetch("https://api.x.ai/v1/videos/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-imagine-video",
    prompt: "Give the woman a silver necklace",
    video: {
      url: process.env.VIDEO_URL,
    },
  }),
});

console.log(JSON.stringify(await response.json(), null, 2));
```

--------------------------------

### POST /v1/completions response example

Source: https://docs.x.ai/developers/rest-api-reference/inference/legacy

Example 200 response for the legacy completions endpoint. Shows choices, usage, and system_fingerprint.

```json
{
  "id": "873492b3-6144-4279-ac2e-2c45242c5ce6",
  "object": "text_completion",
  "created": 1743771779,
  "model": "grok-3",
  "choices": [
    {
      "index": 0,
      "text": "5, ",
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15,
    "prompt_tokens_details": {
      "text_tokens": 12,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_156d35dcaa"
}
```

--------------------------------

### Example output of tool calls

Source: https://docs.x.ai/developers/tools/advanced-usage

Shows the expected output from the tool loop: a server-side web_search call, a client-side get_weather call, and the final response.

```text
Server-side tool call: web_search with arguments: {"query":"Who won the 2025 NBA championship?","num_results":5}
Client-side tool call: get_weather with arguments: {"city":"Oklahoma City"}
Final response: The Oklahoma City Thunder won the 2025 NBA championship. The current weather in Oklahoma City is sunny.

```

--------------------------------

### Get voice response JSON

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON response from the GET /v1/tts/voices/{voice_id} endpoint for voice_id 'eve'. Shows the voice details: voice_id, name, and language.

```json
{
  "voice_id": "eve",
  "name": "Eve",
  "language": "multilingual"
}

```

--------------------------------

### Get custom voice audio response

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON output for the GET /v1/custom-voices/{voice_id}/audio endpoint. Shows a successful response with status 200 and the audio byte length.

```json
{
  "status": 200,
  "audio_bytes": 1536044
}

```

--------------------------------

### Basic Usage with xAI SDK (Python)

Source: https://docs.x.ai/developers/tools/x-search

Use the xAI SDK to create a chat with the x_search tool and stream responses. Requires an XAI_API_KEY environment variable. The example prints tool calls, thinking progress, final content, and citations.

```python
import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",  # reasoning model
    tools=[x_search()],
    include=["verbose_streaming"],
)

chat.append(user("What are people saying about xAI on X?"))

is_thinking = True
for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\n\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\n\nCitations:")
print(response.citations)
```

--------------------------------

### client.image.sample()

Source: https://docs.x.ai/developers/model-capabilities/images/multi-image-editing

SDK method for multi-image editing using the xAI Python SDK.

```APIDOC
## client.image.sample()

### Description
Generates an image edit using the xAI SDK. Accepts a prompt, a model, a list of image URLs, and an optional aspect ratio.

### Method
client.image.sample()

### Parameters
- **prompt** (string) - Required - Natural language description of the desired edit.
- **model** (string) - Required - The model to use, e.g., `grok-imagine-image-2.0`.
- **image_urls** (list of strings) - Required - List of source image URLs. Can be public URLs, base64 data URIs, or `file_id` values.
- **aspect_ratio** (string) - Optional - Desired output aspect ratio, e.g., `"3:2"`.

### Request Example
```python
import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="Show all subjects sitting together on the grass in a sunny park. Casual relaxed mood, natural daylight, warm tones. No additional people or animals.",
    model="grok-imagine-image-2.0",
    image_urls=[
        "https://docs.x.ai/assets/api-examples/images/image-merge/woman.jpg",
        "https://docs.x.ai/assets/api-examples/images/image-merge/man.jpg",
    ],
    aspect_ratio="3:2",
)

print(response.url)
```

### Response
- **response.url** (string) - URL of the generated image.
```
Tokens:
Raw