Structured outputs with xAI, a complete guide with instructor¶

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¶

Install Instructor with xAI support:

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.chat.completions.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.chat.completions.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.chat.completions.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.chat.completions.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.