xai-sdk-python
Mon
Wed
Fri
JulAugSepOctNovDecJanFebMarAprMayJunJul
LessMore
Releases14Avg4/moVersionsv1.8.1 to v1.17.0
Last Checked
3h ago
Latest
v1.17.0
Source
@xai-org/xai-sdk-pythonstorage_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 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).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).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').enable_image_search parameter to web_search() to return image results that can be embedded in responsesvideo.prepare_extension() to sync and async clients for preparing video extension requests for the Batch APIchat.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)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.description parameter to collections.create() and collections.update() for human-friendly collection descriptionscollections.generate_description() method that asks the API to summarize a collection based on its document contentsfield_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)BytesConfiguration as a third chunking strategy (alongside chars_configuration and tokens_configuration) on ChunkConfigurationfilter 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 unknowncollections.reindex_documentcollection.id and file.id span attributes to delete_collection, add_existing_document, remove_document, reindex_document, and generate_descriptioncost_in_usd_ticks to telemetry span attributes for chat, image, and video responseschunk_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.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.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 modechat.file() now supports public URL file references via a new url parameter (with optional filename and mime_type)extend() and extend_start() methods to sync and async video clients for extending existing videos with a text promptreference_image_urls parameter to video.generate(), video.start(), and video.prepare() for reference-image-based video generation (R2V)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)image.prepare() and video.prepare() methods to create batch requests for image and video generationinput_file_id parameter to batch.create() for creating batches from uploaded JSONL filesimage_response and video_response properties on BatchResult for typed access to image and video batch resultsUnion[ImageGenerationModel, str] / Union[VideoGenerationModel, str] for model parameters, enabling IDE autocompleteValueErrorPollTimer now accepts an optional context parameter for more descriptive TimeoutError messagesVideoGenerationError (with code and message attributes) when the API reports a generation failure, instead of returning an incomplete responsegrok-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)agent_count parameter to chat.create() for configuring the number of agents (4 or 16) when using multi-agent modelsgrok-4.20-experimental-beta and grok-4.20-multi-agent-experimental-beta model variants to ChatModelgrok-imagine-image-pro to ImageGenerationModelgrok-2-image model variants from ImageGenerationModelimage_urls parameter to image.sample() and image.sample_batch() for multi-reference image editing with mutual exclusivity enforcement against image_url"2k" option to ImageResolution for higher resolution image generationPollTimer poll interval from 100ms to 1s and introduced DEFAULT_VIDEO_POLL_INTERVAL and DEFAULT_VIDEO_TIMEOUT constants for video clientsBaseImageResponse.prompt now returns an empty string and emits a DeprecationWarning after the up_sampled_prompt field was removed from the GeneratedImage protoclient.video sub-client (sync and async) for video generation, supporting text-to-video and image-to-video with configurable aspect_ratio, resolution, and durationimage_url parameter to image.sample() and image.sample_batch() for using a reference image as a starting point for generationaspect_ratio parameter for controlling image aspect ratios (e.g., "1:1", "16:9", "9:16")resolution parameter for controlling image resolution ("1k")ImageAspectRatio, ImageFormat, ImageResolution, VideoAspectRatio, VideoResolution, and VideoGenerationModel type aliasesgrok-imagine-image to ImageGenerationModel and grok-imagine-video as VideoGenerationModelclient.batch sub-client for interacting with the Batch API:
batch_request_id field in chat.create methoddeveloper role support for chat messages with developer() utility functiontool_call_id field and argument to tool_result utility function for explicit tool call identificationweb_search() server-side tool with new location-related argumentsgen_ai semantic conventionsxai under gen_ai.provider.name field instead of gen_ai.systemserver.address attribute set to api.x.aiupload, delete)create, update, delete, upload_document, add_existing_document, remove_document, update_document)field_definitions parameter to collections.create() enabling custom document metadata schemas with validation constraints (required, unique, inject_into_chunk)metric_space parameter to collections.create() supporting HNSW distance metrics (cosine, euclidean, inner_product)filter parameter to collections.list() with support for filtering by collection_name, created_at, and documents_countwait_for_indexing parameter to document upload with customizable poll_interval and timeoutinstructions and retrieval_mode parameters to collections.search()TypedDict interfaces as ergonomic alternatives to protobuf objectsend_index field for InlineCitationverbose_streaming to include options for streaming responsesupload_document now streams bytes via the Files UploadFile endpoint, then attaches the resulting file to the collectioncontent_type parameter was removed from the public collections.upload_document functionbatch_upload method to both sync and async file clients for concurrent uploads of multiple files with progress trackingmax_turns parameter to chat.create for configuring the maximum number of agentic turns when using server-side toolsinclude field to chat requests allowing users to specify optional outputs to be returned (e.g., tool output, inline citations)InlineCitation support for agentic search outputsModel literals for type-safe model specification and editor autocomplete supporttypes folder for better organizationclient.files sub-client for uploading and managing filesBaseModel directly to response_format parameter in chat.create for type-safe structured outputsclose() methods to Client and AsyncClient for proper gRPC channel cleanupSERVER_SIDE_TOOL_MCP and SERVER_SIDE_TOOL_COLLECTIONS_SEARCH to ServerSideTool usage enumToolCallType support in ToolCall for distinguishing between client-side and server-side toolsget_tool_call_type() for retrieving tool call typesinsecure parameter (useful for local development)xai-sdk-version metadata header to all gRPC requests for better debugging and analyticsXAI_SDK_DISABLE_SENSITIVE_TELEMETRY_ATTRIBUTES environment variableChoiceChunk class to CompletionOutputChunkparse method for chat responsesUnaryStreamAioInterceptorresponse.tool_calls now correctly returns ALL tool calls from all assistant outputs in the response, not just those from a single output indexresponse.content properly aggregates and returns the final assistant response contentweb_search(): Enables web search with configurable domain filtering (exclude/allow lists) and image understanding capabilitiesx_search(): Enables X (Twitter) search with date range filtering, handle-based filtering (include/exclude), and both image and video understandingcode_execution(): Enables server-side code execution for computational tasksxai_sdk.tools module for easily creating server-side tool configurationsServerSideTool enum in usage proto for tracking server-side tool usage (WEB_SEARCH, X_SEARCH, CODE_EXECUTION, VIEW_IMAGE, VIEW_X_VIDEO)server_side_tools_used field to SamplingUsage for detailed usage tracking of which server-side tools were invokedGetChatCompletionResponse.choices → GetChatCompletionResponse.outputsGetChatCompletionChunk.choices → GetChatCompletionChunk.outputsChoice message type → CompletionOutputChoiceChunk message type → CompletionOutputChunkcollections sub-client to Client and AsyncClient which can be used to interact with the collections API.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.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.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.documents sub-client from Client and AsyncClient. In order to search for documents within collections, use the client.collections.search method instead.telemetry module (xai_sdk.telemetry) which can be used to setup trace creation and exporting of traces to an otel backend or to the consoledocuments sub-client to Client and AsyncClient which can be used to interact with the documents API.search method on the documents sub-client which can be used to perform semantic search for documents that are stored in collections.from_date and to_date parameters to have no effect when using them via SearchParameters for the live search featurex_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 handlesexcluded_x_handles allows you to exclude posts authored by particular handlespost_favorite_count allows you to set a threshold for the minimum number of favorites a post must have to be consideredpost_view_count allows you to set a threshold for the minimum number of views a post must have to be considered