xAI

https://github.com/xai-org/xai-sdk-python
Admin
The official Python SDK for xAI's APIs, providing synchronous and asynchronous clients for...
Tokens:88,146
Snippets:557
Trust Score:8
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### start / get

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Submits a video generation request and polls for its status. start returns a StartDeferredResponse with a request_id, and get retrieves the status of a previously submitted request.

```APIDOC
## start / get

### Description
Submits a video generation request and polls for its status. `start` returns a `StartDeferredResponse` carrying a `request_id`; `get` retrieves the status of a previously submitted request.

### Method
start: submit generation request
get: poll status

### Signatures
```python
def start(self, prompt: str, model: Union[VideoGenerationModel, str], *, <same optional params as generate minus timeout/interval>) -> deferred_pb2.StartDeferredResponse
def get(self, request_id: str) -> video_pb2.GetDeferredVideoResponse
```

### Parameters
#### start
- **prompt** (str) - Required - The text prompt describing the video to generate.
- **model** (Union[VideoGenerationModel, str]) - Required - The model to use for generation.
- **optional params** - Optional - Same optional parameters as `generate`, excluding `timeout` and `interval`.

#### get
- **request_id** (str) - Required - The ID of the deferred request to poll.

### Request Example
```python
import time
from xai_sdk import Client
from xai_sdk.proto import deferred_pb2, video_pb2

client = Client()
started = client.video.start("Waves crashing", model="grok-imagine-video")
while True:
    r = client.video.get(started.request_id)
    if r.status == deferred_pb2.DeferredStatus.DONE:
        print(r.response.video.url if r.HasField("response") else "no response")
        break
    if r.status == deferred_pb2.DeferredStatus.FAILED:
        print("failed", r.response.error)
        break
    time.sleep(1)
```

### Response
#### start
- **StartDeferredResponse** - Contains `request_id` for polling.

#### get
- **GetDeferredVideoResponse** - Contains status and response fields. Status can be `DONE` or `FAILED`. When `DONE`, `response.video.url` provides the video URL if present; when `FAILED`, `response.error` provides error details.
```

--------------------------------

### Installation Requirements - xai-sdk[telemetry-http] and xai-sdk[telemetry-grpc]

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Install additional dependencies for HTTP or gRPC OTLP export. Use pip or uv.

```bash
# For HTTP OTLP export
pip install xai-sdk[telemetry-http]
# or
uv add xai-sdk[telemetry-http]

# For gRPC OTLP export
pip install xai-sdk[telemetry-grpc]
# or
uv add xai-sdk[telemetry-grpc]
```

--------------------------------

### Client.get, Client.delete, Client.content usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/files.md

Example usage of the files client methods: retrieve metadata, stream content, and delete a file.

```python
meta = client.files.get("file_abc")
data = client.files.content("file_abc")
client.files.delete("file_abc")
```

--------------------------------

### Manual polling with `start` and `get`

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Shows the signatures for `start` and `get` and a manual polling loop that submits a video generation request and polls until completion or failure. The loop checks `DeferredStatus.DONE` and `DeferredStatus.FAILED`, printing the video URL or error, and sleeps 1 second between polls.

```python
def start(self, prompt: str, model: Union[VideoGenerationModel, str], *, <same optional params as generate minus timeout/interval>) -> deferred_pb2.StartDeferredResponse
def get(self, request_id: str) -> video_pb2.GetDeferredVideoResponse
```

```python
import time
from xai_sdk import Client
from xai_sdk.proto import deferred_pb2, video_pb2

client = Client()
started = client.video.start("Waves crashing", model="grok-imagine-video")
while True:
    r = client.video.get(started.request_id)
    if r.status == deferred_pb2.DeferredStatus.DONE:
        print(r.response.video.url if r.HasField("response") else "no response")
        break
    if r.status == deferred_pb2.DeferredStatus.FAILED:
        print("failed", r.response.error)
        break
    time.sleep(1)
```

--------------------------------

### Install xAI SDK with uv

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Alternative installation method using the uv package manager. Requires Python 3.10 or higher.

```bash
uv add xai-sdk
```

--------------------------------

### list usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/files.md

Example of listing files with limit, order, sort_by, and filter. Prints file_id and filename for each file in the response.

```python
resp = client.files.list(limit=100, order="desc", sort_by="created_at", filter='content_type = "application/pdf"')
for f in resp.files:
    print(f.file_id, f.filename)
```

--------------------------------

### Full agentic example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/tools.md

A complete example demonstrating how to create a chat with web_search and code_execution tools, append a user message, sample a response, and inspect server-side tool usage.

```APIDOC
## Full agentic example

### Description
A complete example demonstrating how to create a chat with web_search and code_execution tools, append a user message, sample a response, and inspect server-side tool usage.

### Example
```python
from xai_sdk import Client
from xai_sdk.chat import system, tool_result, user
from xai_sdk.tools import code_execution, web_search

client = Client()
chat = client.chat.create(
    model="grok-4.6",
    messages=[system("You are an agentic research assistant.")],
    tools=[web_search(excluded_domains=["ads.example.com"]), code_execution()],
    max_turns=5,
    include=["web_search_call_output"],
)

chat.append(user("What factors drive the USD/EUR rate? Summarize with citations."))
response = chat.sample()
print(response.content)
print(response.server_side_tool_usage)  # e.g. {"WEB_SEARCH": 2}
chat.append(response)
```
```

--------------------------------

### Usage example with web and news sources

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/search.md

Example usage: creates a SearchParameters with web and news sources, mode 'on', and passes it to chat.create with inline citations. Prints response content and citations.

```python
from xai_sdk.chat import SearchParameters, web_source, news_source, user

search = SearchParameters(
    sources=[web_source(country="US", safe_search=True), news_source(country="US")],
    mode="on",
    return_citations=True,
    max_search_results=10,
)

chat = client.chat.create(
    model="grok-4.6",
    messages=[user("What's the latest on AI?")],
    search_parameters=search,
    include=["inline_citations"],
)
response = chat.sample()
print(response.content)
print("citations:", response.citations)
```

--------------------------------

### Install xAI SDK with pip

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Install the xai-sdk package from PyPI using pip. Requires Python 3.10 or higher.

```bash
pip install xai-sdk
```

--------------------------------

### Telemetry with OTLP exporter and custom provider

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/telemetry.md

Example of using Telemetry with a custom TracerProvider and an OTLP exporter. The setup_otlp_exporter call may raise ImportError if the required optional dependency is missing; the example prints an installation hint and re-raises.

```python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource
from xai_sdk.telemetry import Telemetry

telemetry = Telemetry(provider=TracerProvider(resource=Resource.create({"service.name": "my-app"})))
try:
    telemetry.setup_otlp_exporter(endpoint="https://observability.example/traces")
except ImportError as e:
    print("run: pip install 'xai-sdk[telemetry-http]'")
    raise
```

--------------------------------

### Usage example with X source and date range

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/search.md

Example usage: creates a SearchParameters with an X source filtered by handle and minimum view count, and date-bounded between 2025-01-01 and 2025-06-01.

```python
from datetime import datetime, timezone
from xai_sdk.chat import SearchParameters, x_source

# X-focused, date-bounded search across a specific account
search = SearchParameters(
    sources=[x_source(included_x_handles=["xai"], post_view_count=1000)],
    mode="on",
    from_date=datetime(2025, 1, 1, tzinfo=timezone.utc),
    to_date=datetime(2025, 6, 1, tzinfo=timezone.utc),
)
```

--------------------------------

### sample() usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-sync.md

Creates a chat with system and user messages, samples a response, prints content, appends the assistant turn, and continues the conversation.

```python
from xai_sdk.chat import system, user

chat = client.chat.create(model="grok-4.6", messages=[system("You are a pirate.")])
chat.append(user("How are you?"))
response = chat.sample()
print(response.content)
chat.append(response)          # feed the assistant turn back in
chat.append(user("Tell me a joke"))
print(chat.sample().content)
```

--------------------------------

### Batch Usage Example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/batch.md

Example of creating a batch, adding chat and image requests, and iterating over results using the Batch API.

```APIDOC
## Batch Usage Example

### Description
Demonstrates how to create a batch, add requests, and process results.

### Code
```python
from xai_sdk import Client

client = Client()
batch = client.batch.create("batch_1")

# chat + image + video requests in one batch
chat_req = client.chat.create(model="grok-4.6", batch_request_id="q1")
chat_req.append(user("hi"))
img_req = client.image.prepare("sunset", model="grok-imagine-image", batch_request_id="img1")

client.batch.add(batch.batch_id, [chat_req, img_req])

page = client.batch.list_batch_results(batch.batch_id)
for r in page.results:
    if r.is_success:
        if r.response is not None:
            print("chat:", r.response.content)
    else:
        print("error:", r.error_message)
```
```

--------------------------------

### Client.create_public_url and Client.revoke_public_url usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/files.md

Example usage of creating a public URL with an expiry and revoking it.

```python
r = client.files.create_public_url("file_abc", expires_after=86400)
print(r.public_url, r.expires_at)
r2 = client.files.revoke_public_url("file_abc")
print(r2.revoked)
```

--------------------------------

### Full agentic example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/tools.md

Complete example of creating an agentic chat client with web search and code execution tools, appending a user message, sampling a response, and printing the content and server-side tool usage.

```python
from xai_sdk import Client
from xai_sdk.chat import system, tool_result, user
from xai_sdk.tools import code_execution, web_search

client = Client()
chat = client.chat.create(
    model="grok-4.6",
    messages=[system("You are an agentic research assistant.")],
    tools=[web_search(excluded_domains=["ads.example.com"]), code_execution()],
    max_turns=5,
    include=["web_search_call_output"],
)

chat.append(user("What factors drive the USD/EUR rate? Summarize with citations."))
response = chat.sample()
print(response.content)
print(response.server_side_tool_usage)  # e.g. {"WEB_SEARCH": 2}
chat.append(response)
```

--------------------------------

### Create collection example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/collections.md

Example call to `create` that creates a collection named "sec-filings" with a chunk configuration, cosine metric space, and a field definition for a ticker. Demonstrates the expected input format for the method.

```python
client.collections.create(
    name="sec-filings",
    chunk_configuration={
        "chars_configuration": {"max_chunk_size_chars": 1000, "chunk_overlap_chars": 100},
    },
    metric_space="cosine",
    field_definitions=[
        {"key": "ticker", "required": True, "inject_into_chunk": True, "unique": False}
    ],
)
```

--------------------------------

### Sync client: list and get language models

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/models.md

Shows how to use the sync client to list all language models and get one by name. Prints model name and created_time for each, then fetches 'grok-4.6' and prints its name.

```python
from xai_sdk import Client

client = Client()
for m in client.models.list_language_models():
    print(m.name, m.created_time)

model = client.models.get_language_model("grok-4.6")
print(model.name)
```

--------------------------------

### Async Batch Processing Example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/batch.md

Demonstrates how to create a batch, add a chat request to it, and retrieve the results asynchronously using the AsyncClient.

```python
import asyncio
from xai_sdk import AsyncClient
from xai_sdk.chat import user


async def main():
    client = AsyncClient()
    batch = await client.batch.create("aio_batch")
    chat = client.chat.create(model="grok-4.6", batch_request_id="q1")
    chat.append(user("Hello"))
    await client.batch.add(batch.batch_id, [chat])
    results = await client.batch.list_batch_results(batch.batch_id)
    for r in results.succeeded:
        print(r.response.content)
    await client.close()


asyncio.run(main())
```

--------------------------------

### Async chat usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-async.md

Complete async example using `AsyncClient`. Creates a chat with `store_messages=True`, appends a user message, samples a response, stores it, retrieves the stored completion, compacts context, and prints results. Requires `asyncio.run(main())` and closes the client in a `finally` block.

```python
import asyncio
from xai_sdk import AsyncClient
from xai_sdk.chat import system, user


async def main():
    client = AsyncClient()
    try:
        chat = client.chat.create(
            model="grok-4.6",
            messages=[system("You talk like a pirate.")],
            store_messages=True,
        )
        chat.append(user("How are you?"))
        response = await chat.sample()
        chat.append(response)
        print(response.content)

        stored = await client.chat.get_stored_completion(response.id)
        print(stored[0].content == response.content)

        compact = await client.chat.compact_context(
            model="grok-4.3",
            messages=[system("You are helpful."), user("Summarise our chat.")],
        )
        print(compact.dropped_message_count)
    finally:
        await client.close()


asyncio.run(main())
```

--------------------------------

### defer() usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-sync.md

Defers a completion with a 5-minute timeout and prints the response content.

```python
import datetime
response = chat.defer(timeout=datetime.timedelta(minutes=5))
print(response.content)
```

--------------------------------

### Structured output with Pydantic

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-async.md

Example demonstrating how to use the `parse` method to obtain structured output validated by a Pydantic model.

```APIDOC
## Structured output with Pydantic

### Description
Example of using the `parse` method to get structured output validated by a Pydantic model.

### Code Example
```python
from pydantic import BaseModel


class City(BaseModel):
    name: str
    population: int


async def main():
    client = AsyncClient()
    chat = client.chat.create(model="grok-4.6")
    chat.append(user("Name the largest city in Egypt"))
    response, city = await chat.parse(City)
    print(city.name, city.population)
    await client.close()
```
```

--------------------------------

### Response usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-responses.md

Shows how to access response content, usage, cost, branch a conversation using previous_response_id, and save image outputs. Requires store_messages=True for branching.

```python
response = chat.sample()
print(response.content)
print(f"tokens: {response.usage.total_tokens}, cost: {response.cost_usd}")

# Branch a new conversation from a stored response
branch = client.chat.create(
    model="grok-4.6",
    messages=[user("Continue from the stored point")],
    previous_response_id=response.id,  # requires store_messages=True on the original
)

# Save generated images to disk
for i, out in enumerate(response.image_outputs):
    ext = out.mime_type.removeprefix("image/")
    with open(f"out_{i}.{ext}", "wb") as f:
        f.write(out.image)
```

--------------------------------

### Video Generation with Reference Images

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Use reference images to guide the style and content of the generated video by passing 'reference_image_urls' to 'client.video.generate()'.

```python
response = client.video.generate(
    prompt="A person walking through a futuristic city",
    model="grok-imagine-video",
    reference_image_urls=[
        "https://example.com/style-ref1.jpg",
        "https://example.com/style-ref2.jpg",
    ],
    duration=10,
    aspect_ratio="16:9",
)
print(f"Video URL: {response.url}")
```

--------------------------------

### Prepare batch requests with `prepare` and `prepare_extension`

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Shows the `prepare` and `prepare_extension` signatures and a usage example that creates a batch, prepares a video request, and adds it to the batch. These methods build `BatchRequest` protos (`video_request` / `video_extension_request`) for the Batch API.

```python
def prepare(
    self,
    prompt: str,
    model: Union[VideoGenerationModel, str],
    *,
    batch_request_id: Optional[str] = None,
    <image_url, image_file_id, last_frame_url, last_frame_file_id, keyframes, video_url, video_file_id, duration, aspect_ratio, resolution, reference_image_urls, reference_image_file_ids, reference_audios, generate_audio, storage_options — all Optional with default None>,
) -> batch_pb2.BatchRequest

def prepare_extension(
    self,
    prompt: str,
    model: Union[VideoGenerationModel, str],
    video_url: Optional[str] = None,
    *,
    video_file_id: Optional[str] = None,
    batch_request_id: Optional[str] = None,
    duration: Optional[int] = None,
    storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
) -> batch_pb2.BatchRequest
```

```python
batch = client.batch.create("video_batch")
req = client.video.prepare("A timelapse of a sunset", model="grok-imagine-video")
client.batch.add(batch.batch_id, [req])
```

--------------------------------

### Using Client sub-clients (auth, models, tokenize)

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/client.md

Example of using the Client to access sub-clients: auth, models, tokenize. Shows how to create a client, call methods on sub-clients, and close the client.

```python
from xai_sdk import Client

client = Client()
# Every sub-client is reachable as an attribute:
info = client.auth.get_api_key_info()
models = client.models.list_language_models()
tokens = client.tokenize.tokenize_text("hello", model="grok-4.6")
client.close()
```

--------------------------------

### Structured output with Pydantic

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-async.md

Example of structured output using Pydantic. It defines a City model and uses `chat.parse(City)` to get a tuple of response and parsed model, then prints the city name and population.

```python
from pydantic import BaseModel


class City(BaseModel):
    name: str
    population: int


async def main():
    client = AsyncClient()
    chat = client.chat.create(model="grok-4.6")
    chat.append(user("Name the largest city in Egypt"))
    response, city = await chat.parse(City)
    print(city.name, city.population)
    await client.close()
```

--------------------------------

### Extend video with `extend`

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Shows the `extend` signature and a usage example that extends a video from a URL with a prompt and duration. `extend_start` is the same minus `timeout`/`interval` and returns `StartDeferredResponse`. Raises `ValueError("One of video_url or video_file_id must be set for a request.")` when neither is provided; input video must be 2–30 s and chaining is supported by feeding `resp.url` back in.

```python
def extend(
    self,
    prompt: str,
    model: Union[VideoGenerationModel, str],
    video_url: Optional[str] = None,
    *,
    video_file_id: Optional[str] = None,
    duration: Optional[int] = None,
    storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
    timeout: Optional[datetime.timedelta] = None,
    interval: Optional[datetime.timedelta] = None,
) -> VideoResponse
```

```python
resp = client.video.extend(
    prompt="The camera slowly zooms out to reveal the city skyline",
    model="grok-imagine-video",
    video_url="https://example.com/clip.mp4",
    duration=6,
)
# chain: resp2 = client.video.extend(..., video_url=resp.url)
```

--------------------------------

### prepare / prepare_extension

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Builds BatchRequest protos for the Batch API. prepare creates a video_request, and prepare_extension creates a video_extension_request.

```APIDOC
## prepare / prepare_extension

### Description
Builds `BatchRequest` protos for the Batch API. `prepare` creates a `video_request` for video generation, and `prepare_extension` creates a `video_extension_request` for video extension.

### Method
prepare: build video generation batch request
prepare_extension: build video extension batch request

### Signatures
```python
def prepare(
    self,
    prompt: str,
    model: Union[VideoGenerationModel, str],
    *,
    batch_request_id: Optional[str] = None,
    <image_url, image_file_id, last_frame_url, last_frame_file_id, keyframes, video_url, video_file_id, duration, aspect_ratio, resolution, reference_image_urls, reference_image_file_ids, reference_audios, generate_audio, storage_options — all Optional with default None>,
) -> batch_pb2.BatchRequest

def prepare_extension(
    self,
    prompt: str,
    model: Union[VideoGenerationModel, str],
    video_url: Optional[str] = None,
    *,
    video_file_id: Optional[str] = None,
    batch_request_id: Optional[str] = None,
    duration: Optional[int] = None,
    storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
) -> batch_pb2.BatchRequest
```

### Parameters
#### prepare
- **prompt** (str) - Required - The text prompt for video generation.
- **model** (Union[VideoGenerationModel, str]) - Required - The model to use.
- **batch_request_id** (Optional[str]) - Optional - Identifier for the batch request.
- **image_url** (Optional) - Optional - URL of an input image.
- **image_file_id** (Optional) - Optional - File ID of an input image.
- **last_frame_url** (Optional) - Optional - URL of the last frame.
- **last_frame_file_id** (Optional) - Optional - File ID of the last frame.
- **keyframes** (Optional) - Optional - Keyframes for generation.
- **video_url** (Optional) - Optional - URL of an input video.
- **video_file_id** (Optional) - Optional - File ID of an input video.
- **duration** (Optional[int]) - Optional - Desired duration.
- **aspect_ratio** (Optional) - Optional - Aspect ratio of the output.
- **resolution** (Optional) - Optional - Resolution of the output.
- **reference_image_urls** (Optional) - Optional - URLs of reference images.
- **reference_image_file_ids** (Optional) - Optional - File IDs of reference images.
- **reference_audios** (Optional) - Optional - Reference audio inputs.
- **generate_audio** (Optional) - Optional - Whether to generate audio.
- **storage_options** (Optional[Union[StorageOptions, image_pb2.StorageOptions]]) - Optional - Storage options.

#### prepare_extension
- **prompt** (str) - Required - The text prompt for the extension.
- **model** (Union[VideoGenerationModel, str]) - Required - The model to use.
- **video_url** (Optional[str]) - Optional - URL of the input video. Must be set if `video_file_id` is not.
- **video_file_id** (Optional[str]) - Optional - File ID of the input video. Must be set if `video_url` is not.
- **batch_request_id** (Optional[str]) - Optional - Identifier for the batch request.
- **duration** (Optional[int]) - Optional - Desired duration.
- **storage_options** (Optional[Union[StorageOptions, image_pb2.StorageOptions]]) - Optional - Storage options.

### Request Example
```python
batch = client.batch.create("video_batch")
req = client.video.prepare("A timelapse of a sunset", model="grok-imagine-video")
client.batch.add(batch.batch_id, [req])
```

### Response
- **batch_pb2.BatchRequest** - A protobuf representing a batch request containing either a `video_request` or `video_extension_request`.
```

--------------------------------

### Basic and image-to-video generation examples

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/video.md

Shows basic text-to-video generation and image-to-video with pinned first/last frames using grok-imagine-video-1.5. The second call uses storage_options to set the output filename.

```python
from xai_sdk import Client

client = Client()
resp = client.video.generate(
    prompt="A timelapse of a sunset over the ocean",
    model="grok-imagine-video",
)
print(resp.url, resp.duration, resp.cost_usd)

# image → video with first/last pinned frames
resp = client.video.generate(
    prompt="The camera dollies from the doorway to the window",
    model="grok-imagine-video-1.5",
    image_url="https://example.com/first.jpg",
    last_frame_url="https://example.com/last.jpg",
    duration=8,
    storage_options={"filename": "clip.mp4"},
)
print(resp.public_url or resp.url)
```

--------------------------------

### Search collections example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/collections.md

Example call to `search` that queries across collections with a hybrid retrieval mode and prints the document name and score for each result.

```python
results = client.collections.search(
    query="What was Q3 revenue?",
    collection_ids=["col_1"],
    limit=5,
    instructions="Focus on latest filings.",
    retrieval_mode="hybrid",
)
for doc in results.documents:
    print(doc.file_metadata.name, doc.score)
```

--------------------------------

### Documents CRUD

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/collections.md

Methods for managing documents within a collection: add existing, list, get, batch get, remove, update, reindex, and generate description.

```APIDOC
## Documents CRUD

### Description
Provides CRUD operations for documents within a collection, including adding existing files, listing, retrieving, updating, removing, reindexing, and generating descriptions.

### Methods

#### add_existing_document
```python
def add_existing_document(self, collection_id: str, file_id: str, fields: Optional[dict[str, str]] = None) -> None
```
Adds an existing file to a collection.

#### list_documents
```python
def list_documents(
    self,
    collection_id: str,
    limit: Optional[int] = None,
    order: Optional[Union[Order, "shared_pb2.Ordering"]] = None,
    sort_by: Optional[Union[DocumentSortBy, "collections_pb2.DocumentsSortBy"]] = None,
    pagination_token: Optional[str] = None,
    filter: Optional[str] = None,  # noqa: A002
) -> collections_pb2.ListDocumentsResponse
```
Lists documents in a collection with optional filtering, sorting, and pagination. The `filter` supports file metadata and document fields, e.g. `'status:DOCUMENT_STATUS_PROCESSED'`, `'fields.isbn:"978-1-234567-89-0"'`.

#### get_document
```python
def get_document(self, file_id: str, collection_id: str) -> collections_pb2.DocumentMetadata
```
Retrieves metadata for a single document.

#### batch_get_documents
```python
def batch_get_documents(self, collection_id: str, file_ids: Sequence[str]) -> collections_pb2.BatchGetDocumentsResponse
```
Retrieves metadata for multiple documents in a collection.

#### remove_document
```python
def remove_document(self, collection_id: str, file_id: str) -> None
```
Removes a document from a collection.

#### update_document
```python
def update_document(
    self,
    collection_id: str,
    file_id: str,
    name: Optional[str] = None,
    data: Optional[bytes] = None,
    content_type: Optional[str] = None,
    fields: Optional[dict[str, str]] = None,
) -> collections_pb2.DocumentMetadata
```
Updates a document's metadata or content.

#### reindex_document
```python
def reindex_document(self, collection_id: str, file_id: str) -> None
```
Reindexes a document in the collection.

#### generate_description
```python
def generate_description(self, collection_id: str) -> str
```
Generates an LLM-generated description for the collection. Returns the description string (empty if generation failed or no processed files).

### Examples
```python
import datetime
from xai_sdk import Client

client = Client()  # constructed with management_api_key for collections mgmt

try:
    collection = client.collections.create("my-books")
    client.collections.upload_document(
        collection.collection_id, "chapter1.txt", data=b"Once upon a time...",
        wait_for_indexing=True, timeout=datetime.timedelta(minutes=3),
    )
    results = client.collections.search("fairytale", [collection.collection_id])
    client.collections.update(collection.collection_id, description="Updated description")
    client.collections.delete(collection.collection_id)
except ValueError as e:  # e.g. missing management key, invalid chunk config, indexing failure
    print(f"collections error: {e}")
    raise
```

```python
import asyncio
from xai_sdk import AsyncClient


async def main():
    client = AsyncClient()  # management_api_key must be provided
    col = await client.collections.create(
        "legal-rules",
        chunk_configuration={
            "tokens_configuration": {"max_chunk_size_tokens": 200, "chunk_overlap_tokens": 20, "encoding_name": "cl100k"}
        },
    )
    await client.collections.add_existing_document(col.collection_id, "file_pdf_1")
    docs = await client.collections.list_documents(col.collection_id, limit=50)
    print(len(docs.documents))
    await client.close()


asyncio.run(main())
```
```

--------------------------------

### batch_upload usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/files.md

Example of calling batch_upload with a list of filenames and batch_size=10. The result dict maps input index to File or BaseException; iterate to handle failures.

```python
results = client.files.batch_upload(["a.pdf", "b.pdf", "c.pdf"], batch_size=10)
ok = {i: f for i, f in results.items() if not isinstance(f, BaseException)}
for i, exc in results.items():
    if isinstance(exc, BaseException):
        print(f"failed {i}: {exc}")
```

--------------------------------

### Check installed version with pip show xai-sdk

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Use this command in your terminal to display detailed package information, including the version number, for the xAI SDK installed via pip.

```bash
pip show xai-sdk
```

--------------------------------

### Tokenize text with sync client

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/models.md

Creates a sync Client, tokenizes 'Hello world' with model 'grok-4.6', and prints token details. The tokenizer is accessed via client.tokenize.

```python
from xai_sdk import Client

client = Client()
tokens = client.tokenize.tokenize_text("Hello world", model="grok-4.6")
for t in tokens:
    print(t.token_id, t.string_token, t.token_bytes)
```

--------------------------------

### Check installed version with uv pip show xai-sdk

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Use this command in your terminal to display detailed package information, including the version number, for the xAI SDK installed via uv.

```bash
uv pip show xai-sdk
```

--------------------------------

### prepare() - Build batch request for image generation

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/image.md

Builds a batch_pb2.BatchRequest for later submission via client.batch.add(). Does not execute generation. Only available on the sync client; the async client inherits the same synchronous prepare().

```python
def prepare(
    self,
    prompt: str,
    model: Union[ImageGenerationModel, str],
    *,
    batch_request_id: Optional[str] = None,
    image_url: Optional[str] = None,
    image_file_id: Optional[str] = None,
    image_urls: Optional[Sequence[str]] = None,
    image_file_ids: Optional[Sequence[str]] = None,
    user: Optional[str] = None,
    image_format: Optional[ImageFormat] = None,
    aspect_ratio: Optional[ImageAspectRatio] = None,
    resolution: Optional[ImageResolution] = None,
    quality: Optional[ImageQuality] = None,
    storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
) -> batch_pb2.BatchRequest
```

--------------------------------

### get

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/batch.md

Retrieves a batch by its ID.

```APIDOC
## get

### Description
Retrieves a batch by its ID.

### Method
get

### Parameters
- **batch_id** (str) - Required - ID of the batch.

### Response
Returns a `batch_pb2.Batch` object.
```

--------------------------------

### Synchronous image generation and editing with Client

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/image.md

Shows how to generate an image with Client.image.sample, print metadata, and save the image. Also demonstrates editing an existing image by file ID with Files-API persistence using storage_options.

```python
from xai_sdk import Client

client = Client()
image = client.image.sample(
    prompt="A sunset over mountains",
    model="grok-imagine-image",
    aspect_ratio="16:9",
    image_format="base64",
)
print(image.model, image.cost_usd, image.respect_moderation)
with open("out.jpg", "wb") as f:
    f.write(image.image)

# Image editing from a file ID with Files-API persistence
from xai_sdk import Client

client = Client()
edited = client.image.sample(
    prompt="Make it snow",
    model="grok-imagine-image-2.0",
    image_file_id="file_abc",
    storage_options={"filename": "snow.png", "public_url": True},
)
print(edited.public_url)
```

--------------------------------

### Async client: list embedding and get image generation models

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/models.md

Shows async usage: lists embedding models and gets an image generation model by name, then closes the client. Requires asyncio and AsyncClient.

```python
import asyncio
from xai_sdk import AsyncClient


async def main():
    client = AsyncClient()
    emb = await client.models.list_embedding_models()
    for m in emb:
        print(m.name)
    img = await client.models.get_image_generation_model("grok-imagine-image")
    print(img.name)
    await client.close()


asyncio.run(main())
```

--------------------------------

### sample() method signature

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-sync.md

Defines the sample method that calls GetCompletion RPC. Returns a Response object.

```python
def sample(self) -> Response
```

--------------------------------

### web_search usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/tools.md

Shows how to create a web_search tool with excluded domains, image understanding enabled, and user location set. The resulting tool is passed to the tools argument of chat.create(...).

```python
from xai_sdk.tools import web_search

tool = web_search(
    excluded_domains=["spam-site.com"],
    enable_image_understanding=True,
    user_location_country="US",
    user_location_city="San Francisco",
    user_location_timezone="America/Los_Angeles",
)
```

--------------------------------

### image_generation usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/tools.md

Example of using the image_generation tool with a chat client. Creates a chat with model 'grok-4.6', a user message 'Draw a cat', and the image_generation tool. Samples a response and prints mime_type and image_uuid for each image output.

```python
from xai_sdk.tools import image_generation

chat = client.chat.create(
    model="grok-4.6",
    messages=[user("Draw a cat")],
    tools=[image_generation()],
)
response = chat.sample()
for out in response.image_outputs:
    print(out.mime_type, out.image_uuid)
```

--------------------------------

### list, get, update, delete method signatures

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/collections.md

Signatures for the `list`, `get`, `update`, and `delete` methods. `list` supports filtering and pagination; `update` raises `ValueError` if no update fields are provided; field-definition updates use operation objects.

```python
def list(
    self,
    limit: Optional[int] = None,
    order: Optional[Union[Order, "shared_pb2.Ordering"]] = None,
    sort_by: Optional[Union[CollectionSortBy, "collections_pb2.CollectionsSortBy"]] = None,
    filter: Optional[str] = None,  # noqa: A002
    pagination_token: Optional[str] = None,
) -> collections_pb2.ListCollectionsResponse

def get(self, collection_id: str) -> collections_pb2.CollectionMetadata

def update(
    self,
    collection_id: str,
    name: Optional[str] = None,
    chunk_configuration: Optional[Union[ChunkConfiguration, types_pb2.ChunkConfiguration]] = None,
    field_definitions: Optional[Sequence[Union[FieldDefinitionUpdate, collections_pb2.FieldDefinitionUpdate]]] = None,
    description: Optional[str] = None,
) -> collections_pb2.CollectionMetadata

def delete(self, collection_id: str) -> None
```

--------------------------------

### Create and list batch results

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/batch.md

Demonstrates creating a batch with mixed request types and iterating through the results.

```python
from xai_sdk import Client

client = Client()
batch = client.batch.create("batch_1")

# chat + image + video requests in one batch
chat_req = client.chat.create(model="grok-4.6", batch_request_id="q1")
chat_req.append(user("hi"))
img_req = client.image.prepare("sunset", model="grok-imagine-image", batch_request_id="img1")

client.batch.add(batch.batch_id, [chat_req, img_req])

page = client.batch.list_batch_results(batch.batch_id)
for r in page.results:
    if r.is_success:
        if r.response is not None:
            print("chat:", r.response.content)
    else:
        print("error:", r.error_message)
```

--------------------------------

### get

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/collections.md

Retrieves metadata for a specific collection by ID.

```APIDOC
## get

### Description
Retrieves metadata for a specific collection by its ID.

### Method
get

### Parameters
- **collection_id** (str) - Required - The ID of the collection.

### Response
Returns `collections_pb2.CollectionMetadata`.
```

--------------------------------

### Instantiate synchronous and asynchronous clients

Source: https://github.com/xai-org/xai-sdk-python/blob/main/README.md

Creates Client and AsyncClient instances using the XAI_API_KEY environment variable by default. No explicit API key needed if the variable is set.

```python
from xai_sdk import Client, AsyncClient

# Synchronous client
sync_client = Client()

# Asynchronous client
async_client = AsyncClient()
```

--------------------------------

### Compact/continue pattern

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-responses.md

Example usage of the compact/continue pattern with the chat API.

```APIDOC
## Compact/continue pattern

### Description
Demonstrates how to compact a chat context and continue the conversation using the compacted context.

### Example
```python
chat = client.chat.create(model="grok-4.6", messages=[system("You are helpful.")])
chat.append(user("Hello!"))
chat.append(chat.sample())

compacted = chat.compact()          # RPC + replaces messages with the compacted context
print(f"Dropped {compacted.dropped_message_count} messages")
chat.append(user("What did we discuss?"))  # continues over the compacted context
print(chat.sample().content)

# Or without mutating a chat: compact an arbitrary history
from xai_sdk.chat import user as u, system as s
compact = client.chat.compact_context(
    model="grok-4.3",
    messages=[s("You are helpful."), u("Summarise our chat.")],
)
print(compact.encrypted_content)
```
```

--------------------------------

### sample() - Generate a single image

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/image.md

Generates one image via the GenerateImage RPC. The async client defines async def sample(...) with the same signature. The span is 'image.sample <model>'.

```python
def sample(
    self,
    prompt: str,
    model: Union[ImageGenerationModel, str],
    *,
    image_url: Optional[str] = None,
    image_file_id: Optional[str] = None,
    image_urls: Optional[Sequence[str]] = None,
    image_file_ids: Optional[Sequence[str]] = None,
    user: Optional[str] = None,
    image_format: Optional[ImageFormat] = None,
    aspect_ratio: Optional[ImageAspectRatio] = None,
    resolution: Optional[ImageResolution] = None,
    quality: Optional[ImageQuality] = None,
    storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
) -> "ImageResponse"
```

--------------------------------

### sample_batch() usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-sync.md

Uses sample_batch with a PendingDeprecationWarning suppressed, then prints each option.

```python
import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore", PendingDeprecationWarning)
    options = chat.sample_batch(3)
for i, r in enumerate(options):
    print(f"Option {i+1}: {r.content}")
```

--------------------------------

### stream() usage example

Source: https://github.com/xai-org/xai-sdk-python/blob/main/_autodocs/api-reference/chat-sync.md

Streams a response, printing chunks as they arrive and then the fully accumulated content.

```python
chat.append(user("Tell me a story"))
for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)
print()
print(response.content)  # fully accumulated
```
Tokens:
Raw