xAI (Grok) API Development

Source: https://docs.x.ai

xAI provides the Grok family of AI models via a REST API that's OpenAI-compatible. Grok excels at truthful, insightful answers with unique capabilities like live web search and reasoning.

Quick Start

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-api-key",
    base_url="https://api.x.ai/v1"
)

response = client.chat.completions.create(
    model="grok-3-latest",
    messages=[
        {"role": "user", "content": "What's happening in AI today?"}
    ]
)
print(response.choices[0].message.content)

Model Selection

Key Features

Chat with Reasoning

Grok 3 supports extended thinking for complex problems:

response = client.chat.completions.create(
    model="grok-3-latest",
    messages=[{"role": "user", "content": "Solve this step by step..."}],
    reasoning_effort="high"  # low, medium, high
)

Live Web Search

Enable real-time web access:

response = client.chat.completions.create(
    model="grok-3-latest",
    messages=[{"role": "user", "content": "What's the latest news?"}],
    tools=[{"type": "web_search"}]
)

Function Calling

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="grok-3-latest",
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto"
)

Image Understanding

response = client.chat.completions.create(
    model="grok-vision-beta",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
    }]
)

Image Generation

response = client.images.generate(
    model="aurora",
    prompt="A futuristic city at sunset",
    n=1,
    size="1024x1024"
)
print(response.data[0].url)

Structured Outputs

response = client.chat.completions.create(
    model="grok-3-latest",
    messages=[{"role": "user", "content": "List 3 planets"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "planets",
            "schema": {
                "type": "object",
                "properties": {
                    "planets": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                }
            }
        }
    }
)

Best Practices

1. Use OpenAI SDK - xAI API is OpenAI-compatible; use the official OpenAI Python/JS SDK with base_url="https://api.x.ai/v1"

2. Choose the right model - Use grok-3-latest for quality, grok-3-fast for speed, grok-3-mini for cost

3. Enable streaming - For long responses, use stream=True to improve perceived latency

4. Handle rate limits - Implement exponential backoff; check x-ratelimit-* headers

5. Use tools effectively - Combine web search with function calling for powerful agentic workflows

6. Regional endpoints - Use regional endpoints for lower latency and data residency requirements

Tools Available

Grok supports built-in tools:

• web_search - Real-time web search
• code_execution - Run Python code in sandbox
• collection_search - Search your uploaded documents
• Remote MCP tools - Connect to external MCP servers

Stateful Responses API

For multi-turn conversations with memory:

# Create a response with state
response = client.responses.create(
    model="grok-3-latest",
    input="Remember my name is Alice"
)

# Continue the conversation
response = client.responses.create(
    model="grok-3-latest",
    input="What's my name?",
    previous_response_id=response.id
)

Documentation Index

Syncing Documentation

cd skills/xai
bun install        # Install playwright (first time only)
bun run scripts/sync-docs.ts

The sync script uses Playwright to bypass Cloudflare protection on docs.x.ai.