xai-sdk

Added

• xhigh Reasoning Effort: Added "xhigh" as an accepted reasoning_effort value (maps to EFFORT_XHIGH; supported by models such as grok-4.6)
• Added grok-4.6 to the ChatModel known-model type literal

Added

• Service Tier: Added service_tier parameter to chat.create() for requesting priority processing ("default" or "priority") at a higher token price. Responses expose a service_tier property indicating which tier was actually used

Added

• Imagine File Storage: Image and video generation (sync and async) now accept a storage_options parameter to persist generated assets to the Files API. It takes a dict with a required filename and optional expires_after (an int in seconds or a datetime.timedelta) and public_url (True to create a public URL with default expiry, or {"expires_after": <seconds>} for an independent URL expiry). Image and video responses expose new file_output, storage_error, public_url, and public_url_error properties.
• File-ID Inputs for Generation: Image and video generation now accept Files API file_id references as inputs alongside URLs/base64 — image_file_id / image_file_ids for image.sample() / image.sample_batch(), and image_file_id / video_file_id / reference_image_file_ids for video.generate() / video.extend() (and the batch prepare helpers). URL and file-ID lists may be mixed in the same multi-image request (file IDs are sent first).
• Public File URLs: Added client.files.create_public_url() and client.files.revoke_public_url() (sync and async) to create and revoke publicly shareable, unauthenticated URLs for stored files. create_public_url() accepts an optional expires_after (an int in seconds or a datetime.timedelta).
• Files List Filter: client.files.list() (sync and async) now accepts an optional filter parameter to narrow results server-side by fields such as content_type, size_bytes, created_at, upload_status, and public_url (e.g. filter='public_url != null').
• Added grok-imagine-image-quality to the ImageGenerationModel known-model type literal and grok-imagine-video-1.5-preview to the VideoGenerationModel known-model type literal

Added

• Context Compaction: Added chat.compact_context() (sync and async) to compact a conversation into an opaque encrypted_content representation that can be reused in follow-up requests without sending the full message history. Chat objects also expose compact(), which runs compaction on the current conversation and appends the result. The returned CompactContextResponse includes encrypted_content, dropped_message_count, and usage.
• Added grok-build-0.1 to the ChatModel known-model type literal

Added

• Image Search: Added enable_image_search parameter to web_search() to return image results that can be embedded in responses

Added

• Reasoning Effort: Added "none" and "medium" as accepted reasoning_effort values (maps to EFFORT_NONE and EFFORT_MEDIUM)

Added

• Added grok-4.3 and grok-4.3-latest to the ChatModel known-model type literal

Added

• Cost Tracking: Responses from chat.sample() / chat.stream(), image.sample() / image.sample_batch(), and video.generate() / video.extend() now expose a cost_usd property that returns the per-request cost in USD (or None when the server does not report cost)
• Files API: client.files.upload() (sync and async) now accepts an optional expires_after parameter to set a TTL on uploaded files. Accepts either an int (seconds) or a datetime.timedelta. After the duration elapses, the file is automatically deleted.
• Collections API Enhancements:
  • Added description parameter to collections.create() and collections.update() for human-friendly collection descriptions
  • Added collections.generate_description() method that asks the API to summarize a collection based on its document contents
  • Added field_definitions parameter to collections.update() for adding or deleting field definitions on existing collections. Each entry is either an add ({"field_definition": {...}, "operation": "add"}) or a delete ({"key": "...", "operation": "delete"}); typed via FieldDefinitionAdd / FieldDefinitionDelete (re-exported as the union FieldDefinitionUpdate)
  • Added BytesConfiguration as a third chunking strategy (alongside chars_configuration and tokens_configuration) on ChunkConfiguration
  • Added filter parameter to collections.list_documents() for filtering on file metadata and document fields (e.g., 'status:DOCUMENT_STATUS_PROCESSED', 'fields.isbn:"978-1-234567-89-0"')
  • wait_for_indexing polling now treats the new DOCUMENT_STATUS_CHUNKED, DOCUMENT_STATUS_EMBEDDING, and DOCUMENT_STATUS_WRITING statuses as in-progress instead of unknown
• Telemetry Improvements:
  • Added tracing span around collections.reindex_document
  • Added collection.id and file.id span attributes to delete_collection, add_existing_document, remove_document, reindex_document, and generate_description
  • Added cost_in_usd_ticks to telemetry span attributes for chat, image, and video responses

Changed

• Breaking Change: chunk_configuration validation is now stricter. When chunk_configuration is provided, it must specify exactly one of chars_configuration, tokens_configuration, or bytes_configuration. Previously, calls that omitted all three (e.g., to update only strip_whitespace) silently succeeded; they now raise ValueError. Callers updating only top-level chunk flags must now also include their existing chunking strategy.

Removed

• Breaking Change: Removed the team_id field from File responses returned by the Files API (upload, list, get). The same value is available via client.auth.get_api_key_info().team_id, which is the canonical source.

Added

• Inline File Attachments: chat.file() now supports inline file data via a new data parameter (with optional filename and mime_type), in addition to the existing file_id mode
• URL File Attachments: chat.file() now supports public URL file references via a new url parameter (with optional filename and mime_type)

Added

• Video Extension API: Added extend() and extend_start() methods to sync and async video clients for extending existing videos with a text prompt
• Reference-to-Video Generation: Added reference_image_urls parameter to video.generate(), video.start(), and video.prepare() for reference-image-based video generation (R2V)

Changed

• Model Literals: Updated grok-4.20 model variants from beta to GA naming convention (e.g., grok-4.20, grok-4.20-0309, grok-4.20-multi-agent)

Added

• Image/Video Batch Support: Added image.prepare() and video.prepare() methods to create batch requests for image and video generation
• Batch API Enhancement: Added input_file_id parameter to batch.create() for creating batches from uploaded JSONL files
• Batch Result Properties: Added image_response and video_response properties on BatchResult for typed access to image and video batch results
• Model Type Signatures: Image and video client methods now accept Union[ImageGenerationModel, str] / Union[VideoGenerationModel, str] for model parameters, enabling IDE autocomplete

Fixed

• Polling Robustness: Unknown deferred statuses in video and collections polling loops now emit a warning and continue polling instead of raising ValueError
• Timeout Error Messages: PollTimer now accepts an optional context parameter for more descriptive TimeoutError messages

Fixed

• Video Generation Error Handling: Video generation polling now raises a VideoGenerationError (with code and message attributes) when the API reports a generation failure, instead of returning an incomplete response

Changed

• Model Literals: Updated grok-4.20 model variants from experimental-beta to beta naming convention (e.g., grok-4.20-beta, grok-4.20-beta-0309, grok-4.20-multi-agent-beta-0309)

Added

• Multi-Agent Chat: Added agent_count parameter to chat.create() for configuring the number of agents (4 or 16) when using multi-agent models
• Model Literals:
  • Added grok-4.20-experimental-beta and grok-4.20-multi-agent-experimental-beta model variants to ChatModel
  • Added grok-imagine-image-pro to ImageGenerationModel

Removed

• Deprecated Models: Removed grok-2-image model variants from ImageGenerationModel

Added

• Multi-Reference Image Editing: Added image_urls parameter to image.sample() and image.sample_batch() for multi-reference image editing with mutual exclusivity enforcement against image_url
• 2K Image Resolution: Added "2k" option to ImageResolution for higher resolution image generation

Changed

• Video Polling Defaults: Reduced default PollTimer poll interval from 100ms to 1s and introduced DEFAULT_VIDEO_POLL_INTERVAL and DEFAULT_VIDEO_TIMEOUT constants for video clients

Deprecated

• Image Prompt: BaseImageResponse.prompt now returns an empty string and emits a DeprecationWarning after the up_sampled_prompt field was removed from the GeneratedImage proto

Added

• Video Generation API: Added new client.video sub-client (sync and async) for video generation, supporting text-to-video and image-to-video with configurable aspect_ratio, resolution, and duration
• Image Generation Enhancements:
  • Added image_url parameter to image.sample() and image.sample_batch() for using a reference image as a starting point for generation
  • Added aspect_ratio parameter for controlling image aspect ratios (e.g., "1:1", "16:9", "9:16")
  • Added resolution parameter for controlling image resolution ("1k")
• Type Aliases: Added ImageAspectRatio, ImageFormat, ImageResolution, VideoAspectRatio, VideoResolution, and VideoGenerationModel type aliases
• Model Literals: Added grok-imagine-image to ImageGenerationModel and grok-imagine-video as VideoGenerationModel

Added

• Batch API: Added new client.batch sub-client for interacting with the Batch API:
  • Ability to create, manage, and retrieve batch jobs
  • Integration with existing chat objects when adding requests to a batch
  • New optional batch_request_id field in chat.create method
• Developer Role: Added developer role support for chat messages with developer() utility function
• Tool Call ID Field: Added tool_call_id field and argument to tool_result utility function for explicit tool call identification
• User Location for Web Search: Added user-location support to web_search() server-side tool with new location-related arguments

Changed

• Telemetry Improvements:
  • Updated chat spans to be compliant with latest OpenTelemetry gen_ai semantic conventions
  • Now emits xai under gen_ai.provider.name field instead of gen_ai.system
  • Added server.address attribute set to api.x.ai
  • Added instrumentation for Files API methods (upload, delete)
  • Added instrumentation for Collections API methods (create, update, delete, upload_document, add_existing_document, remove_document, update_document)

Added

• Server-Side Tool Output Utilities: Added utility functions to retrieve server-side tool call outputs from responses
• Collections API Enhancements:
  • Added field_definitions parameter to collections.create() enabling custom document metadata schemas with validation constraints (required, unique, inject_into_chunk)
  • Added metric_space parameter to collections.create() supporting HNSW distance metrics (cosine, euclidean, inner_product)
  • Added filter parameter to collections.list() with support for filtering by collection_name, created_at, and documents_count
  • Added wait_for_indexing parameter to document upload with customizable poll_interval and timeout
  • Added instructions and retrieval_mode parameters to collections.search()
  • Implemented dict-based TypedDict interfaces as ergonomic alternatives to protobuf objects
• Inline Citations: Added property methods for convenient access to inline citations on responses for both streaming and unary responses
  • Added end_index field for InlineCitation
• Verbose Streaming: Added verbose_streaming to include options for streaming responses

Changed

• Renamed built-in document search tool to "attachment search" for clarity
• Collections upload_document now streams bytes via the Files UploadFile endpoint, then attaches the resulting file to the collection

Removed

• Breaking Change: The content_type parameter was removed from the public collections.upload_document function

Added

• Tool Call Status Tracking: Added status field to tool call entries in chat response outputs for tracking tool execution progress
  • Tool call messages now include a status field indicating the current state of the tool call
  • Multiple entries for the same tool call can now represent different stages (in progress, success, failure)
  • Enables real-time tracking of server-side tool execution lifecycle
• Batch File Upload: Added batch_upload method to both sync and async file clients for concurrent uploads of multiple files with progress tracking
• Max Turns Parameter: Added max_turns parameter to chat.create for configuring the maximum number of agentic turns when using server-side tools
• Include Field: Added include field to chat requests allowing users to specify optional outputs to be returned (e.g., tool output, inline citations)
• Inline Citations: Added InlineCitation support for agentic search outputs
• Model Literals: Introduced Model literals for type-safe model specification and editor autocomplete support

Changed

• Reorganized existing literals into the types folder for better organization
• Updated gRPC metadata to include the language (Python) alongside SDK version

Added

• Files API: Added support for the Files API with new client.files sub-client for uploading and managing files
• Remote MCP Tools: Added support for remote MCP (Model Context Protocol) tool integration, enabling connection to external MCP servers
• Collections Search Tool: Added collections-search as a server-side tool with proto support and convenience utility functions
• Structured Outputs Enhancement: Allow passing a Pydantic BaseModel directly to response_format parameter in chat.create for type-safe structured outputs
• Client Resource Management: Added context manager support and explicit close() methods to Client and AsyncClient for proper gRPC channel cleanup
• Chat Response Features:
  • Added support for encrypted content in chat responses
  • Added debug output support in chat responses
• Tool Enhancements:
  • Added SERVER_SIDE_TOOL_MCP and SERVER_SIDE_TOOL_COLLECTIONS_SEARCH to ServerSideTool usage enum
  • Added ToolCallType support in ToolCall for distinguishing between client-side and server-side tools
  • Added utility function get_tool_call_type() for retrieving tool call types
  • Added new examples for MCP and collections search server-side tools
• Client Configuration:
  • Added option to use an insecure gRPC channel via insecure parameter (useful for local development)
  • Added xai-sdk-version metadata header to all gRPC requests for better debugging and analytics
• Telemetry Controls: Added ability to exclude sensitive attributes from telemetry spans/traces via the XAI_SDK_DISABLE_SENSITIVE_TELEMETRY_ATTRIBUTES environment variable

Changed

• Optimized streaming chat response memory usage with lazy buffering
• Renamed internal ChoiceChunk class to CompletionOutputChunk
• Improved agentic response handling to append all output entries correctly
• Set index correctly in parse method for chat responses

Fixed

• Removed double await in UnaryStreamAioInterceptor

Fixed

• Fixed handling of multi-output responses in agentic workflows (server-side tools). When server-side tools are used, the API returns multiple completion outputs in a single response (tool call → tool result → final answer). This release ensures:
  • response.tool_calls now correctly returns ALL tool calls from all assistant outputs in the response, not just those from a single output index
  • response.content properly aggregates and returns the final assistant response content
  • Streaming chunks correctly expose all assistant outputs during agentic multi-turn conversations
  • All outputs are properly tracked and indexed, preventing missing tool calls or incomplete responses

Added

• Added proto support for three new server-side tools in agentic workflows:
  • web_search(): Enables web search with configurable domain filtering (exclude/allow lists) and image understanding capabilities
  • x_search(): Enables X (Twitter) search with date range filtering, handle-based filtering (include/exclude), and both image and video understanding
  • code_execution(): Enables server-side code execution for computational tasks
• Added convenience functions in new xai_sdk.tools module for easily creating server-side tool configurations
• Added ServerSideTool enum in usage proto for tracking server-side tool usage (WEB_SEARCH, X_SEARCH, CODE_EXECUTION, VIEW_IMAGE, VIEW_X_VIDEO)
• Added server_side_tools_used field to SamplingUsage for detailed usage tracking of which server-side tools were invoked

Changed

• Breaking Proto Change: Renamed response structure fields for semantic clarity and better multi-output support:
  • GetChatCompletionResponse.choices → GetChatCompletionResponse.outputs
  • GetChatCompletionChunk.choices → GetChatCompletionChunk.outputs
  • Choice message type → CompletionOutput
  • ChoiceChunk message type → CompletionOutputChunk
  • This change better reflects the API's capability to return multiple completion outputs rather than "choices," providing clearer semantics for the response structure

Added

• Added support for the new collections API
• Added a new collections sub-client to Client and AsyncClient which can be used to interact with the collections API.
• The Client and AsyncClient objects now accept an optional management_api_key parameter which can be used to authenticate requests to the management API (e.g. CRUD operations on collections). Alternatively, the XAI_MANAGEMENT_API_KEY environment variable can be used to set this value without having to pass it as a parameter.
• Added support for the new stateful chat API
• Added two new parameters to the chat.create method:
  • store_messages whether to persist messages on xAI servers such that they can be referenced and retrieved later.
  • previous_response_id allows you to specify the ID of a previously stored response to use as the starting point for the new chat.
• Added two new methods to the chat object:
  • get_stored_completion allows you to retrieve a previously stored response by its ID.
  • delete_stored_completion allows you to delete a previously stored response by its ID.

Removed

• Breaking Change: Removed the documents sub-client from Client and AsyncClient. In order to search for documents within collections, use the client.collections.search method instead.

Added

• Added OpenTelemetry integration for distributed tracing and monitoring of SDK operations
• Instrumented all methods that make gRPC requests to produce spans with relevant request/response attributes closely adhering to the OpenTelemetry GenAI Semantic Conventions.
• Added a new telemetry module (xai_sdk.telemetry) which can be used to setup trace creation and exporting of traces to an otel backend or to the console
• Added a new documents sub-client to Client and AsyncClient which can be used to interact with the documents API.
• Added a new search method on the documents sub-client which can be used to perform semantic search for documents that are stored in collections.

Fixed

• Fixed a bug that caused the from_date and to_date parameters to have no effect when using them via SearchParameters for the live search feature

Added

• Added support for new parameters to the x_source (from xai_sdk.search import x_source) for use with the live search API feature:
  • included_x_handles allows you to limit posts used to those only authored by particular handles
  • excluded_x_handles allows you to exclude posts authored by particular handles
  • post_favorite_count allows you to set a threshold for the minimum number of favorites a post must have to be considered
  • post_view_count allows you to set a threshold for the minimum number of views a post must have to be considered

Fixed

• Fixed an issue where long running gRPC requests would prematurely terminate.

Added

• Initial RC version of the xai-sdk