The xAI Python SDK

Updated November 3, 2026, based on the xAI best practices and API reference: temperature capped at 1 and recommended at 0.7. Source: Best practices. The call example follows the SDK README (chat.append(user(...)), chat.sample(), response.content) and was run to verify it.

xAI’s official Python SDK

xAI’s native Python SDK is the most direct way to work with the Grok API. It exposes the platform’s specific features and gets updates first when new models or endpoints are added.

Installation

Install the SDK with pip in your Python environment:

pip install xai-sdk

We recommend using a virtual environment to isolate each project’s dependencies:

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install xai-sdk

Initialize the client

The Client class is the SDK’s entry point. It handles authentication, HTTP connections, and request serialization:

from xai_sdk import Client
import os

client = Client(api_key=os.getenv("XAI_API_KEY"))

If the XAI_API_KEY environment variable is set, you can also create the client without an explicit argument:

client = Client()

The SDK detects the variable automatically and uses it for authentication.

Send a request

Once the client is initialized, the SDK thinks in conversations: client.chat.create() creates the conversation (without sending anything), append adds a message built with user() or system(), and sample() asks the model for its answer:

import os

from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(model="grok-4.7")
chat.append(user("Explain what a REST API is in 3 sentences."))
response = chat.sample()

print(response.content)

Common parameters

• model: the ID of the model to use (required); xAI recommends grok-4.7
• messages: the conversation’s starting messages, built with system(), user(), and assistant() from xai_sdk.chat (plain dictionaries make the call fail)
• temperature: from 0 to 2, capped at 1 above that; xAI recommends 0.7, with top_p at 0.95
• max_tokens: the maximum number of tokens generated
• reasoning_effort: the depth of reasoning (none, low, medium, high), which xAI recommends setting on every request

Streaming doesn’t go through a parameter: for response, chunk in chat.stream(): returns the fragments as they arrive in chunk.content. Lesson 10 shows streaming with the REST API, over SSE.

Advantages of the native SDK

Compared with the OpenAI SDK pointed at the xAI API (next lesson), the native SDK gives direct access to xAI-specific features: X and web search, server-side tools, video generation, document collections. Its complete Python types power your editor’s autocompletion, and xAI maintains it at the API’s pace. It also has its own shape, which you have to accept: it runs over gRPC, its messages are built with user() and system(), and its errors are grpc.RpcError.

When to choose this SDK

The choice follows naturally from your situation. For a new project built specifically on the Grok API, the native SDK is the obvious starting point: you get everything above with no compatibility constraints to respect. It becomes essential as soon as you plan to use xAI-specific features such as X search or built-in web search, which only work fully this way. If, on the other hand, you have existing code built on the OpenAI SDK, don’t rewrite anything for now: the next lesson shows how to adapt it by changing two lines.

Key takeaways

• Install with pip install xai-sdk in a virtual environment
• The Client class is the entry point, with automatic detection of XAI_API_KEY
• client.chat.create() creates a conversation; chat.append(user(...)) adds a message, and chat.sample() returns the answer, read from response.content
• Prefer this SDK for new projects that target only the Grok API