xAI Grok Python SDK

1.7.0 · active · verified Sat Feb 28

Official Python SDK for xAI's Grok models — gRPC-based client for chat, image generation, and agentic tool use. Also supports OpenAI-compatible REST API.

Warnings

breaking Anthropic SDK compatibility is fully deprecated. Using Anthropic SDK with xAI base_url will fail.
Fix: Migrate to native xai-sdk, OpenAI-compatible interface, or Vercel AI SDK
breaking Live Search API (search_parameters field) deprecated as of December 15, 2025. Replaced by Agent Tools API which requires the Responses API endpoint.
Fix: Use Agent Tools API with xai.responses(modelId) — web_search, x_search, code_execution now server-side tools
breaking grok-beta and grok-vision-beta model names are legacy. grok-beta was an alias for Grok 2.
Fix: Use grok-3, grok-3-mini-beta, grok-4, or grok-4-fast explicitly
breaking Native xai-sdk uses gRPC (not REST). Errors raised on timeout are grpc.RpcError with StatusCode.DEADLINE_EXCEEDED — not standard Python HTTP exceptions.
Fix: Catch grpc.RpcError specifically. Default timeout is 900s. Set client = Client(timeout=300) to override.
gotcha grok-3-mini-beta and grok-3-mini-fast-beta support reasoning_effort ('low'/'high'). Full grok-3 does NOT support reasoning_effort — passing it is silently ignored or errors.
Fix: Only pass reasoning_effort to mini/reasoning variants
gotcha pip install grok installs a completely unrelated Zope web framework (v6.x). The correct package is xai-sdk.
Fix: pip install xai-sdk (not grok, not xai-grok, not xai-grok-sdk — all are third-party or unrelated)
gotcha Multiple unofficial packages on PyPI: xai-grok, xai-grok-sdk, xai-grok-sdk-advanced. None are official. Only xai-sdk is maintained by xAI.
Fix: Use pip install xai-sdk from pypi.org/project/xai-sdk

Install

pip install xai-sdk Official SDK (gRPC-based)
pip install openai OpenAI-compatible alternative

Imports

Client
```
from xai_sdk import Client
```
Package installs as xai-sdk but module is xai_sdk (underscore)

OpenAI-compat

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

Must override both api_key and base_url

Quickstart

Chat completion via OpenAI-compatible interface (recommended for portability)

from openai import OpenAI
import os

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

response = client.chat.completions.create(
    model='grok-3',
    messages=[{'role': 'user', 'content': 'Hello'}]
)
print(response.choices[0].message.content)

view raw JSON →