openapi: 3.1.0 info: title: xAI's REST v1 API description: REST API for xAI compatible with other providers. license: name: '' version: 1.0.0 tags: - name: v1 paths: /v1/api-key: get: tags: - v1 summary: Get information about an API key, including name, status, permissions and users who created or modified this key. operationId: handle_get_api_key_info_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKey' example: redacted_api_key: xai-...b14o user_id: 59fbe5f2-040b-46d5-8325-868bb8f23eb2 name: My API Key create_time: '2024-01-01T12:55:18.139305Z' modify_time: '2024-08-28T17:20:12.343321Z' modified_by: 3d38b4dc-4eb7-4785-ae26-c3fa8997ffc7 team_id: 5ea6f6bd-7815-4b8a-9135-28b2d7ba6722 acls: - api-key:model:* - api-key:endpoint:* api_key_id: ae1e1841-4326-4b36-a8a9-8a1a7237db11 team_blocked: false api_key_blocked: false api_key_disabled: false '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/chat/completions: post: tags: - v1 summary: Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models. operationId: handle_generic_completion_request requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatRequest' example: messages: - role: system content: You are a helpful assistant that can answer questions and help with tasks. - role: user content: What is 101*3? model: latest required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ChatResponse' example: id: a3d1008e-4544-40d4-d075-11527e794e4a object: chat.completion created: 1752854522 model: latest choices: - index: 0 message: role: assistant content: 101 multiplied by 3 is 303. refusal: null finish_reason: stop usage: prompt_tokens: 32 completion_tokens: 9 total_tokens: 135 prompt_tokens_details: text_tokens: 32 audio_tokens: 0 image_tokens: 0 cached_tokens: 6 completion_tokens_details: reasoning_tokens: 94 audio_tokens: 0 accepted_prediction_tokens: 0 rejected_prediction_tokens: 0 num_sources_used: 0 system_fingerprint: fp_3a7881249c '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/chat/deferred-completion/{request_id}: get: tags: - v1 summary: Tries to fetch a result for a previously-started deferred completion. Returns `200 Success` with the response body, if the request has been completed. Returns `202 Accepted` when the request is pending processing. operationId: handle_get_deferred_completion_request parameters: - name: request_id in: path description: The deferred request id returned by a previous deferred chat request. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ChatResponse' example: id: 335b92e4-afa5-48e7-b99c-b9a4eabc1c8e object: chat.completion created: 1743770624 model: latest choices: - index: 0 message: role: assistant content: 101 multiplied by 3 is 303. refusal: null finish_reason: stop usage: prompt_tokens: 31 completion_tokens: 11 total_tokens: 42 prompt_tokens_details: text_tokens: 31 audio_tokens: 0 image_tokens: 0 cached_tokens: 0 completion_tokens_details: reasoning_tokens: 0 audio_tokens: 0 accepted_prediction_tokens: 0 rejected_prediction_tokens: 0 system_fingerprint: fp_156d35dcaa '202': description: Accepted. The request is processing, but haven't been completed. You can retry at a later time. '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No deferred completion could be found with the given request_id. security: - bearerAuth: [] /v1/complete: post: tags: - v1 summary: (Legacy - Not supported by reasoning models) Create a text completion response. This endpoint is compatible with the Anthropic API. operationId: handle_generic_complete_request requestBody: content: application/json: schema: $ref: '#/components/schemas/CompleteRequest' example: model: grok-3 max_tokens_to_sample: 8 temperature: 0.1 prompt: ' Human: Hello, how are you? Assistant:' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompleteResponse' example: type: completion id: 982044c5-760c-4c8d-8936-f906b5cedc26 completion: ' Hey there! I''m doing great, thanks' stop_reason: max_tokens model: grok-3 '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/completions: post: tags: - v1 summary: (Legacy - Not supported by reasoning models) Create a text completion response for a given prompt. Replaced by /v1/chat/completions. operationId: handle_sample_request requestBody: content: application/json: schema: $ref: '#/components/schemas/SampleRequest' example: prompt: '1, 2, 3, 4, ' model: grok-3 max_tokens: 3 required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SampleResponse' example: id: 873492b3-6144-4279-ac2e-2c45242c5ce6 object: text_completion created: 1743771779 model: grok-3 choices: - index: 0 text: '5, ' finish_reason: length usage: prompt_tokens: 12 completion_tokens: 3 total_tokens: 15 prompt_tokens_details: text_tokens: 12 audio_tokens: 0 image_tokens: 0 cached_tokens: 0 completion_tokens_details: reasoning_tokens: 0 audio_tokens: 0 accepted_prediction_tokens: 0 rejected_prediction_tokens: 0 system_fingerprint: fp_156d35dcaa '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/documents/search: post: tags: - v1 summary: Search for content related to the query within the given collections. operationId: handle_document_search_request_v2 requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' example: query: What is the revenue in the last quarter? source: collection_ids: - collection_80100614-300c-4609-959b-a138fa90f542 filter: document_type = "financial_report" AND year > 2020 required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: matches: - file_id: file_ac3c5728-7399-41fc-bd62-0fef0042de9c chunk_id: 0199717c-511b-7a80-bab3-dfe9a27f82ab chunk_content: ', deferred revenue related to such customer payments amounted to $2.10 billion and $1.77 billion, respectively, mainly due to contractual payment terms. Revenue recognized from the deferred revenue balances as of December 31, 2024 and 2023 was $944 million and $873 million for the six months ended June 30, 2025 and 2024, respectively. We have elected the practical expedient to omit disclosure of the amount of the transaction price allocated to remaining performance obligations for contracts with an original expected contract length of one year or less. As of June 30, 2025, total transaction price allocated to performance obligations that were unsatisfied or partially unsatisfied for contracts with an original expected length of more than one year was $10.38 billion. Of this amount, we expect to recognize $5.47 billion in the next 12 months and the rest over the remaining performance obligation period. Changes in government and economic incentives or tariffs may impact the transaction price or our ability to e' score: 1.1447691 collection_ids: - collection_80100614-300c-4609-959b-a138fa90f542 '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/embedding-models: get: tags: - v1 summary: List all embedding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es). operationId: handle_embedding_models_list_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListEmbeddingModelsResponse' example: models: - id: v1 fingerprint: fp_df37966059 created: 1725148800 object: model owned_by: xai version: 0.1.0 input_modalities: - text prompt_text_token_price: 100 prompt_image_token_price: 0 aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/embedding-models/{model_id}: get: tags: - v1 summary: Get full information about an embedding model with its model_id. operationId: handle_embedding_model_get_request parameters: - name: model_id in: path description: ID of the model to get. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/EmbeddingModel' example: id: v1 created: 1725148800 object: model owned_by: xai version: 0.1.0 input_modalities: - text prompt_text_token_price: 10 prompt_image_token_price: 0 aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Model not found security: - bearerAuth: [] /v1/embeddings: post: tags: - v1 summary: Create an embedding vector representation corresponding to the input text. This is the endpoint for making requests to embedding models. operationId: handle_embedding_request requestBody: content: application/json: schema: $ref: '#/components/schemas/EmbeddingRequest' example: "{\n \"input\": [\"This is an example content to embed...\"],\n \"model\": \"v1\",\n \"encoding_format\": \"float\"\n }" required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/EmbeddingResponse' example: object: list model: v1 data: - index: 0 embedding: - 0.01567895 - 0.063257694 - 0.045925662 object: embedding usage: prompt_tokens: 1 total_tokens: 1 '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/files: get: tags: - v1 summary: 'List files owned by the authenticated team, paginated. The response always returns a `pagination_token`; pass it back as a query parameter to fetch the next page. The end of the list is reached when the returned `data` array is shorter than `limit`.' operationId: handle_list_files_request parameters: - name: limit in: query description: The maximum number of objects to be returned in a single response. required: false schema: type: integer format: int32 - name: order in: query description: The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order. required: false schema: type: string - name: sort_by in: query description: 'The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.' required: false schema: type: string - name: pagination_token in: query description: The pagination token returned by the previous list files request. required: false schema: type: string - name: after in: query description: Only included for compatibility. Use `pagination_token` instead. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListFilesResponse' example: data: - id: file_a128090d-f0c9-4873-bd84-e499777e7417 object: file bytes: 12345 created_at: 1762345678 expires_at: null filename: document.pdf purpose: '' pagination_token: file_a128090d-f0c9-4873-bd84-e499777e7417 security: - bearerAuth: [] post: tags: - v1 summary: 'Upload a file to xAI''s storage. Returns the file''s metadata. Files can be referenced by ID anywhere a `file_id` is accepted (e.g. chat attachments). Maximum file size: 50 MB. Files are kept until you delete them, or until `expires_after` elapses if set at upload time.' operationId: handle_upload_file_request requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/UploadFileMultipartRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/File' example: id: file_a128090d-f0c9-4873-bd84-e499777e7417 object: file bytes: 12345 created_at: 1762345678 expires_at: 1762432078 filename: document.pdf purpose: '' '400': description: 'Bad request. Common causes: `expires_after` outside [3600, 2592000], `expires_after` field appearing after `file` in the multipart body, missing or unnamed `file` part, invalid filename.' '413': description: Payload too large -- file exceeds 50 MB. security: - bearerAuth: [] /v1/files/{file_id}: get: tags: - v1 summary: 'Retrieve metadata for a single file by ID. Errors with 404 if the file doesn''t exist, has been deleted, or has passed its `expires_at`.' operationId: handle_retrieve_file_request parameters: - name: file_id in: path description: The file's `id` returned by upload or list. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/File' '404': description: File not found, deleted, or expired. security: - bearerAuth: [] delete: tags: - v1 summary: 'Delete a file by ID. After this returns, the file no longer appears in `GET /v1/files`, content download returns 404, and the ID can no longer be referenced in chat attachments.' operationId: handle_delete_file_request parameters: - name: file_id in: path description: The file's `id` to delete. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteFileResponse' example: id: file_a128090d-f0c9-4873-bd84-e499777e7417 deleted: true '404': description: File not found or already deleted. security: - bearerAuth: [] /v1/files/{file_id}/content: get: tags: - v1 summary: 'Download the contents of a file as a stream of raw bytes. The response `Content-Type` is `application/octet-stream`. Use this for the binary payload; use `GET /v1/files/{file_id}` for metadata only.' operationId: handle_download_file_content_request parameters: - name: file_id in: path description: The file's `id` to download. required: true schema: type: string - name: format in: query description: Format of the downloaded content. required: false schema: $ref: '#/components/schemas/ContentFormat' responses: '200': description: Success -- raw file bytes streamed in chunks. content: application/octet-stream: schema: type: string '404': description: File not found, deleted, or expired. security: - bearerAuth: [] /v1/image-generation-models: get: tags: - v1 summary: List all image generation models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es). operationId: handle_image_generation_models_list_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListImageGenerationModelsResponse' example: models: - id: grok-imagine-image fingerprint: fp_ca78641a52 max_prompt_length: 1024 created: 1738961600 object: model owned_by: xai version: 1.0.0 prompt_text_token_price: 100000 prompt_image_token_price: 100000 generated_image_token_price: 100000 aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/image-generation-models/{model_id}: get: tags: - v1 summary: Get full information about an image generation model with its model_id. operationId: handle_image_generation_model_get_request parameters: - name: model_id in: path description: ID of the model to get. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ImageGenerationModel' example: id: grok-imagine-image fingerprint: fp_ca78641a52 max_prompt_length: 1024 created: 1737961600 object: model owned_by: xai version: 1.0.0 prompt_text_token_price: 100000 prompt_image_token_price: 100000 generated_image_token_price: 100000 aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Model not found security: - bearerAuth: [] /v1/images/edits: post: tags: - v1 summary: Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models. operationId: handle_edit_image_request requestBody: content: application/json: schema: $ref: '#/components/schemas/EditImageRequest' example: prompt: Add a hat to this cat. image: url: '...' model: grok-imagine-image required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GeneratedImageResponse' example: data: - url: '...' '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/images/generations: post: tags: - v1 summary: Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models. operationId: handle_generate_image_request requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateImageRequest' example: prompt: A cat in a tree model: grok-imagine-image response_format: url n: 2 required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GeneratedImageResponse' example: data: - url: '...' - url: '...' '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/language-models: get: tags: - v1 summary: List all chat and image understanding models available to the authenticating API key with full information. Additional information compared to /v1/models includes modalities, pricing, fingerprint and alias(es). operationId: handle_language_models_list_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListLanguageModelsResponse' example: models: - id: grok-3 fingerprint: fp_898ae9f31c created: 1743724800 object: model owned_by: xai version: '1.0' input_modalities: - text output_modalities: - text prompt_text_token_price: 30000 cached_prompt_text_token_price: 7500 prompt_image_token_price: 0 completion_text_token_price: 150000 search_price: 250000000 aliases: - grok-3-latest - grok-3-beta - id: grok-3-mini fingerprint: fp_6a09108ff5 created: 1743724800 object: model owned_by: xai version: '1.0' input_modalities: - text output_modalities: - text prompt_text_token_price: 3000 cached_prompt_text_token_price: 750 prompt_image_token_price: 0 completion_text_token_price: 5000 search_price: 250000000 aliases: - grok-3-mini-latest - grok-3-mini-beta - id: grok-2-vision-1212 fingerprint: fp_daba7546e5 created: 1733961600 object: model owned_by: xai version: 0.1.0 input_modalities: - text - image output_modalities: - text prompt_text_token_price: 20000 prompt_image_token_price: 20000 completion_text_token_price: 100000 aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/language-models/{model_id}: get: tags: - v1 summary: Get full information about a chat or image understanding model with its model_id. operationId: handle_language_model_get_request parameters: - name: model_id in: path description: ID of the model to get. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LanguageModel' example: id: latest fingerprint: fp_156d35dcaa created: 1743724800 object: model owned_by: xai version: 1.0.0 input_modalities: - text output_modalities: - text prompt_text_token_price: 20000 cached_prompt_text_token_price: 0 prompt_image_token_price: 0 completion_text_token_price: 100000 aliases: - grok-4 - grok-4-latest '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Model not found security: - bearerAuth: [] /v1/messages: post: tags: - v1 summary: Create a messages response. This endpoint is compatible with the Anthropic API. operationId: handle_generic_messages_request requestBody: content: application/json: schema: $ref: '#/components/schemas/MessageRequest' example: model: latest max_tokens: 32 messages: - role: user content: Hello, world required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MessageResponse' example: id: 4f224bfb-9d53-4c82-b40a-b7cd80831ec2 type: message role: assistant content: - type: text text: Hello there! "Hello, world" is a classic, isn't it? Whether you're just saying hi or channeling your inner coder, I'm happy to greet you back model: latest stop_reason: max_tokens stop_sequence: null usage: input_tokens: 9 cache_creation_input_tokens: 0 cache_read_input_tokens: 0 output_tokens: 32 '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/models: get: tags: - v1 summary: List all models available to the authenticating API key with minimalized information, including model names (ID), creation times, etc. operationId: handle_models_list_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListModelsResponse' example: data: - id: grok-4-0709 created: 1752019200 object: model owned_by: xai - id: grok-code-fast-1 created: 1755993600 object: model owned_by: xai - id: grok-3 created: 1743724800 object: model owned_by: xai - id: grok-3-mini created: 1743724800 object: model owned_by: xai - id: grok-2-image-1212 created: 1736726400 object: model owned_by: xai - id: grok-2-vision-1212 created: 1733961600 object: model owned_by: xai object: list '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/models/{model_id}: get: tags: - v1 summary: Get minimalized information about a model with its model_id. operationId: handle_model_get_request parameters: - name: model_id in: path description: ID of the model to get. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Model' example: id: latest created: 1743724800 object: model owned_by: xai '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Model not found security: - bearerAuth: [] /v1/responses: post: tags: - v1 summary: Generates a response based on text or image prompts. The response ID can be used to retrieve the response later or to continue the conversation without repeating prior context. New responses will be stored for 30 days and then permanently deleted. operationId: handle_generic_model_request requestBody: content: application/json: schema: $ref: '#/components/schemas/ModelRequest' example: input: - role: system content: You are a helpful assistant that can answer questions and help with tasks. - role: user content: What is 101*3? model: latest required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ModelResponse' example: created_at: 1754475266 id: ad5663da-63e6-86c6-e0be-ff15effa8357 max_output_tokens: null model: latest object: response output: - content: - type: output_text text: 101 multiplied by 3 is 303. logprobs: null annotations: [] id: msg_ad5663da-63e6-86c6-e0be-ff15effa8357 role: assistant type: message status: completed parallel_tool_calls: true previous_response_id: null reasoning: null temperature: null text: format: type: text tool_choice: auto tools: [] top_p: null usage: input_tokens: 32 input_tokens_details: cached_tokens: 8 output_tokens: 9 output_tokens_details: reasoning_tokens: 110 total_tokens: 151 num_sources_used: 0 num_server_side_tools_used: 0 user: null incomplete_details: null status: completed store: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/responses/{response_id}: get: tags: - v1 summary: Retrieve a previously generated response. operationId: handle_get_stored_completion_request parameters: - name: response_id in: path description: The response id returned by a previous create response request. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ModelResponse' example: created_at: 1754475266 id: ad5663da-63e6-86c6-e0be-ff15effa8357 max_output_tokens: null model: latest object: response output: - content: - type: output_text text: 101 multiplied by 3 is 303. logprobs: null annotations: [] id: msg_ad5663da-63e6-86c6-e0be-ff15effa8357 role: assistant type: message status: completed - id: '' summary: - text: 'First, the user asked: "What is 101*3?" This is a simple multiplication: 101 multiplied by 3. Calculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303. I should respond helpfully and directly, as per my system prompt: "You are a helpful assistant that can answer questions and help with tasks." Keep the response concise and accurate. No need for extra fluff unless it adds value. Final answer: 303.' type: summary_text type: reasoning status: completed parallel_tool_calls: true previous_response_id: null reasoning: null temperature: null text: format: type: text tool_choice: auto tools: [] top_p: null usage: prompt_tokens: 32 completion_tokens: 9 total_tokens: 151 prompt_tokens_details: text_tokens: 32 audio_tokens: 0 image_tokens: 0 cached_tokens: 8 completion_tokens_details: reasoning_tokens: 110 audio_tokens: 0 accepted_prediction_tokens: 0 rejected_prediction_tokens: 0 num_sources_used: 0 user: null incomplete_details: null status: completed store: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No responses could be found with the given response_id. security: - bearerAuth: [] delete: tags: - v1 summary: Delete a previously generated response. operationId: handle_delete_stored_completion_request parameters: - name: response_id in: path description: The response id returned by a previous create response request. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteStoredCompletionResponse' example: id: ad5663da-63e6-86c6-e0be-ff15effa8357 object: response deleted: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No responses could be found with the given response_id. security: - bearerAuth: [] /v1/tokenize-text: post: tags: - v1 summary: Tokenize text with the specified model operationId: handle_tokenize_text_request requestBody: content: application/json: schema: $ref: '#/components/schemas/TokenizeRequest' example: text: Hello world! model: latest required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TokenizeResponse' example: token_ids: - token_id: 13902 string_token: Hello token_bytes: - 72 - 101 - 108 - 108 - 111 - token_id: 1749 string_token: ' world' token_bytes: - 32 - 119 - 111 - 114 - 108 - 100 - token_id: 161 string_token: '!' token_bytes: - 33 '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/video-generation-models: get: tags: - v1 summary: List all video generation models available to the authenticating API key with full information. operationId: handle_video_generation_models_list_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListVideoGenerationModelsResponse' example: models: - id: grok-imagine-video fingerprint: fp_898ae9f31c created: 1743724800 object: model owned_by: xai version: 1.0.0 input_modalities: - text - image output_modalities: - video aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. security: - bearerAuth: [] /v1/video-generation-models/{model_id}: get: tags: - v1 summary: Get full information about a video generation model with its model_id. operationId: handle_video_generation_model_get_request parameters: - name: model_id in: path description: ID of the model to get. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/VideoGenerationModel' example: id: grok-imagine-video fingerprint: fp_898ae9f31c created: 1743724800 object: model owned_by: xai version: '1.0' input_modalities: - text - image output_modalities: - video aliases: [] '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Model not found security: - bearerAuth: [] /v1/videos/edits: post: tags: - v1 summary: 'Edit a video based on a prompt. This is an asynchronous operation that returns a request_id for polling.' operationId: handle_edit_video_request requestBody: content: application/json: schema: $ref: '#/components/schemas/EditVideoRequest' example: prompt: Add snow to the scene video: url: https://example.com/video.mp4 model: grok-imagine-video required: true responses: '200': description: Video editing started successfully content: application/json: schema: $ref: '#/components/schemas/StartDeferredResponse' example: request_id: a3d1008e-4544-40d4-d075-11527e794e4a '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/videos/extensions: post: tags: - v1 summary: 'Extend a video by generating continuation content. This is an asynchronous operation that returns a request_id for polling.' operationId: handle_extend_video_request requestBody: content: application/json: schema: $ref: '#/components/schemas/ExtendVideoRequest' example: prompt: The camera slowly zooms out to reveal the city skyline video: url: https://example.com/video.mp4 model: grok-imagine-video duration: 6 required: true responses: '200': description: Video extension started successfully content: application/json: schema: $ref: '#/components/schemas/StartDeferredResponse' example: request_id: a3d1008e-4544-40d4-d075-11527e794e4a '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/videos/generations: post: tags: - v1 summary: 'Generate a video from a text prompt and optionally an image. This is an asynchronous operation that returns a request_id for polling.' operationId: handle_generate_video_request requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateVideoRequest' example: prompt: A cat playing with a ball model: grok-imagine-video duration: 6 required: true responses: '200': description: Video generation started successfully content: application/json: schema: $ref: '#/components/schemas/StartDeferredResponse' example: request_id: a3d1008e-4544-40d4-d075-11527e794e4a '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/videos/{request_id}: get: tags: - v1 summary: Get the result of a deferred video generation request. description: 'Returns the current status of a video generation job. When the job completes successfully the response contains the generated video URL. When the job fails the response contains a structured `error` object with a machine-readable `code` and a human-readable `message`. Both successful and failed completions return HTTP 200 — use the `status` field (`"done"` or `"failed"`) to distinguish between the two.' operationId: handle_get_deferred_video_request parameters: - name: request_id in: path description: The deferred request id returned by a previous video generation request. required: true schema: type: string responses: '200': description: Video generation completed or failed. Check the `status` field to determine the outcome. content: application/json: schema: $ref: '#/components/schemas/VideoResponse' example: status: done video: url: https://vidgen.x.ai/xai-vidgen-bucket/xai-video-{request_id}.mp4 duration: 6 respect_moderation: true model: grok-imagine-video '202': description: Video generation still in progress '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No deferred video could be found with the given request_id. security: - bearerAuth: [] components: schemas: VideoResolution: type: string description: Resolution for video generation. enum: - 480p - 720p - 1080p Function: type: object required: - name - arguments properties: arguments: type: string name: type: string File: type: object description: An uploaded file. required: - bytes - created_at - filename - id - object properties: bytes: type: integer format: int64 description: The size of the file, in bytes. created_at: type: integer format: int64 description: The Unix timestamp (in seconds) for file creation time. expires_at: type: - integer - 'null' format: int64 description: The Unix timestamp (in seconds) for file expiry time. null if file does not expire. filename: type: string description: The name of the file. id: type: string description: The file identifier, which can be used in other API requests. object: type: string description: The object type, which is always `file`. Only included for compatability. purpose: type: string description: The intended purpose of the uploaded file. Only included for OAI compatability. VideoResponse: type: object description: Video generation response. required: - status - progress properties: error: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoError' description: 'Structured error describing why video generation failed. Only present when the generation encountered a failure (4xx or 5xx).' model: type: - string - 'null' description: The model used to generate the video. Omitted when status is "failed". progress: type: integer format: int32 description: 'Approximate completion percentage for the video generation task (0-100). - When status is "pending": progress is between 0-99, indicating current completion. - When status is "done": progress is 100. - When status is "failed": progress is 0.' maximum: 100 minimum: 0 status: type: string description: 'Status of the video generation: "done" when the video is ready.' usage: oneOf: - type: 'null' - $ref: '#/components/schemas/MediaUsage' description: Billing and cost information for this request. video: oneOf: - type: 'null' - $ref: '#/components/schemas/GeneratedVideo' description: The generated video data. Omitted when status is "failed". ReciprocalRankFusion: type: object description: Configuration for reciprocal rank fusion (RRF) reranking. properties: embedding_weight: type: number format: float description: Weight for embedding (dense) search results. Should be between 0 and 1. Defaults to 0.5. k: type: - integer - 'null' format: int32 description: The RRF constant k used in the reciprocal rank fusion formula. Defaults to 60. text_weight: type: number format: float description: Weight for keyword (sparse) search results. Should be between 0 and 1. Defaults to 0.5. RankingMetric: type: string description: 'Deprecated: Metric now comes from collection creation.' enum: - RANKING_METRIC_UNKNOWN - RANKING_METRIC_L2_DISTANCE - RANKING_METRIC_COSINE_SIMILARITY ModelOutput: oneOf: - allOf: - $ref: '#/components/schemas/OutputMessage' - allOf: - $ref: '#/components/schemas/FunctionToolCall' - allOf: - $ref: '#/components/schemas/Reasoning' - allOf: - $ref: '#/components/schemas/WebSearchCall' - allOf: - $ref: '#/components/schemas/FileSearchCall' - allOf: - $ref: '#/components/schemas/CodeInterpreterCall' - allOf: - $ref: '#/components/schemas/McpCall' - allOf: - $ref: '#/components/schemas/CustomToolCall' - allOf: - $ref: '#/components/schemas/ShellCall' LocalShellSkill: type: object description: A skill available in the local shell environment. required: - name - description - path properties: description: type: string description: A description of what the skill does. name: type: string description: The name of the skill. path: type: string description: The path to the directory containing the skill (with a SKILL.md file). ServerSideToolUsageDetails: type: object required: - web_search_calls - x_search_calls - code_interpreter_calls - file_search_calls - mcp_calls - document_search_calls properties: code_interpreter_calls: type: integer format: int32 description: Number of code interpreter calls. document_search_calls: type: integer format: int32 description: Number of document search calls. file_search_calls: type: integer format: int32 description: Number of file search calls. mcp_calls: type: integer format: int32 description: Number of MCP calls. web_search_calls: type: integer format: int32 description: Number of web search calls. x_search_calls: type: integer format: int32 description: Number of X search calls. ContentPart: type: object required: - type properties: file: oneOf: - type: 'null' - $ref: '#/components/schemas/FileRef' description: File reference for file attachments (OpenAI-compatible nesting). image_url: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageUrl' description: A public URL of image prompt, only available for vision models. text: type: - string - 'null' description: Text prompt. type: type: string description: The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. SampleContent: oneOf: - type: string description: Text prompt. - type: array items: type: string description: An array of strings, a token list, or an array of token lists. Message: oneOf: - type: object description: System message, usually instructions for the model to respond in a certain way. required: - content - role properties: content: $ref: '#/components/schemas/Content' description: System prompt content. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. role: type: string enum: - system - type: object description: User message, typically request from user for the model to answer. required: - content - role properties: content: $ref: '#/components/schemas/Content' description: System prompt content. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. role: type: string enum: - user - type: object description: Assistant role message, previous chat messages from the model. required: - role properties: content: oneOf: - type: 'null' - $ref: '#/components/schemas/Content' description: Assistant prompt content. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. reasoning_content: type: - string - 'null' description: Assistant reasoning content. role: type: string enum: - assistant tool_calls: type: - array - 'null' items: $ref: '#/components/schemas/ToolCall' description: An array of tool calls available to the model on your machine. - type: object description: Tool call role message, used to return function call result to the model. required: - content - role properties: content: $ref: '#/components/schemas/Content' description: Content of the tool call result. role: type: string enum: - tool tool_call_id: type: - string - 'null' description: The ID of the tool call received from assistant message response. - type: object description: 'Function call role message. Deprecated in favor of `{"role": "tool"}`.' required: - content - role properties: content: $ref: '#/components/schemas/Content' description: Content of the tool call result. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. role: type: string enum: - function description: Chat message objects. ContentFormat: type: string description: Format of the downloaded file content. enum: - original - text EmbeddingContent: oneOf: - type: string description: Embedding in base64 string. - type: array items: type: number format: float description: Embedding as an array of floats. Tool: oneOf: - type: object required: - function - type properties: function: $ref: '#/components/schemas/FunctionDefinition' description: Definition of tool call available to the model. type: type: string enum: - function - type: object required: - sources - type properties: sources: type: array items: $ref: '#/components/schemas/SearchSource' type: type: string enum: - live_search description: Definition of one tool that the model can call. GeneratedVideo: type: object description: Generated video. required: - duration - respect_moderation properties: duration: type: integer format: int32 description: Duration of the generated video in seconds. respect_moderation: type: boolean description: 'Whether the video generated by the model respects moderation rules. The field will be true if the video respects moderation rules. Otherwise the field will be false and the video url field will be empty.' url: type: - string - 'null' description: A url to the generated video. HybridRetrieval: type: object description: Document search using a combination of keyword and semantic search. properties: reranker: oneOf: - type: 'null' - $ref: '#/components/schemas/HybridReranker' description: Which reranker to use to limit results to the desired value. search_multiplier: type: - integer - 'null' format: int32 description: 'Additional multiplier to requested search limit. Valid range is [1, 100]. Defaults to 1 when unset.' EmbeddingUsage: type: object required: - prompt_tokens - total_tokens properties: prompt_tokens: type: integer format: int32 description: Prompt token used. total_tokens: type: integer format: int32 description: Total token used. ShellCallOutputResult: type: object description: The content of a shell tool call output that was emitted. required: - outcome properties: outcome: $ref: '#/components/schemas/ShellCallOutcome' description: The outcome of the command execution. stderr: type: string description: The standard error output that was captured. stdout: type: string description: The standard output that was captured. MediaUsage: type: object description: Billing and cost information for media generation requests (image and video). required: - cost_in_usd_ticks properties: cost_in_usd_ticks: type: integer format: int64 description: 'The cost of this request expressed in USD ticks. One USD cent equals 100,000,000 ticks, so one US dollar equals 10,000,000,000 ticks.' MessageBody: type: object description: Anthropic compatible message body required: - role - content properties: content: $ref: '#/components/schemas/MessageContent' description: The content message. role: type: string description: The role that the message belongs to, `"system"` for system prompt, `"user"` for user prompt, and `"assistant"` for response from the model. WebSearchUserLocation: type: object required: - type properties: city: type: - string - 'null' description: City of the user's location. country: type: - string - 'null' description: Two-letter ISO 3166-1 alpha-2 country code, like US, GB, etc. region: type: - string - 'null' description: Region of the user's location. timezone: type: - string - 'null' description: Timezone of the user's location, IANA timezone like America/Chicago, Europe/London, etc. type: type: string description: Type is always `"approximate"`. MessageTools: type: object required: - name - description - input_schema properties: cache_control: description: (Unsupported) Cache control. description: type: string description: Description of the tool. input_schema: $ref: '#/components/schemas/MessageToolInputSchema' description: Input schema allowed by the tool. name: type: string description: Name of the tool. ListLanguageModelsResponse: type: object required: - models properties: models: type: array items: $ref: '#/components/schemas/LanguageModel' description: Array of available language models. GeneratedImageResponse: type: object description: Image generation response for `/v1/image/generations` endpoint required: - data properties: data: type: array items: $ref: '#/components/schemas/GeneratedImage' description: A list of generated image objects. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/MediaUsage' description: Billing and cost information for this request. KeywordRetrieval: type: object description: Document search using keyword matching (sparse embeddings). properties: reranker: oneOf: - type: 'null' - $ref: '#/components/schemas/RerankerModel' description: Optional, but always used when doing search across multiple collections. VideoOutput: type: object description: Output destination for generated video. required: - upload_url properties: upload_url: type: string description: Signed URL to upload the generated video via HTTP PUT. UploadFileMultipartRequest: type: object description: 'Multipart form fields accepted by `POST /v1/files`. The `expires_after` field MUST appear before `file` in the multipart body when both are present (the upload handler streams `file` straight to gRPC and cannot rewind to read metadata after).' required: - file properties: expires_after: type: - integer - 'null' format: int64 description: 'Optional TTL in seconds (measured from upload time). Must be between 3600 (1 hour) and 2592000 (30 days). If unset the file does not expire. Accepts either a plain integer or the OpenAI SDK deepObject form (`expires_after[anchor]=created_at` + `expires_after[seconds]=N`) as separate multipart fields. The anchor+seconds form must arrive before the `file` part.' file: type: string format: binary description: 'The file to upload. The filename from the multipart `Content-Disposition: filename=` header is recorded as the file''s `filename`.' purpose: type: - string - 'null' description: 'Optional purpose label, accepted for OpenAI SDK compatibility. xAI does not enforce or interpret this field. Setting `"assistants"` is the conventional choice.' EmbeddingInput: oneOf: - type: object description: 'A strings to be embedded. For best performance, prepend "query: " in front of query content and prepend "passage: " in front of passage/text' required: - String properties: String: type: string description: 'A strings to be embedded. For best performance, prepend "query: " in front of query content and prepend "passage: " in front of passage/text' - type: object description: An array of strings to be embedded required: - StringArray properties: StringArray: type: array items: type: string description: An array of strings to be embedded - type: object description: A token in integer to be embedded required: - Ints properties: Ints: type: array items: type: integer format: int32 description: A token in integer to be embedded - type: object description: An array of tokens in integers to be embedded required: - IntsArray properties: IntsArray: type: array items: type: array items: type: integer format: int32 description: An array of tokens in integers to be embedded ToolChoice: oneOf: - type: string description: Controls tool access by the model. `"none"` makes model ignore tools, `"auto"` let the model automatically decide whether to call a tool, `"required"` forces model to pick a tool to call. - type: object required: - type properties: function: oneOf: - type: 'null' - $ref: '#/components/schemas/FunctionChoice' description: Name of the function to use. type: type: string description: Type is always `"function"`. description: Parameter to control how model chooses the tools. EditVideoRequest: type: object description: Request for editing video for `/v1/videos/edits` endpoint required: - prompt - video properties: model: type: - string - 'null' description: Model to be used. example: grok-imagine-video output: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoOutput' description: Optional output destination for generated video. prompt: type: string description: Prompt for video editing. user: type: - string - 'null' description: A unique identifier representing your end-user. video: $ref: '#/components/schemas/VideoUrl' description: Input video to perform edit on. OutputTokensDetails: type: object required: - reasoning_tokens properties: reasoning_tokens: type: integer format: int32 description: Tokens generated by the model for reasoning. SystemMessageContent: oneOf: - type: string description: Text content of system prompt. - type: array items: $ref: '#/components/schemas/SystemMessagePart' description: An array of system prompt parts. FileSearchResult: type: object required: - file_id - filename - text properties: file_id: type: string description: The file ID of the file search result. filename: type: string description: The filename of the file search result. score: type: number format: double description: 'The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent.' text: type: string description: The text of the file search result. Content: oneOf: - type: string description: Text prompt. - type: array items: $ref: '#/components/schemas/ContentPart' description: An array of content parts of different types, such as image, text or text file. description: Content of each chat message. RerankerModel: type: object description: Configuration for model-based reranking. properties: instructions: type: - string - 'null' description: Instructions for the reranking model. Defaults to generic reranking instructions. model: type: - string - 'null' description: The model to use for reranking. Defaults to standard reranker model. PromptUsageDetail: type: object description: Details of prompt usage. required: - text_tokens - audio_tokens - image_tokens - cached_tokens properties: audio_tokens: type: integer format: int32 description: Audio prompt token used. cached_tokens: type: integer format: int32 description: Token cached by xAI from previous requests and reused for this request. image_tokens: type: integer format: int32 description: Image prompt token used. text_tokens: type: integer format: int32 description: Total text prompt token used (cached + non-cached text tokens). HybridReranker: oneOf: - allOf: - $ref: '#/components/schemas/RerankerModel' description: Use a reranker model to perform the reranking. - type: object required: - type properties: type: type: string enum: - reranker_model description: Use a reranker model to perform the reranking. - allOf: - $ref: '#/components/schemas/ReciprocalRankFusion' description: Use RRF to perform the reranking. - type: object required: - type properties: type: type: string enum: - rrf description: Use RRF to perform the reranking. description: Reranker configuration for hybrid retrieval. ResponseFormat: oneOf: - type: object description: Specify text response format, always `"text"`. required: - type properties: type: type: string enum: - text - type: object description: Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this. required: - type properties: type: type: string enum: - json_object - type: object description: Specify json_schema response format with a given schema. Type is always `"json_schema"`. required: - json_schema - type properties: json_schema: description: A json schema representing the desired response schema. Includes the schema as a `"schema"` field. type: type: string enum: - json_schema description: Response format parameter for structured outputs. GenerateVideoRequest: type: object description: Request to generate video for `/v1/videos/generations` endpoint properties: aspect_ratio: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoAspectRatio' description: Aspect ratio of the generated video. duration: type: - integer - 'null' format: int32 description: 'Video duration in seconds. Range: [1, 15]. Default: 8. Also accepts `seconds` for OpenAI API compatibility. Accepts both number (8) and string ("8") values.' default: 8 maximum: 15 minimum: 1 image: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageUrl' description: 'Optional input image for image-to-video generation. If provided, generates video with this image as the first frame. Also accepts `input_reference` for compatibility (same semantics — first frame).' model: type: - string - 'null' description: Model to be used. example: grok-imagine-video output: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoOutput' description: Optional output destination for generated video. prompt: type: string description: 'Prompt for video generation. Required for text-to-video (T2V) and reference-to-video (R2V). Optional for image-to-video (I2V) — when omitted, the model generates a video from the image alone.' reference_images: type: array items: $ref: '#/components/schemas/ImageUrl' description: 'Optional reference images for reference-to-video (R2V) generation. When provided generates video using these images as style/content references.' resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoResolution' description: Resolution of the generated video. user: type: - string - 'null' description: A unique identifier representing your end-user. CompleteRequest: type: object description: (Legacy) Anthropic compatible complete request on `/v1/complete` endpoint. properties: max_tokens_to_sample: type: integer format: int32 description: The maximum number of tokens to generate before stopping. metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/MessageMetadata' description: An object describing metadata about the request. model: type: string description: Model to use for completion. prompt: type: string description: Prompt for the model to perform completion on. stop_sequences: type: - array - 'null' items: type: string description: (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. stream: type: - boolean - 'null' description: '(Unsupported) If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.' temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 example: 0.2 maximum: 2 minimum: 0 top_k: type: - integer - 'null' format: int32 description: (Unsupported) When generating next tokens, randomly selecting the next token from the k most likely options. top_p: type: - number - 'null' format: float description: An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 ShellEnvironment: type: object description: The environment configuration for a shell tool. required: - type properties: skills: type: array items: $ref: '#/components/schemas/LocalShellSkill' description: An optional list of skills available in the local environment. type: type: string description: The type of the environment. Currently only `local` is supported. MessageContentPart: oneOf: - type: object description: Text prompt message content part. required: - text - type properties: cache_control: description: (Unsupported) Cache control. text: type: string description: Text prompt. type: type: string enum: - text - type: object description: Image prompt message content part. required: - source - type properties: cache_control: description: (Unsupported) Cache control. source: $ref: '#/components/schemas/MessageImageContent' description: Image source. type: type: string enum: - image - type: object description: Tool call message content part. Received from model. required: - id - name - input - type properties: cache_control: description: (Unsupported) Cache control. id: type: string description: ID of the tool call. input: description: Input for tool call. name: type: string description: Name of the tool call. type: type: string enum: - tool_use - type: object description: Tool call result. required: - tool_use_id - content - type properties: cache_control: description: (Unsupported) Cache control. content: $ref: '#/components/schemas/ToolResultContent' description: Result content of the tool call. Can be a string or an array of content blocks. is_error: type: - boolean - 'null' description: Whether the tool call returns an error. tool_use_id: type: string description: ID of the tool call given by the model. type: type: string enum: - tool_result - type: object description: (Redacted) Thinking of the model. required: - data - type properties: data: type: string description: Encrypted data of the redacted thinking. type: type: string enum: - redacted_thinking - type: object description: Thinking of the model. required: - thinking - type properties: signature: type: - string - 'null' description: Signature of the thinking block (required by Anthropic SDK for round-tripping). thinking: type: string description: Thinking. type: type: string enum: - thinking ReasoningText: type: object required: - text - type properties: text: type: string description: Reasoning done by the model. type: type: string description: The type of the object, which is always `reasoning_text`. OutputMessageContent: oneOf: - type: object description: Text output. required: - text - type properties: annotations: type: array items: $ref: '#/components/schemas/Annotation' description: Citations. logprobs: type: array items: $ref: '#/components/schemas/TokenLogProb' description: The log probabilities of each output token returned in the content of message. text: type: string description: The text output from the model. type: type: string enum: - output_text - type: object description: Refusal. required: - refusal - type properties: refusal: type: string description: The reason for the refusal. type: type: string enum: - refusal ModelInputPart: oneOf: - type: object description: Message input to the model. required: - content - role properties: content: $ref: '#/components/schemas/ModelInputContent' description: Text, image or audio input. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages. role: type: string description: The role of the message. Possible values are `user`, `assistant`, `system` and `developer`. type: type: - string - 'null' description: The type of the message, which is always `message`. - allOf: - $ref: '#/components/schemas/ModelOutput' description: The model output from previous responses. - allOf: - $ref: '#/components/schemas/FunctionToolCallOutput' description: The output of a function call. - allOf: - $ref: '#/components/schemas/ShellCallOutput' description: The output of a shell call. - allOf: - $ref: '#/components/schemas/CompactionOutputItem' description: A compaction item from a previous `/v1/responses/compact` call. ChatResponse: type: object description: The chat response body for `/v1/chat/completions` endpoint. required: - id - object - created - model - choices properties: choices: type: array items: $ref: '#/components/schemas/Choice' description: A list of response choices from the model. The length corresponds to the `n` in request body (default to 1). citations: type: - array - 'null' items: type: string description: List of all the external pages used by the model to answer. created: type: integer format: int64 description: The chat completion creation time in Unix timestamp. id: type: string description: A unique ID for the chat response. model: type: string description: Model ID used to create chat completion. example: latest object: type: string description: The object type, which is always `"chat.completion"`. output_files: type: - array - 'null' items: $ref: '#/components/schemas/OutputFile' description: 'Files generated during the response (e.g., by the code execution tool). Only populated when `code_execution_files_output` is included.' system_fingerprint: type: - string - 'null' description: System fingerprint, used to indicate xAI system configuration changes. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/Usage' description: Token usage information. Choice: type: object required: - index - message properties: finish_reason: type: - string - 'null' description: Finish reason. `"stop"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"length"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `"end_turn"` or `null` in streaming mode when the chunk is not the last. index: type: integer format: int32 description: Index of the choice within the response choices, starting from 0. logprobs: oneOf: - type: 'null' - $ref: '#/components/schemas/LogProbs' description: The log probabilities of each output token returned in the content of message. message: $ref: '#/components/schemas/ChoiceMessage' description: The generated chat completion message. ShellCallOutcome: oneOf: - type: object description: The command exited normally. required: - exit_code - type properties: exit_code: type: integer format: int32 description: The exit code of the command. type: type: string enum: - exit - type: object description: The command timed out. required: - type properties: type: type: string enum: - timeout description: The outcome of a shell command execution. VideoAspectRatio: type: string description: Aspect ratio for video generation. enum: - '1:1' - '16:9' - '9:16' - '4:3' - '3:4' - '3:2' - '2:3' SystemMessagePart: type: object required: - type - text properties: cache_control: description: (Unsupported) Cache control. text: type: string description: System prompt text. type: type: string description: Type of the object. This is always `"text"`. ImageAspectRatio: type: string description: 'Aspect ratio for image generation. Only supported by grok-imagine models.' enum: - '1:1' - '3:4' - '4:3' - '9:16' - '16:9' - '2:3' - '3:2' - '9:19.5' - 19.5:9 - '9:20' - '20:9' - '1:2' - '2:1' - auto MessageUsage: type: object required: - input_tokens - cache_creation_input_tokens - cache_read_input_tokens - output_tokens properties: cache_creation_input_tokens: type: integer format: int32 description: (Unsupported) Number of tokens written to the cache when creating a new entry. cache_read_input_tokens: type: integer format: int32 description: Number of tokens retrieved from the cache for this request. input_tokens: type: integer format: int32 description: Number of input tokens used output_tokens: type: integer format: int32 description: Number of output tokens used GeneratedImage: type: object description: Generated images properties: b64_json: type: - string - 'null' description: A base64-encoded string representation of the generated image (without the data-URI prefix), if `b64_json` is specified as `response_format` in the request. mime_type: type: - string - 'null' description: The MIME type of the generated image (e.g. `image/png`, `image/jpeg`, `image/webp`). url: type: - string - 'null' description: A url to the generated image, if `response_format` is not specified or with `url` in the request. ModelInputContentItem: oneOf: - type: object description: Text input. required: - text - type properties: text: type: string description: Text input. type: type: string enum: - input_text - type: object description: Text output (used in compact response output items). required: - text - type properties: text: type: string type: type: string enum: - output_text - type: object description: 'Image input. Note: Storing and fetching images is not fully supported at the moment.' required: - image_url - type properties: file_id: type: - string - 'null' description: Only included for compatibility. image_url: type: string description: A public URL of image prompt, only available for vision models. type: type: string enum: - input_image - type: object description: File input. required: - type properties: file_data: type: - string - 'null' description: 'Inline file bytes (base64 encoded). When set, the file content is provided directly in the request and does NOT need to be uploaded to the Files API first. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' file_id: type: - string - 'null' description: 'The file ID from the Files API. Set this to reference a previously-uploaded file. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' file_url: type: - string - 'null' description: 'Public URL for a file attachment. When set, the file content is fetched from this URL. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' filename: type: - string - 'null' description: 'Filename for inline uploads. Required when `file_data` is set.' mime_type: type: - string - 'null' description: Optional MIME type for inline uploads (e.g. "application/pdf"). type: type: string enum: - input_file ShellCallOutput: type: object description: The output of a shell tool call, sent by the client after local execution. required: - call_id - output - type properties: call_id: type: string description: The unique ID of the shell tool call generated by the model. max_output_length: type: - integer - 'null' format: int32 description: 'The maximum length of the shell command output. Generated by the model and should be passed back with the raw output.' output: type: array items: $ref: '#/components/schemas/ShellCallOutputResult' description: An array of shell call output contents. type: type: string description: The type of the output item, which is always `shell_call_output`. ListVideoGenerationModelsResponse: type: object required: - models properties: models: type: array items: $ref: '#/components/schemas/VideoGenerationModel' description: Array of available video generation models. TopLogProb: type: object required: - token - logprob properties: bytes: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: The ASCII encoding of the output character. logprob: type: number format: float description: The log probability of returning this token. token: type: string description: The token. MessageToolChoice: oneOf: - type: object description: Allows the model to automatically decide whether to call the tool required: - type properties: type: type: string enum: - auto - type: object description: Forces the model to use at least one tool, without specifying the tool. required: - type properties: type: type: string enum: - any - type: object description: Forces the model to use the named tool required: - name - type properties: name: type: string description: Name of the tool to use. type: type: string enum: - tool description: Tool choice option. WebSearchCall: type: object description: The output of a web search tool call. required: - type - action properties: action: $ref: '#/components/schemas/WebSearchAction' description: 'An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find).' id: type: string description: The unique ID of the web search tool call. status: type: string description: The status of the web search tool call. type: type: string description: The type of the web search tool call. Always `web_search_call`. CodeInterpreterOutput: oneOf: - type: object description: The output of the code interpreter tool call. required: - logs - type properties: logs: type: string description: The output of the code interpreter tool call. type: type: string enum: - logs - type: object description: The error of the code interpreter tool call. required: - url - type properties: type: type: string enum: - image url: type: string description: The error of the code interpreter tool call. ImageGenerationModel: type: object description: Details of an image generation model required: - id - fingerprint - max_prompt_length - created - object - owned_by - version - input_modalities - output_modalities - image_price - aliases properties: aliases: type: array items: type: string description: Alias ID(s) of the model that user can use in a request's model field. created: type: integer format: int64 description: Model creation time in Unix timestamp. fingerprint: type: string description: Fingerprint of the xAI system configuration hosting the model. id: type: string description: Model ID. image_price: type: integer format: int64 description: Price of a single image in USD cents. input_modalities: type: array items: type: string description: The input modalities supported by the model. max_prompt_length: type: integer format: int64 object: type: string description: The object type, which is always `"model"`. output_modalities: type: array items: type: string description: The output modalities supported by the model. owned_by: type: string description: Owner of the model. version: type: string description: Version of the model. ModelResponse: type: object description: The response body for `/v1/responses` endpoint. required: - created_at - id - model - object - output - parallel_tool_calls - text - tool_choice - tools - status - store - metadata - background - service_tier - truncation - top_logprobs - presence_penalty - frequency_penalty properties: background: type: boolean description: 'OpenResponses compatibility fields. Not used at the moment. Just for OpenResponses compatibility. Whether to process the response asynchronously in the background.' default: false completed_at: type: - integer - 'null' format: int64 description: The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed. created_at: type: integer format: int64 description: The Unix timestamp (in seconds) for the response creation time. error: description: An error object returned when the model fails to generate a response. frequency_penalty: type: number format: float description: (NOT SUPPORTED in Responses API) Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. id: type: string description: Unique ID of the response. incomplete_details: oneOf: - type: 'null' - $ref: '#/components/schemas/IncompleteDetails' description: Details about why the response is incomplete. instructions: type: - string - 'null' description: A system (or developer) message inserted into the model's context. max_output_tokens: type: - integer - 'null' format: int32 description: Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. max_tool_calls: type: - integer - 'null' format: int32 description: The maximum number of tool calls allowed for this response. metadata: description: Only included for compatibility. model: type: string description: Model name used to generate the response. object: type: string description: The object type of this resource. Always set to `response`. output: type: array items: $ref: '#/components/schemas/ModelOutput' description: The response generated by the model. parallel_tool_calls: type: boolean description: Whether to allow the model to run parallel tool calls. presence_penalty: type: number format: float description: (NOT SUPPORTED in Responses API) Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. previous_response_id: type: - string - 'null' description: The ID of the previous response from the model. prompt_cache_key: type: - string - 'null' description: The cache key used for the prompt for routing to the correct engine. reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ReasoningConfiguration' description: Reasoning configuration. Only for reasoning models. safety_identifier: type: - string - 'null' description: A stable identifier used to help detect users of your application that may be violating xAI's usage policies. service_tier: type: string description: Specifies the processing tier used for serving the request. default: default status: type: string description: Status of the response. One of `completed`, `in_progress` or `incomplete`. store: type: boolean description: Whether to store the input message(s) and model response for later retrieval. default: true temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 maximum: 2 minimum: 0 text: $ref: '#/components/schemas/ModelResponseConfiguration' description: Settings for customizing a text response from the model. tool_choice: $ref: '#/components/schemas/ModelToolChoice' description: 'Controls which (if any) tool is called by the model. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.' tools: type: array items: $ref: '#/components/schemas/ModelTool' description: A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported. maxItems: 128 top_logprobs: type: integer format: int32 description: An integer between 0 and 8 specifying the number of most likely tokens to return at each token position. top_p: type: - number - 'null' format: float description: An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 truncation: type: string description: The truncation strategy to use for the model response. default: disabled usage: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelUsage' description: Token usage information. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. FileRef: type: object properties: file_id: type: - string - 'null' description: The file ID from the Files API. url: type: - string - 'null' description: Public URL for a file attachment. WebSearchSource: type: object required: - type properties: type: type: string description: The type of source. url: type: string description: The URL of the source. LanguageModel: type: object description: Details of a language model required: - id - fingerprint - created - object - owned_by - version - input_modalities - output_modalities - prompt_text_token_price - cached_prompt_text_token_price - prompt_image_token_price - completion_text_token_price - search_price - aliases properties: aliases: type: array items: type: string description: Alias ID(s) of the model that user can use in a request's model field. cached_prompt_text_token_price: type: integer format: int64 description: Price of a prompt text token (in USD cents per 100 million tokens) that was cached previously. completion_text_token_price: type: integer format: int64 description: Price of the completion text token in USD cents per 100 million token. created: type: integer format: int64 description: Creation time of the model in Unix timestamp. fingerprint: type: string description: Fingerprint of the xAI system configuration hosting the model. id: type: string description: Model ID. Obtainable from or . input_modalities: type: array items: type: string description: The input modalities supported by the model, e.g. `"text"`, `"image"`. object: type: string description: The object type, which is always `"model"`. output_modalities: type: array items: type: string description: The output modalities supported by the model, e.g. `"text"`, `"image"`. owned_by: type: string description: Owner of the model. prompt_image_token_price: type: integer format: int64 description: Price of the prompt image token in USD cents per 100 million token. prompt_text_token_price: type: integer format: int64 description: Price of the prompt text token in USD cents per 100 million token. search_price: type: integer format: int64 description: Price of the search in USD cents per 100 million searches. version: type: string description: Version of the model. RagPipeline: type: string enum: - chroma_db - es MessageRequest: type: object description: Request message for `/v1/messages` properties: max_tokens: type: integer format: int32 description: The maximum number of tokens to generate before stopping. The model may stop before the max_tokens when it reaches the stop sequence. messages: type: array items: $ref: '#/components/schemas/MessageBody' description: Input messages. metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/MessageMetadata' description: An object describing metadata about the request. model: type: string description: Model name for the model to use. example: latest stop_sequences: type: - array - 'null' items: type: string description: (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. stream: type: - boolean - 'null' description: 'If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.' system: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemMessageContent' description: System prompt message for the model, defining how the model should behave to user messages. temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. It may not work well with reasoning models. default: 1 maximum: 2 minimum: 0 tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/MessageToolChoice' description: 'Controls which (if any) tool is called by the model. `"none"` means the model will not call any tool and instead generates a message. `"auto"` means the model can pick between generating a message or calling one or more tools. `"any"` means the model must call one or more tools. Specifying a particular tool via `{"type": "tool", "function": {"name": "get_weather"}}` forces the model to call that tool. `"none"` is the default when no tools are provided. `"auto"` is the default if tools are provided.' tools: type: - array - 'null' items: $ref: '#/components/schemas/MessageTools' description: A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. top_k: type: - integer - 'null' format: int32 description: (Unsupported) When generating next tokens, randomly selecting the next token from the k most likely options. top_p: type: - number - 'null' format: float description: An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 ModelRequest: type: object description: The request body for `/v1/responses` endpoint. required: - input properties: background: type: - boolean - 'null' description: (Unsupported) Whether to process the response asynchronously in the background. default: false context_management: type: - array - 'null' items: {} description: Optional context-management directives (e.g. compaction). Parsed but not yet executed. include: type: - array - 'null' items: type: string description: What additional output data to include in the response. Currently the only supported value is `reasoning.encrypted_content` which returns an encrypted version of the reasoning tokens. input: $ref: '#/components/schemas/ModelInput' description: The input passed to the model. Can be text, image or file. instructions: type: - string - 'null' description: An alternate way to specify the system prompt. Note that this cannot be used alongside `previous_response_id`, where the system prompt of the previous message will be used. logprobs: type: - boolean - 'null' description: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. default: false max_output_tokens: type: - integer - 'null' format: int32 description: Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. max_turns: type: - integer - 'null' format: int32 description: 'Maximum number of agentic tool calling turns allowed for this request. If not set, defaults to the server''s global cap. This parameter will be ignored for any non-agentic requests.' metadata: description: Not supported. Only maintained for compatibility reasons. model: type: string description: Model name for the model to use. Obtainable from or . example: latest parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run parallel tool calls. default: true previous_response_id: type: - string - 'null' description: The ID of the previous response from the model. prompt_cache_key: type: - string - 'null' description: Plumbed to x-grok-conv-id for Open Responses compatibility, used for routing. reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ReasoningConfiguration' description: Reasoning configuration. Only for reasoning models. search_parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchParameters' description: Set the parameters to be used for searched data. Takes precedence over `web_search_preview` tool if specified in the tools. service_tier: type: - string - 'null' description: Not supported. Only maintained for compatibility reasons. store: type: - boolean - 'null' description: Whether to store the input message(s) and model response for later retrieval. default: true stream: type: - boolean - 'null' description: 'If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.' default: false example: true temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 example: 0.2 maximum: 2 minimum: 0 text: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelResponseConfiguration' description: Settings for customizing a text response from the model. tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelToolChoice' description: 'Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.' tools: type: - array - 'null' items: $ref: '#/components/schemas/ModelTool' description: A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`. maxItems: 128 top_logprobs: type: - integer - 'null' format: int32 description: An integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used. maximum: 8 minimum: 0 top_p: type: - number - 'null' format: float description: An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 truncation: type: - string - 'null' description: Not supported. Only maintained for compatibility reasons. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Reasoning: type: object description: The reasoning done by the model. required: - summary - type properties: content: type: array items: $ref: '#/components/schemas/ReasoningText' description: The reasoning text contents. encrypted_content: type: - string - 'null' description: The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`. id: type: string description: The unique ID of the reasoning content. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. summary: type: array items: $ref: '#/components/schemas/SummaryText' description: The summarized reasoning text contents. type: type: string description: The type of the object, which is always `reasoning`. McpCall: type: object description: The output of a MCP tool call. required: - type - name - server_label - arguments - output properties: arguments: type: string description: A JSON string of the arguments passed to the tool. error: type: string description: The error message of the MCP tool call. id: type: string description: The unique ID of the MCP tool call. name: type: string description: The name of the tool that was run. output: type: string description: The output of the MCP tool call. server_label: type: string description: The label of the MCP server running the tool. status: type: string description: The status of the MCP tool call. type: type: string description: The type of the MCP tool call. Always `mcp_call`. Model: type: object description: Same as `LanguageModel` but fully compliant with the OpenAI API. required: - id - created - object - owned_by properties: created: type: integer format: int64 description: Model creation time in Unix timestamp. id: type: string description: Model ID. Obtainable from or . object: type: string description: The object type, which is always `"model"`. owned_by: type: string description: Owner of the model. SampleResponse: type: object description: (Legacy) Response for `/v1/completions` endpoint required: - id - object - created - model - choices properties: choices: type: array items: $ref: '#/components/schemas/SampleChoice' description: A list of response choices from the model. The length corresponds to the `n` in request body (default to 1). created: type: integer format: int64 description: The chat completion creation time in Unix timestamp. id: type: string description: ID of the request. model: type: string description: Model to be used. example: latest object: type: string description: Object type of the response. This is always `"text_completion"`. system_fingerprint: type: - string - 'null' description: System fingerprint, used to indicate xAI system configuration changes. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/Usage' description: Token usage information. ModelUsage: type: object required: - input_tokens - input_tokens_details - output_tokens - output_tokens_details - total_tokens - num_sources_used - num_server_side_tools_used properties: cost_in_nano_usd: type: - integer - 'null' format: int64 description: Cost in nano US dollars for this request. cost_in_usd_ticks: type: - integer - 'null' format: int64 description: 'Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10''000''000''000 ticks in one *dollar*.' input_tokens: type: integer format: int32 description: Number of input tokens used. input_tokens_details: $ref: '#/components/schemas/InputTokensDetails' description: Breakdown of the input tokens. num_server_side_tools_used: type: integer format: int32 description: Number of server side tools used. num_sources_used: type: integer format: int32 description: Number of sources used (for live search). output_tokens: type: integer format: int32 description: Number of output tokens used. output_tokens_details: $ref: '#/components/schemas/OutputTokensDetails' description: Breakdown of the output tokens. server_side_tool_usage_details: oneOf: - type: 'null' - $ref: '#/components/schemas/ServerSideToolUsageDetails' description: Details about the server side tool usage. total_tokens: type: integer format: int32 description: Total tokens used. ApiKey: type: object required: - redacted_api_key - user_id - name - create_time - modify_time - modified_by - team_id - acls - api_key_id - team_blocked - api_key_blocked - api_key_disabled properties: acls: type: array items: type: string description: A list of ACLs authorized with the API key, e.g. `"api-key:endpoint:*"`, `"api-key:model:*"`. api_key_blocked: type: boolean description: Indicates whether the API key is blocked. api_key_disabled: type: boolean description: Indicates whether the API key is disabled. api_key_id: type: string description: ID of the API key. create_time: type: string description: Creation time of the API key in Unix timestamp. modified_by: type: string description: User ID of the user who last modified the API key. modify_time: type: string description: Last modification time of the API key in Unix timestamp. name: type: string description: The name of the API key specified by user. redacted_api_key: type: string description: The redacted API key. team_blocked: type: boolean description: Indicates whether the team that owns the API key. team_id: type: string description: The team ID of the team that owns the API key. user_id: type: string description: User ID the API key belongs to. VideoUrl: type: object description: 'Video input for editing and extension requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.' properties: file_id: type: - string - 'null' description: 'File ID from the xAI Files API. Mutually exclusive with `url`. The file must be a video (e.g., MP4) and fully uploaded.' url: type: string description: 'URL of the video (public URL or base64-encoded data URL). The video must have the `.mp4` file extension and be encoded with `.mp4` supported codecs such as H.265, H.264, AV1, etc. Required when `file_id` is not set.' WebSearchFilters: type: object properties: allowed_domains: type: - array - 'null' items: type: string description: 'List of website domains (without protocol specification or subdomains) to restrict search results to (e.g., ["example.com"]). A maximum of 5 websites can be allowed. Use this as a whitelist to limit results to only these specific sites; no other websites will be considered. If no relevant information is found on these websites, the number of results returned might be smaller than `max_search_results` set in `SearchParameters`. Note: This parameter cannot be set together with `excluded_domains`.' example: - example.com maxItems: 5 excluded_domains: type: - array - 'null' items: type: string description: 'List of website domains (without protocol specification or subdomains) to exclude from search results (e.g., ["example.com"]). Use this to prevent results from unwanted sites. A maximum of 5 websites can be excluded. This parameter cannot be set together with `allowed_domains`.' example: - example.com maxItems: 5 RetrievalMode: oneOf: - allOf: - $ref: '#/components/schemas/HybridRetrieval' description: Hybrid search combining keyword and semantic search. - type: object required: - type properties: type: type: string enum: - hybrid description: Hybrid search combining keyword and semantic search. - allOf: - $ref: '#/components/schemas/SemanticRetrieval' description: Semantic search using dense embeddings. - type: object required: - type properties: type: type: string enum: - semantic description: Semantic search using dense embeddings. - allOf: - $ref: '#/components/schemas/KeywordRetrieval' description: Keyword search using sparse embeddings. - type: object required: - type properties: type: type: string enum: - keyword description: Keyword search using sparse embeddings. description: Retrieval mode configuration for document search. FunctionChoice: type: object description: Function name. required: - name properties: name: type: string ModelInput: oneOf: - type: string description: Text input. - type: array items: $ref: '#/components/schemas/ModelInputPart' description: A list of input items to the model. Can be of different types. description: Content of the input passed to a `/v1/response` request. ShellCallAction: type: object description: The shell commands and limits that describe how to run the tool call. required: - commands properties: commands: type: array items: type: string description: The commands to run. max_output_length: type: - integer - 'null' format: int32 description: Optional maximum number of characters to return from each command. timeout_ms: type: - integer - 'null' format: int64 description: Optional timeout in milliseconds for the commands. type: type: - string - 'null' description: The type of the action, which is always `exec`. ChatRequest: type: object description: The chat request body for `/v1/chat/completions` endpoint. properties: deferred: type: - boolean - 'null' description: If set to `true`, the request returns a `request_id`. You can then get the deferred response by GET `/v1/chat/deferred-completion/{request_id}`. default: false frequency_penalty: type: - number - 'null' format: float description: (Not supported by reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. default: 0 maximum: 2 minimum: -2 logit_bias: type: - object - 'null' description: (Unsupported) A JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. additionalProperties: type: number format: float propertyNames: type: integer format: int32 logprobs: type: - boolean - 'null' description: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. default: false max_completion_tokens: type: - integer - 'null' format: int32 description: An upper bound for the number of tokens that can be generated for a completion, only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to None, meaning the model will generate as many tokens as needed up until the model's maximum context length. example: 8192 max_tokens: type: - integer - 'null' format: int32 description: \[DEPRECATED\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`. example: 8192 messages: type: array items: $ref: '#/components/schemas/Message' description: A list of messages that make up the chat conversation. Different models support different message types, such as image and text. model: type: string description: Model name for the model to use. Obtainable from or . example: latest n: type: - integer - 'null' format: int32 description: How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs. default: 1 example: 1 minimum: 1 parallel_tool_calls: type: - boolean - 'null' description: If set to false, the model can perform maximum one tool call. default: true example: false presence_penalty: type: - number - 'null' format: float description: (Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. default: 0 maximum: 2 minimum: -2 reasoning_effort: type: - string - 'null' description: Constrains how hard a reasoning model thinks before responding. Not supported by `grok-4` and will result in error if used with `grok-4`. Possible values are `low` (uses fewer reasoning tokens) and `high` (uses more reasoning tokens). response_format: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseFormat' description: 'An object specifying the format that the model must output. Specify `{ "type": "json_object" }` for JSON output, or `{ "type": "json_schema", "json_schema": {...} }` for structured outputs. If `{ \"type\": \"text\" }`, the model will return a text response.' search_parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchParameters' description: Set the parameters to be used for searched data. If not set, no data will be acquired by the model. seed: type: - integer - 'null' format: int32 description: If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. stop: type: - array - 'null' items: type: string description: (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. stream: type: - boolean - 'null' description: 'If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.' default: false example: true stream_options: oneOf: - type: 'null' - $ref: '#/components/schemas/StreamOptions' description: 'Options for streaming response. Only set this when you set `stream: true`.' temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 example: 0.2 maximum: 2 minimum: 0 tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolChoice' description: 'Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.' tools: type: - array - 'null' items: $ref: '#/components/schemas/Tool' description: A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. maxItems: 128 top_logprobs: type: - integer - 'null' format: int32 description: An integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used. maximum: 8 minimum: 0 top_p: type: - number - 'null' format: float description: An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. web_search_options: oneOf: - type: 'null' - $ref: '#/components/schemas/WebSearchOptions' description: 'Options to control the web search. This is only included for compatibility reason. Prefer the usage of `realtime_data_parameters` instead.' SummaryText: type: object required: - text - type properties: text: type: string description: Summary of the reasoning done by the model. type: type: string description: The type of the object, which is always `summary_text`. MessageResponse: type: object description: Response message for `/v1/messages` required: - id - type - role - content - model - usage properties: content: type: array items: $ref: '#/components/schemas/MessageResponseContent' description: Response message content. id: type: string description: Unique object identifier. model: type: string description: Model name that handled the request. example: latest role: type: string description: Role of the generated message. Always `"assistant"` stop_reason: type: - string - 'null' description: Reason to stop. `"stop_sequence"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"max_tokens"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `"end_turn"` or `null` in streaming mode when the chunk is not the last. `"tool_use"` means the model has called a tool and is waiting for the tool response. stop_sequence: type: - string - 'null' description: Custom stop sequence used to stop the generation. type: type: string description: Object type. This is always `"message"` for message types. example: message usage: $ref: '#/components/schemas/MessageUsage' description: Token usage information. ModelTool: oneOf: - allOf: - $ref: '#/components/schemas/FunctionDefinition' - type: object description: A function that the model can call. required: - type properties: type: type: string enum: - function description: A function that the model can call. - allOf: - $ref: '#/components/schemas/WebSearchOptions' - type: object properties: allowed_domains: type: - array - 'null' items: type: string description: 'List of website domains to allow in the search results. This parameter act as a whitelist where only those websites can be selected. A maximum of 5 websites can be selected. Note: This parameter cannot be set with `excluded_domains`.' example: - wikipedia.com maxItems: 5 enable_image_search: type: - boolean - 'null' description: 'When true, activates the image search server-side tool, enabling the model to search for images alongside the standard web search.' enable_image_understanding: type: - boolean - 'null' description: Enable image understanding during web search. excluded_domains: type: - array - 'null' items: type: string description: 'List of website domains to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. Note: This parameter cannot be set with `allowed_domains`' example: - wikipedia.com maxItems: 5 external_web_access: type: - boolean - 'null' description: 'Control whether the web search tool fetches live content or uses only cached content. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' filters: oneOf: - type: 'null' - $ref: '#/components/schemas/WebSearchFilters' description: Filters to apply to the search results. Compatible with OpenAI's API. search_context_size: type: - string - 'null' description: 'High level guidance for the amount of context window space to use for the search. Available values are `low`, `medium`, or `high`. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' user_location: oneOf: - type: 'null' - $ref: '#/components/schemas/WebSearchUserLocation' description: 'The user location to use for the search. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' - type: object description: Search the web. required: - type properties: type: type: string enum: - web_search description: Search the web. - type: object description: Search X. required: - type properties: allowed_x_handles: type: - array - 'null' items: type: string description: 'List of X Handles of the users from whom to consider the posts. Note: This parameter cannot be set with `excluded_x_handles`.' example: - elonmusk maxItems: 10 enable_image_understanding: type: - boolean - 'null' description: Enable image understanding during X search. enable_video_understanding: type: - boolean - 'null' description: Enable video understanding during X search. excluded_x_handles: type: - array - 'null' items: type: string description: 'List of X Handles of the users from whom to exclude the posts. Note: This parameter cannot be set with `allowed_x_handles`.' example: - elonmusk maxItems: 10 from_date: type: - string - 'null' format: date description: 'Date from which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-06-24' to_date: type: - string - 'null' format: date description: 'Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-12-24' type: type: string enum: - x_search - type: object description: Search the knowledge bases. required: - vector_store_ids - type properties: filters: description: 'A filter to apply. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' max_num_results: type: - integer - 'null' format: int32 example: 10 minimum: 1 ranking_options: description: 'Ranking options for search. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' type: type: string enum: - file_search vector_store_ids: type: array items: type: string description: List of vector store IDs to search within. example: - collection_id_1 - collection_id_2 maxItems: 10 - type: object description: Execute code. required: - type properties: container: description: 'The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' type: type: string enum: - code_interpreter - type: object description: A remote MCP server to use. required: - server_label - server_url - type properties: allowed_tools: type: - array - 'null' items: type: string authorization: type: - string - 'null' connector_id: type: - string - 'null' headers: type: - object - 'null' additionalProperties: type: string propertyNames: type: string require_approval: type: - string - 'null' server_description: type: - string - 'null' server_label: type: string server_url: type: string type: type: string enum: - mcp - type: object description: A local shell execution tool. required: - environment - type properties: environment: $ref: '#/components/schemas/ShellEnvironment' description: The environment configuration for the shell tool. type: type: string enum: - shell description: Definition of one tool that the model can call. CompactionOutputItem: type: object description: 'A compaction item from a previous `/v1/responses/compact` call. Accepted as input in `/v1/responses` calls. Clients must treat `encrypted_content` as opaque — do not parse or depend on its internal structure.' required: - type - encrypted_content properties: encrypted_content: type: string description: The encrypted content of the compacted conversation. id: type: - string - 'null' description: The unique ID of the compaction item (e.g. `cmp_`). type: type: string description: The type of the item. Always `"compaction"`. EditImageRequest: type: object description: Request for editing image required: - prompt properties: aspect_ratio: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageAspectRatio' description: 'Aspect ratio of the output image for image editing with multiple images. For single image editing, do not set this. It will always auto-detect from the input image.' image: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageUrl' description: Input image to perform edit on. Mutually exclusive with `images`. images: type: array items: $ref: '#/components/schemas/ImageUrl' description: 'List of input images for multi-reference editing. Mutually exclusive with `image`. When multiple images are provided, refer to them as \, \, etc. in the prompt.' model: type: - string - 'null' description: Model to be used. example: grok-imagine-image n: type: - integer - 'null' format: int32 description: Number of image edits to be generated. prompt: type: string description: Prompt for image editing. resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageResolution' description: 'Resolution of the generated image. Defaults to `1k`. Only supported by grok-imagine models.' response_format: type: - string - 'null' description: Response format to return the image in. Can be `url` or `b64_json`. If `b64_json` is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file. default: url user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. GenerateImageRequest: type: object properties: aspect_ratio: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageAspectRatio' description: 'Aspect ratio of the generated image. Can be `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `9:19.5`, `19.5:9`, `9:20`, `20:9`, `1:2`, `2:1`, or `auto`. Defaults to `auto` for automatically selecting the best ratio for the prompt. Only supported by grok-imagine models.' model: type: - string - 'null' description: Model to be used. example: grok-imagine-image n: type: - integer - 'null' format: int32 description: Number of images to be generated default: 1 maximum: 10 minimum: 1 prompt: type: string description: Prompt for image generation. resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/ImageResolution' description: 'Resolution of the generated image. Defaults to `1k`. Only supported by grok-imagine models.' response_format: type: - string - 'null' description: Response format to return the image in. Can be url or b64_json. If b64_json is specified, the image will be returned as a base64-encoded string instead of a url to the generated image file. default: url user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. MessageContent: oneOf: - type: string description: Text prompt. - type: array items: $ref: '#/components/schemas/MessageContentPart' description: An array of message content parts. MessageImageContent: oneOf: - type: object required: - media_type - data - type properties: data: type: string description: Base64 encoded image string. media_type: type: string description: 'Media type of the image source. Available options: `image/jpeg`, `image/png`, `image/webp`.' type: type: string enum: - base64 - type: object required: - url - type properties: type: type: string enum: - url url: type: string description: URL of the image. OutputFile: type: object description: A file generated during the model's response (e.g., by the code execution tool). required: - file_id - name properties: file_id: type: string description: The file ID from the Files API. Use this to download the file. name: type: string description: The display name of the file. ShellCall: type: object description: A shell command call emitted by the model for local execution. required: - action - call_id - type properties: action: $ref: '#/components/schemas/ShellCallAction' description: The shell commands and limits that describe how to run the tool call. call_id: type: string description: The unique ID of the shell tool call generated by the model. environment: oneOf: - type: 'null' - $ref: '#/components/schemas/ShellEnvironment' description: The environment for the shell tool call. id: type: string description: The unique ID of the shell call item. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The type of the output item, which is always `shell_call`. ModelToolChoice: oneOf: - type: string description: Controls tool access by the model. `"none"` makes model ignore tools, `"auto"` let the model automatically decide whether to call a tool, `"required"` forces model to pick a tool to call. - type: object required: - type - name properties: name: type: string description: Name of the function to use. type: type: string description: Type is always `"function"`. description: Parameter to control how model chooses the tools. CompleteResponse: type: object description: (Legacy) Anthropic compatible complete response on `/v1/complete` endpoint. required: - type - id - completion - model properties: completion: type: string description: The completion content up to and excluding stop sequences. id: type: string description: ID of the completion response. model: type: string description: The model that handled the request. stop_reason: type: - string - 'null' description: The reason to stop completion. `"stop_sequence"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"length"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `"end_turn"` or `null` in streaming mode when the chunk is not the last. type: type: string description: Completion response object type. This is always `"completion"`. DeleteStoredCompletionResponse: type: object description: Response to delete a stored completion. required: - id - object - deleted properties: deleted: type: boolean description: Whether the response was successfully deleted. id: type: string description: The response_id to be deleted. object: type: string description: The deleted object type, which is always `response`. ToolCall: type: object required: - id - function properties: function: $ref: '#/components/schemas/Function' description: Function to call for the tool call. id: type: string description: A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request. index: type: - integer - 'null' format: int32 description: Index of the tool call. type: type: - string - 'null' description: Type of tool call, should be `"function"` or `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` TokenizeResponseToken: type: object required: - token_id - string_token - token_bytes properties: string_token: type: string description: The string of the token. token_bytes: type: array items: type: integer format: int32 minimum: 0 description: The bytes that constituted the token. token_id: type: integer format: int32 description: The integer representation of the token for the model. minimum: 0 VideoErrorCode: type: string description: 'Machine-readable error codes for video generation failures. These are the codes that can appear in `VideoError.code` when polling a deferred video generation result. Authentication errors, model-not-found errors, and rate-limit errors are returned synchronously as HTTP errors and never appear in `VideoError`. Serializes to/from snake_case strings (e.g. `"invalid_argument"`, `"internal_error"`) for JSON compatibility.' enum: - invalid_argument - permission_denied - failed_precondition - internal_error Annotation: type: object required: - type - url properties: end_index: type: - integer - 'null' format: int32 description: The end index of the annotation. start_index: type: - integer - 'null' format: int32 description: The summary of the annotation. title: type: - string - 'null' description: The title of the annotation. type: type: string description: The type of the annotation. Only supported type currently is `url_citation`. url: type: string description: The URL of the web resource. EmbeddingModel: type: object description: Details of an embedding model required: - id - fingerprint - created - object - owned_by - version - input_modalities - output_modalities - prompt_text_token_price - prompt_image_token_price - aliases properties: aliases: type: array items: type: string description: Alias ID(s) of the model that user can use in a request's model field. created: type: integer format: int64 description: Model creation time in Unix timestamp. fingerprint: type: string description: Fingerprint of the xAI system configuration hosting the model. id: type: string description: Model ID. Obtainable from or . input_modalities: type: array items: type: string description: The input modalities supported by the model. object: type: string description: Object type, should be model. output_modalities: type: array items: type: string description: The output modalities supported by the model. owned_by: type: string description: Owner of the model. prompt_image_token_price: type: integer format: int64 description: Price of the prompt image token in USD cents per million token. prompt_text_token_price: type: integer format: int64 description: Price of the prompt text token in USD cents per million token. version: type: string description: Version of the model. CompletionUsageDetail: type: object description: Details of completion usage. required: - reasoning_tokens - audio_tokens - accepted_prediction_tokens - rejected_prediction_tokens properties: accepted_prediction_tokens: type: integer format: int32 description: The number of tokens in the prediction that appeared in the completion. audio_tokens: type: integer format: int32 description: Audio input tokens generated by the model. reasoning_tokens: type: integer format: int32 description: Tokens generated by the model for reasoning. rejected_prediction_tokens: type: integer format: int32 description: The number of tokens in the prediction that did not appear in the completion. DeleteFileResponse: type: object required: - id - deleted - object properties: deleted: type: boolean description: Whether the file was deleted. id: type: string description: The ID of the file. object: type: string description: The object type, which is always "file". Only included for compatibility. ExtendVideoRequest: type: object description: Request for extending a video for `/v1/videos/extensions` endpoint required: - prompt - video properties: duration: type: - integer - 'null' format: int32 description: 'Duration of the extension segment to generate in seconds (1-10). Defaults to 6 seconds if not specified.' model: type: - string - 'null' description: Model to be used. example: grok-imagine-video output: oneOf: - type: 'null' - $ref: '#/components/schemas/VideoOutput' description: Optional output destination for generated video. prompt: type: string description: Prompt describing what should happen next in the video. video: $ref: '#/components/schemas/VideoUrl' description: 'Input video to extend. The extension continues from the end of this video. Input video must be between 2 and 30 seconds long.' ListFilesResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/File' description: List of files. pagination_token: type: - string - 'null' description: Pagination token to use with next request. TokenizeRequest: type: object properties: model: type: string description: The model to tokenize with. text: type: string description: The text content to be tokenized. user: type: - string - 'null' description: Optional user identifier. LogProbs: type: object properties: content: type: - array - 'null' items: $ref: '#/components/schemas/TokenLogProb' description: An array the log probabilities of each output token returned. EmbeddingResponse: type: object required: - object - model - data properties: data: type: array items: $ref: '#/components/schemas/Embedding' description: A list of embedding objects. model: type: string description: Model ID used to create embedding. object: type: string description: The object type of `data` field, which is always `"list"`. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/EmbeddingUsage' description: Token usage information. StreamOptions: type: object description: Options available when using streaming response. required: - include_usage properties: include_usage: type: boolean description: 'Set an additional chunk to be streamed before the `data: [DONE]` message. The other chunks will return `null` in `usage` field.' WebSearchAction: oneOf: - type: object description: Action type "search" - Performs a web search query. required: - query - type properties: query: type: string description: The search query. sources: type: array items: $ref: '#/components/schemas/WebSearchSource' description: The sources used in the search. type: type: string enum: - search - type: object description: Action type "open_page" - Opens a specific URL from search results. required: - url - type properties: type: type: string enum: - open_page url: type: string description: The URL of the page to open. - type: object description: 'Action type "find": Searches for a pattern within a loaded page.' required: - source - pattern - type properties: pattern: type: string description: The pattern or text to search for within the page. source: $ref: '#/components/schemas/WebSearchSource' description: The source of the page to search in. type: type: string enum: - find ListEmbeddingModelsResponse: type: object required: - models properties: models: type: array items: $ref: '#/components/schemas/EmbeddingModel' description: Array of available embedding models. FileSearchCall: type: object description: The output of a web search tool call. required: - type - queries - results properties: id: type: string description: The unique ID of the file search tool call. queries: type: array items: type: string description: The queries used to search for files. results: type: array items: $ref: '#/components/schemas/FileSearchResult' description: The results of the file search tool call. status: type: string description: The status of the file search tool call. type: type: string description: The type of the file search tool call. Always `file_search_call`. VideoError: type: object description: Structured error returned when video generation fails. required: - code - message properties: code: $ref: '#/components/schemas/VideoErrorCode' description: 'Machine-readable error code indicating the type of failure. See `VideoErrorCode` for all possible values.' message: type: string description: Human-readable error message describing the failure. VideoGenerationModel: type: object description: Details of a video generation model required: - id - fingerprint - created - object - owned_by - version - input_modalities - output_modalities - aliases properties: aliases: type: array items: type: string description: Alias ID(s) of the model that user can use in a request's model field. created: type: integer format: int64 description: Model creation time in Unix timestamp. fingerprint: type: string description: Fingerprint of the xAI system configuration hosting the model. id: type: string description: Model ID. input_modalities: type: array items: type: string description: The input modalities supported by the model (e.g. "text", "image"). object: type: string description: The object type, which is always `"model"`. output_modalities: type: array items: type: string description: The output modalities supported by the model (e.g. "video"). owned_by: type: string description: Owner of the model. version: type: string description: Version of the model. EmbeddingRequest: type: object properties: dimensions: type: - integer - 'null' format: int32 description: The number of dimensions the resulting output embeddings should have. encoding_format: type: - string - 'null' description: The format to return the embeddings in. Can be either `float` or `base64`. input: $ref: '#/components/schemas/EmbeddingInput' description: Input text to embed, encoded as a string or list of tokens. To embed multiple inputs in a single request, pass a list of strings or list of token lists. The total tokens in the input must not exceed the context window for the model and cannot be an empty string. If the input is a list, the maximum length of the list is 128. model: type: string description: ID of the model to use. example: v1 preview: type: - boolean - 'null' description: Flag to use the new format of the API. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. ImageResolution: type: string description: 'Resolution for image generation. Only supported by grok-imagine models.' enum: - 1k - 2k SearchSource: oneOf: - type: object required: - type properties: excluded_x_handles: type: - array - 'null' items: type: string description: 'List of X handles to exclude from the search results. X posts returned will not include any posts authored by these handles.' included_x_handles: type: - array - 'null' items: type: string description: ' NOTE: `included_x_handles` and `x_handles` are the same parameter. `included_x_handles` is the new name but we keep both for backward compatibility. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`.' post_favorite_count: type: - integer - 'null' format: int32 description: The minimum favorite count of the X posts to consider. post_view_count: type: - integer - 'null' format: int32 description: The minimum view count of the X posts to consider. type: type: string enum: - x x_handles: type: - array - 'null' items: type: string description: 'DEPRECATED in favor of `included_x_handles`. Use `included_x_handles` instead. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`.' deprecated: true - type: object required: - type properties: allowed_websites: type: - array - 'null' items: type: string description: 'List of website to allow in the search results. This parameter act as a whitelist where only those websites can be selected. A maximum of 5 websites can be selected. Note 1: If no relevant information is found on those websites, the number of results returned might be smaller than `max_search_results`. Note 2: This parameter cannot be set with `excluded_websites`.' example: - wikipedia.com maxItems: 5 country: type: - string - 'null' format: iso3166-1-alpha-2 description: 'ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See .' example: BE excluded_websites: type: - array - 'null' items: type: string description: 'List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. Note 2: This parameter cannot be set with `allowed_websites`' example: - wikipedia.com maxItems: 5 safe_search: type: - boolean - 'null' description: If set to true, mature content won't be considered during the search. Default to `true`. type: type: string enum: - web - type: object required: - type properties: country: type: - string - 'null' format: iso3166-1-alpha-2 description: 'ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See .' example: BE excluded_websites: type: - array - 'null' items: type: string description: 'List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded.' example: - foxnews.com maxItems: 5 safe_search: type: - boolean - 'null' description: If set to true, mature content won't be considered during the search. Default to `true`. type: type: string enum: - news - type: object required: - links - type properties: links: type: array items: type: string description: Links of the RSS feeds. example: - https://status.x.ai/feed.xml maxItems: 1 minItems: 1 type: type: string enum: - rss MessageMetadata: type: object properties: user_id: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. ModelResponseConfiguration: type: object properties: format: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelResponseFormat' description: 'An object specifying the format that the model must output. Specify `{ "type": "json_object" }` for JSON output, or `{ "type": "json_schema", "json_schema": {...} }` for structured outputs. If `{ \"type\": \"text\" }`, the model will return a text response.' SearchParameters: type: object description: Parameters to control realtime data. properties: from_date: type: - string - 'null' format: date description: 'Date from which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-06-24' max_search_results: type: - integer - 'null' format: int32 description: Maximum number of search results to use. default: 15 maximum: 30 minimum: 1 mode: type: - string - 'null' description: 'Choose the mode to query realtime data: * `off`: no search performed and no external will be considered. * `on` (default): the model will search in every sources for relevant data. * `auto`: the model choose whether to search data or not and where to search the data.' default: auto example: auto return_citations: type: - boolean - 'null' description: Whether to return citations in the response or not. default: true sources: type: - array - 'null' items: $ref: '#/components/schemas/SearchSource' description: List of sources to search in. If no sources specified, the model will look over the web and X by default. to_date: type: - string - 'null' format: date description: 'Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-12-24' FunctionToolCall: type: object description: A tool call to run a function. required: - arguments - call_id - name - type properties: arguments: type: string description: The arguments to pass to the function, as a JSON string. call_id: type: string description: The unique ID of the function tool call generated by the model. id: type: string description: The unique ID of the function tool call. name: type: string description: The name of the function. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: 'The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls.' OutputMessage: type: object description: An output message from the model. required: - content - role - type properties: content: type: array items: $ref: '#/components/schemas/OutputMessageContent' description: Content of the output message. id: type: string description: The unique ID of the output message. role: type: string description: The role of the output message, which can be `assistant` or `tool`. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The type of the output message, which is always `message`. SearchResponse: type: object description: SearchResponse defines the response to a search request. required: - matches properties: matches: type: array items: $ref: '#/components/schemas/SearchMatch' description: The search matches. Usage: type: object required: - prompt_tokens - completion_tokens - total_tokens - prompt_tokens_details - completion_tokens_details - num_sources_used - cost_in_usd_ticks properties: completion_tokens: type: integer format: int32 description: Total completion token used. completion_tokens_details: $ref: '#/components/schemas/CompletionUsageDetail' description: Breakdown of completion token usage of different types. cost_in_usd_ticks: type: integer format: int64 description: 'Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10''000''000''000 ticks in one *dollar*.' num_sources_used: type: integer format: int32 description: Number of individual live search source used. prompt_tokens: type: integer format: int32 description: Total prompt token used. prompt_tokens_details: $ref: '#/components/schemas/PromptUsageDetail' description: Breakdown of prompt token usage of different types. total_tokens: type: integer format: int32 description: Total token used, the sum of prompt token and completion token amount. GroupBy: type: object description: Group search results by metadata key(s) and keep top-k per group. required: - keys properties: aggregate: oneOf: - type: 'null' - $ref: '#/components/schemas/GroupByAggregate' description: Aggregation function per group. Defaults to MinK(k=1, keys=["#score"]). keys: type: array items: type: string description: 'Metadata key(s) to group results by (e.g. "category", "department"). At least one key is required.' InputTokensDetails: type: object required: - cached_tokens properties: cached_tokens: type: integer format: int32 description: Token cached by xAI from previous requests and reused for this request. WebSearchOptions: type: object properties: filters: description: Only included for compatibility. search_context_size: type: - string - 'null' description: This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`. default: medium example: medium user_location: description: Only included for compatibility. SampleRequest: type: object description: (Legacy) Request for `/v1/completions` endpoint properties: best_of: type: - integer - 'null' format: int32 description: (Unsupported) Generates multiple completions internally and returns the top-scoring one. Not functional yet. echo: type: - boolean - 'null' description: Option to include the original prompt in the response along with the generated completion. frequency_penalty: type: - number - 'null' format: float description: (Unsupported) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. logit_bias: type: - object - 'null' description: (Unsupported) Accepts a JSON object that maps tokens to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. additionalProperties: type: number format: float propertyNames: type: integer format: int32 logprobs: type: - boolean - 'null' description: Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the logprob of the sampled token, so there may be up to `logprobs+1` elements in the response. max_tokens: type: - integer - 'null' format: int32 description: Limits the number of tokens that can be produced in the output. Ensure the sum of prompt tokens and `max_tokens` does not exceed the model's context limit. model: type: string description: Specifies the model to be used for the request. n: type: - integer - 'null' format: int32 description: Determines how many completion sequences to produce for each prompt. Be cautious with its use due to high token consumption; adjust `max_tokens` and stop sequences accordingly. presence_penalty: type: - number - 'null' format: float description: (Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. prompt: $ref: '#/components/schemas/SampleContent' description: Input for generating completions, which can be a string, list of strings, token list, or list of token lists. `<|endoftext|>` is used as a document separator, implying a new context start if omitted. seed: type: - integer - 'null' format: int32 description: If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend. stop: type: - array - 'null' items: type: string description: (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. stream: type: - boolean - 'null' description: 'Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.' stream_options: oneOf: - type: 'null' - $ref: '#/components/schemas/StreamOptions' description: 'Options for streaming response. Only set this when you set `stream: true`.' suffix: type: - string - 'null' description: (Unsupported) Optional string to append after the generated text. temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. default: 1 example: 0.2 maximum: 2 minimum: 0 top_p: type: - number - 'null' format: float description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. ListImageGenerationModelsResponse: type: object required: - models properties: models: type: array items: $ref: '#/components/schemas/ImageGenerationModel' description: Array of available image generation models. IncompleteDetails: oneOf: - type: object required: - reason properties: reason: type: string enum: - max_output_tokens - type: object required: - reason properties: reason: type: string enum: - max_prompt_tokens - type: object required: - reason properties: reason: type: string enum: - max_time_limit description: Details about why a response is incomplete. ReasoningConfiguration: type: object properties: effort: type: - string - 'null' description: Constrains how hard a reasoning model thinks before responding. Possible values are `low` (uses fewer reasoning tokens), `medium` and `high` (uses more reasoning tokens). default: medium generate_summary: type: - string - 'null' description: Only included for compatibility. summary: type: - string - 'null' description: A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`. MessageResponseContent: oneOf: - type: object description: Text response from the model. required: - text - type properties: text: type: string type: type: string enum: - text - type: object description: Thinking response for the model required: - signature - thinking - type properties: signature: type: string description: Signature of the content thinking: type: string description: Thinking content type: type: string enum: - thinking - type: object description: Redacted thinking response for the model required: - data - type properties: data: type: string description: Signature of the content type: type: string enum: - redacted_thinking - type: object description: Request by the model to invoke a tool call. required: - id - name - input - type properties: id: type: string description: Tool call ID. input: description: Input to the tool call follwing the `input_schema`. name: type: string description: Name of the tool call to be used. type: type: string enum: - tool_use TokenLogProb: type: object required: - token - logprob - top_logprobs properties: bytes: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: The ASCII encoding of the output character. logprob: type: number format: float description: The log probability of returning this token. token: type: string description: The token. top_logprobs: type: array items: $ref: '#/components/schemas/TopLogProb' description: An array of the most likely tokens to return at this token position. DocumentsSource: type: object description: DocumentsSource defines the source of documents to search over. required: - collection_ids properties: collection_ids: type: array items: type: string description: The collection IDs to search in. rag_pipeline: oneOf: - type: 'null' - $ref: '#/components/schemas/RagPipeline' description: Which RAG pipeline to use. Defaults to `chroma_db` when unset. FunctionToolCallOutput: type: object description: The output of a function tool call. required: - call_id - output - type properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: The output of the function tool call, as a JSON string. type: type: string description: The type of the function tool call, which is always `function_call_output`. ModelInputContent: oneOf: - type: string description: Text input. - type: array items: $ref: '#/components/schemas/ModelInputContentItem' description: A list of input items to the model. Can include text and images. TokenizeResponse: type: object required: - token_ids properties: token_ids: type: array items: $ref: '#/components/schemas/TokenizeResponseToken' description: A list of tokens. ImageUrl: type: object description: 'Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.' properties: file_id: type: - string - 'null' description: 'File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.' url: type: string description: 'Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.' StartDeferredResponse: type: object description: Response for starting a deferred operation. required: - request_id properties: request_id: type: string description: A unique request ID to poll for the result. ToolResultContent: oneOf: - type: string description: Plain text content. - type: array items: $ref: '#/components/schemas/ToolResultContentBlock' description: An array of content blocks (text, image, etc.). description: 'Content of a tool_result block. The Anthropic SDK may send this as either a plain string or an array of typed content blocks (e.g. `[{"type": "text", "text": "..."}]`).' SemanticRetrieval: type: object description: Document search using semantic similarity (dense embeddings). properties: reranker: oneOf: - type: 'null' - $ref: '#/components/schemas/RerankerModel' description: Optional, but always used when doing search across multiple collections. SampleChoice: type: object required: - index - text - finish_reason properties: finish_reason: type: string description: Finish reason. `"stop"` means the inference has reached a model-defined or user-supplied stop sequence in `stop`. `"length"` means the inference result has reached models' maximum allowed token length or user defined value in `max_tokens`. `"end_turn"` or `null` in streaming mode when the chunk is not the last. index: type: integer format: int32 description: Index of the choice. text: type: string description: Text response. ModelResponseFormat: oneOf: - type: object description: Specify text response format, always `"text"`. required: - type properties: type: type: string enum: - text - type: object description: Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this. required: - type properties: type: type: string enum: - json_object - type: object description: Specify json_schema response format with a given schema. Type is always `"json_schema"`. required: - schema - type properties: description: type: - string - 'null' description: Only included for compatibility. name: type: - string - 'null' description: Only included for compatibility. schema: description: A json schema representing the desired response schema. strict: type: - boolean - 'null' description: Only included for compatibility. type: type: string enum: - json_schema description: Response format parameter for structured outputs. MessageToolInputSchema: type: object required: - type - properties properties: properties: description: JSON-object of the tool input schema. required: type: - array - 'null' items: type: string description: Required properties of the tool input schema, if any. type: type: string description: Type of the schema. This is always `"object"`. SearchMatch: type: object description: SearchMatch defines a single match from a search request. required: - file_id - chunk_id - chunk_content - score - collection_ids - fields properties: chunk_content: type: string description: The chunk content. chunk_id: type: string description: The chunk ID. collection_ids: type: array items: type: string description: The collection ID(s). fields: type: object description: Metadata fields belonging to the document of this chunk. additionalProperties: type: string propertyNames: type: string file_id: type: string description: The document ID. page_number: type: integer format: int32 description: The dominant page number this chunk belongs to (0 for single-page docs). score: type: number format: float description: The relevance score. Embedding: type: object required: - index - embedding - object properties: embedding: $ref: '#/components/schemas/EmbeddingContent' description: Embedding content. index: type: integer format: int32 description: Index of the embedding object in the data list. object: type: string description: The object type, which is always `"embedding"`. CustomToolCall: type: object description: The output of a custom tool call. required: - call_id - name - type - id properties: call_id: type: string description: The unique ID of the function tool call generated by the model. id: type: string description: The status of the custom tool call. input: type: string description: The unique ID of the custom tool call, name: type: string description: An identifier used to map this custom tool call to a tool call output. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The input for the custom tool call generated by the model. GroupByAggregate: oneOf: - type: object description: Keep the k records with the smallest values (best scores). required: - min_k properties: min_k: type: object description: Keep the k records with the smallest values (best scores). required: - keys - k properties: k: type: integer format: int32 description: Number of records to keep per group. Must be >= 1. keys: type: array items: type: string description: Key(s) to sort by within each group. Use "#score" for relevance score. - type: object description: Keep the k records with the largest values. required: - max_k properties: max_k: type: object description: Keep the k records with the largest values. required: - keys - k properties: k: type: integer format: int32 description: Number of records to keep per group. Must be >= 1. keys: type: array items: type: string description: Key(s) to sort by within each group. description: Aggregation function to apply within each group. SearchRequest: type: object description: SearchRequest defines the request to search for documents. required: - query - source properties: filter: type: - string - 'null' description: 'Optional metadata filter string to apply to search results. Uses AIP-160 filter syntax for querying document metadata. Supports comparison operators: `=`, `!=`, `>`, `>=`, `<`, `<=` Supports logical operators: `AND`, `OR` Supports range syntax: `field:10..20` (inclusive) Examples: `author = "John"` or `year > 2020 AND category = "finance"`' group_by: oneOf: - type: 'null' - $ref: '#/components/schemas/GroupBy' description: 'Optional group_by to diversify search results by metadata key(s). When set, results are grouped by the specified key(s) and only the top-k records per group are returned. Applied after ranking and filtering. Documents missing a group_by key are placed in a shared null group. Grouping is applied per-collection, not across the combined result set.' instructions: type: - string - 'null' description: User-defined instructions to be included in the search query. Defaults to generic search instructions. limit: type: - integer - 'null' format: int32 description: 'The number of chunks to return. Will always return the top matching chunks. Optional, defaults to 10.' query: type: string description: 'The query to search for which will be embedded using the same embedding model as the one used for the source to query.' ranking_metric: oneOf: - type: 'null' - $ref: '#/components/schemas/RankingMetric' description: 'Deprecated: Metric now comes from collection creation.' retrieval_mode: oneOf: - type: 'null' - $ref: '#/components/schemas/RetrievalMode' description: How to perform the document search. Defaults to hybrid retrieval. source: $ref: '#/components/schemas/DocumentsSource' description: The source to query. ChoiceMessage: type: object required: - role properties: content: type: - string - 'null' description: The content of the message. reasoning_content: type: - string - 'null' description: The reasoning trace generated by the model. refusal: type: - string - 'null' description: The reason given by model if the model is unable to generate a response. null if model is able to generate. role: type: string description: The role that the message belongs to, the response from model is always `"assistant"`. tool_calls: type: - array - 'null' items: $ref: '#/components/schemas/ToolCall' description: A list of tool calls asked by model for user to perform. ListModelsResponse: type: object required: - data - object properties: data: type: array items: $ref: '#/components/schemas/Model' description: A list of models with with minimalized information. object: type: string description: The object type of `data` field, which is always `"list"`. CodeInterpreterCall: type: object description: The output of a code interpreter tool call. required: - type - outputs properties: code: type: string description: The code of the code interpreter tool call. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: array items: $ref: '#/components/schemas/CodeInterpreterOutput' description: The outputs of the code interpreter tool call. status: type: string description: The status of the code interpreter tool call. type: type: string description: The type of the code interpreter tool call. Always `code_interpreter_call`. ToolResultContentBlock: oneOf: - type: object description: Text content block. required: - text - type properties: text: type: string description: The text content. type: type: string enum: - text - type: object description: Image content block. required: - source - type properties: source: $ref: '#/components/schemas/MessageImageContent' description: Image source. type: type: string enum: - image description: A single content block within a tool_result's array content. FunctionDefinition: type: object description: Definition of the tool call made available to the model. required: - name - parameters properties: description: type: - string - 'null' description: A description of the function to indicate to the model when to call it. name: type: string description: 'The name of the function. If the model calls the function, this name is used in the response.' parameters: description: 'A JSON schema describing the function parameters. The model _should_ follow the schema, however, this is not enforced at the moment.' strict: type: - boolean - 'null' description: Not supported. Only maintained for compatibility reasons. securitySchemes: bearerAuth: type: http scheme: bearer