xAI Grok Python SDK

1.7.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install xai-sdk

Common errors

error ModuleNotFoundError: No module named 'xai_sdk' ↓

cause The `xai-sdk` library has not been installed in your Python environment or the current environment is not active.

fix

Run pip install xai-sdk to install the library.

error xai_sdk.exceptions.XaiAPIError: UNAUTHENTICATED: Invalid API key. ↓

cause The API key provided for authentication is either missing, incorrect, or expired, preventing access to the Grok API.

fix

Ensure your XAI_API_KEY environment variable is correctly set with a valid API key, or pass it directly to the XaiClient constructor: xai_client = XaiClient(api_key="your_api_key_here").

error AttributeError: 'Chat' object has no attribute 'create' ↓

cause You are attempting to call `create()` directly on the `chat` object, but the correct method is nested under `completions` for chat completions.

fix

Access chat completions via xai_client.chat.completions.create(...) instead of xai_client.chat.create(...).

error xai_sdk.exceptions.XaiAPIError: INVALID_ARGUMENT: 'messages' must be a list of dictionaries. ↓

cause The `messages` parameter for chat completions was not provided in the correct format (a list of dictionaries, where each dictionary represents a message with 'role' and 'content' keys).

fix

Ensure the messages parameter is a list of dictionaries, for example: messages=[{"role": "user", "content": "Hello!"}].

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

breaking xai-sdk requires Python 3.10 or higher. ↓

fix Ensure your Python environment is 3.10 or newer.

breaking The XAI_API_KEY environment variable is required for authentication to the xAI API using the xai-sdk. Failure to set this variable will result in a KeyError. ↓

fix Set the XAI_API_KEY environment variable before running the application, e.g., export XAI_API_KEY='your_api_key_here' or pass it directly in your deployment environment configuration.

Install

pip install openai

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) openai - - - -

3.10 alpine (musl) xai-sdk - - 2.02s 69.7M

3.10 slim (glibc) openai - - - -

3.10 slim (glibc) xai-sdk - - 1.12s 69M

3.11 alpine (musl) openai - - - -

3.11 alpine (musl) xai-sdk - - 2.75s 74.8M

3.11 slim (glibc) openai - - - -

3.11 slim (glibc) xai-sdk - - 1.62s 74M

3.12 alpine (musl) openai - - - -

3.12 alpine (musl) xai-sdk - - 2.64s 66.1M

3.12 slim (glibc) openai - - - -

3.12 slim (glibc) xai-sdk - - 2.02s 65M

3.13 alpine (musl) openai - - - -

3.13 alpine (musl) xai-sdk - - 2.57s 65.7M

3.13 slim (glibc) openai - - - -

3.13 slim (glibc) xai-sdk - - 1.97s 65M

3.9 alpine (musl) openai - - - -

3.9 alpine (musl) xai-sdk - - - -

3.9 slim (glibc) openai - - - -

3.9 slim (glibc) xai-sdk - - - -

Imports

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

OpenAI-compat

wrong

from openai import OpenAI
client = OpenAI()

correct

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 stale last tested: 2026-05-12

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)