xai-sdk

library1.19.0pypypi✓ verified 26d ago

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.

llm-agents ai-ml

pip install xai-sdk

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · XAI-SDK

xai-sdk

llm-agentspythonv1.19.0

Install

7.2s avg

Import

1848ms

Disk

69MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.19.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 8.85s

py 3.11

✓ —

✓ 7.25s

py 3.12

✓ —

✓ 6.15s

py 3.13

✓ —

✓ 6.35s

py 3.9

1/2 runs

69MB installed

● package 69MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from xai_sdk import Client

✗ import xai_sdk xai_sdk.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')

✗ from openai import OpenAI client = OpenAI()

Must override both api_key and base_url

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)

Debug

Known issues

breakingAnthropic 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

affects: all

breakingLive 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

affects: all

breakinggrok-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

affects: all

breakingNative 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.

affects: 1.x

gotchagrok-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

affects: all

gotchapip 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)

affects: all

gotchaMultiple 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

affects: all

breakingxai-sdk requires Python 3.10 or higher.

fix

Ensure your Python environment is 3.10 or newer.

affects: all

breakingThe 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.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'xai_sdk'

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.

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

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")`.

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

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(...)`.

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

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!"}]`.

Upgrade

Version history

1.19.0latest on PyPI · released Aug 18, 2026

Audit

Dependencies

xai-sdk[telemetry-grpc]optionalOptional OpenTelemetry tracing via gRPC backend

xai-sdk[telemetry-http]optionalOptional OpenTelemetry tracing via HTTP backend

Agent activity

131 hits · last 30 days

node

124

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/xai-org/xai-sdk-python ↗

packagehttps://pypi.org/project/xai-sdk/ ↗

homepagehttps://x.ai ↗

docshttps://docs.x.ai ↗