npx @buildinternet/releases get xai-sdk-pythonsafety_identifier parameter to client.chat.create. It is an opaque, stable string that your application assigns to the end user behind a request, so xAI can attribute a policy violation to that user instead of to your whole API key. Send a hash of your internal user ID, never an email address or display name. Same field as OpenAI's safety_identifier. The legacy user parameter is still accepted.last_frame_url / last_frame_file_id (on client.video.generate / start / prepare) pin the exact last frame of the clip; combined with image_url / image_file_id, the video interpolates between a pinned first and last frame. image_url / image_file_id combined with reference inputs, a last frame, or keyframes now pins the exact first frame. Only supported for grok-imagine-video-1.5.keyframes parameter to video generation (generate / start / prepare) that pins images at chosen moments inside the clip. Each entry is a TypedDict such as {"image_url": "https://...", "timestamp": 2.0} or {"image_file_id": "file_...", "timestamp": 2.0}, with timestamp in seconds; timestamps must fall strictly inside the clip, at most four entries. Only supported for grok-imagine-video-1.5.XaiSdk/{version} via grpc.primary_user_agent (same string already used for image URL fetches; exposed as xai_sdk.client.USER_AGENT)reference_audios and generate_audio parameters to video generation. reference_audios (on client.video.generate / start / prepare) is a list of audio sources for reference-to-video — each entry is a TypedDict such as {"voice_id": "ara"}; only supported for grok-imagine-video-1.5. generate_audio (on generate / start / prepare) controls whether the generated video includes audio (true) or is silent (false); when omitted the server defaults to true."1080p" as an accepted video resolution value (maps to VIDEO_RESOLUTION_1080P). Only supported on models that advertise 1080p (e.g. grok-imagine-video-1.5 for image-to-video).quality parameter ("low", "medium") to image generation (client.image.sample, sample_batch, and batch prepare), mapping to the GenerateImageRequest.quality field. When omitted, the default is "medium". Only supported for grok-imagine-image-2.0.grok-imagine-image-2.0 to the ImageGenerationModel known-model type literalxai_sdk.tools.image_generation helper for the server-side image_generation tool, enabling image generation and editing in agentic requests. Accepts an optional action parameter ("auto", "generate", or "edit") to control which image capabilities are exposed to the modelResponse.image_outputs for retrieving images generated by the server-side image_generation tool as decoded bytes (output.image), along with mime_type, data_url, image_uuid, and the originating tool_callgrok-imagine-video-1.5 and removed grok-imagine-video-1.5-preview (now an alias of grok-imagine-video-1.5) from VideoGenerationModel, and removed grok-imagine-image-pro (an alias of grok-imagine-image-quality) from ImageGenerationModel. These literals are type hints for editor autocomplete only — alias strings continue to work when passed to the API.chat.append(response) now sets tool_call_id on replayed tool-role messages (recovered from the tool call echoed on the output), so servers can pair replayed tool turns with their originating calls. This fixes stateless multi-turn follow-ups to server-side tools whose results are re-hydrated by ID — e.g. editing a previously generated image in-memory without previous_response_id.xhigh Reasoning Effort: Added "xhigh" as an accepted reasoning_effort value (maps to EFFORT_XHIGH; supported by models such as grok-4.6)grok-4.6 to the ChatModel known-model type literalgrok-4.5 and grok-4.5-latest to the ChatModel known-model type literalservice_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 usedstorage_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').grok-imagine-image-quality to the ImageGenerationModel known-model type literal and grok-imagine-video-1.5-preview to the VideoGenerationModel known-model type literalchat.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.grok-build-0.1 to the ChatModel known-model type literalenable_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 API"none" and "medium" as accepted reasoning_effort values (maps to EFFORT_NONE and EFFORT_MEDIUM)grok-4.3 and grok-4.3-latest to the ChatModel known-model type literalchat.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