xAI ↗

Original Documentation

xAI provides access to Grok models through the xai-sdk package, enabling structured outputs with Instructor. This guide covers everything you need to know about using xAI’s Grok models with Instructor for type-safe, validated responses.

Quick Start#

Instructor is distributed without xAI dependencies by default. Install xAI support with the optional xai extra:

pip install "instructor[xai]"

Or using uv:

uv pip install "instructor[xai]"

⚠️ Important: You must set your xAI API key before using the client. You can do this in two ways:

Set the environment variable:

export XAI_API_KEY='your-api-key-here'

The xAI SDK will use this environment variable automatically.

Simple User Example (Sync)#

import instructor
from pydantic import BaseModel

# Auto-configure xAI client
client = instructor.from_provider("xai/grok-3-mini")

class User(BaseModel):
    name: str
    age: int

# Create structured output
user = client.create(
    response_model=User,
    messages=[
        {"role": "user", "content": "Extract: Jason is 25 years old"},
    ],
)

print(user)
#> User(name='Jason', age=25)

Simple User Example (Async)#

import instructor
from pydantic import BaseModel
import asyncio

# Auto-configure async xAI client
client = instructor.from_provider("xai/grok-3-mini", async_client=True)

class User(BaseModel):
    name: str
    age: int

async def extract_user():
    user = await client.create(
        response_model=User,
        messages=[
            {"role": "user", "content": "Extract: Jason is 25 years old"},
        ],
    )
    return user

# Run async function
user = asyncio.run(extract_user())
print(user)
#> User(name='Jason', age=25)

Nested Example#

from pydantic import BaseModel
from typing import List
import instructor

class Address(BaseModel):
    street: str
    city: str
    country: str

class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]

# Auto-configure xAI client
client = instructor.from_provider("xai/grok-3-mini")

# Create structured output with nested objects
user = client.create(
    response_model=User,
    messages=[
        {"role": "user", "content": """
            Extract: Jason is 25 years old.
            He lives at 123 Main St, New York, USA
            and has a summer house at 456 Beach Rd, Miami, USA
        """},
    ],
)

print(user)
#> {
#>     'name': 'Jason',
#>     'age': 25,
#>     'addresses': [
#>         {
#>             'street': '123 Main St',
#>             'city': 'New York',
#>             'country': 'USA'
#>         },
#>         {
#>             'street': '456 Beach Rd',
#>             'city': 'Miami',
#>             'country': 'USA'
#>         }
#>     ]
#> }

Instructor Modes#

xAI supports the following modes:

instructor.Mode.JSON : Forces the model to return JSON output (default)
instructor.Mode.TOOLS : Uses function calling for structured outputs

import instructor
from instructor import Mode

# Using JSON mode (default)
client = instructor.from_provider("xai/grok-3-mini", mode=Mode.JSON)

# Using TOOLS mode
client = instructor.from_provider("xai/grok-3-mini", mode=Mode.TOOLS)

Available Models#

xAI provides access to the following models:

grok-3 - The most capable Grok model for complex reasoning tasks
grok-3-mini - A smaller, faster version optimized for speed and cost

Limitations#

Streaming Support#

⚠️ Note: Streaming responses (create_iterable and create_partial) are not yet supported due to differences in xAI’s streaming API. See issue #1663 for updates.

Python Version#

⚠️ Requires Python 3.10+: The xAI SDK requires Python 3.10 or higher.

Best Practices#

1. API Key Management#

Store your xAI API key securely using environment variables:

export XAI_API_KEY="your-api-key-here"

2. Model Selection#

Use grok-3-mini for:
Simple extraction tasks
High-volume processing
Cost-sensitive applications
Use grok-3 for:
Complex reasoning tasks
Multi-step analysis
Higher accuracy requirements

3. Error Handling#

Always handle potential API errors gracefully:

try:
    user = client.create(
        response_model=User,
        messages=[{"role": "user", "content": "Extract user data"}],
    )
except Exception as e:
    print(f"Error: {e}")

Common Use Cases#

Data Extraction from unstructured text
Form parsing and validation
Content classification
Entity recognition
Structured data generation

Updates and Compatibility#

Instructor maintains compatibility with the latest xAI SDK versions. Check the changelog for updates.

Link last verified June 7, 2026. View original ↗

Source: Instructor Docs

Link last verified: 2026-03-04