{"openapi":"3.1.0","info":{"title":"xAI's REST API","description":"REST API for xAI compatible with other providers.","license":{"name":""},"version":"1.0.0"},"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":"\n\nHuman: Hello, how are you?\n\nAssistant:"}}},"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\nalways returns a `pagination_token`; pass it back as a query parameter\nto fetch the next page. The end of the list is reached when the\nreturned `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\nbe referenced by ID anywhere a `file_id` is accepted (e.g. chat\nattachments). Maximum file size: 50 MB. Files are kept until you\ndelete 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\ndoesn'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\n`GET /v1/files`, content download returns 404, and the ID can no longer\nbe 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\n`Content-Type` is `application/octet-stream`. Use this for the binary\npayload; 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?\"\n\nThis is a simple multiplication: 101 multiplied by 3.\n\nCalculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303.\n\nI should respond helpfully and directly, as per my system prompt: \"You are a helpful assistant that can answer questions and help with tasks.\"\n\nKeep the response concise and accurate. No need for extra fluff unless it adds value.\n\nFinal 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.\nThis 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.\nThis 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.\nThis 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\nsuccessfully the response contains the generated video URL. When the job fails\nthe response contains a structured `error` object with a machine-readable\n`code` and a human-readable `message`.\n\nBoth successful and failed completions return HTTP 200 — use the `status`\nfield (`\"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":{"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."}}},"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."}}},"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 <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.","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\nthe usage of `realtime_data_parameters` instead."}]}}},"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).\nOnly 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."}]}}},"ChatResponseChunk":{"type":"object","required":["id","object","created","model","choices"],"properties":{"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChoiceChunk"},"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. Only populated for the last chunk."},"created":{"type":"integer","format":"int64","description":"The chat completion creation time in Unix timestamp."},"id":{"type":"string","description":"A unique ID for the chat completion. Each chunk in a streaming response has the same ID."},"model":{"type":"string","description":"The model ID used to create chat completion.","example":"latest"},"object":{"type":"string","description":"The object type, which is always `\"chat.completion.chunk\"`."},"output_files":{"type":["array","null"],"items":{"$ref":"#/components/schemas/OutputFile"},"description":"Files generated during the response (e.g., by the code execution tool).\nOnly populated for the final chunk 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."}}},"ChoiceChunk":{"type":"object","required":["index","delta"],"properties":{"delta":{"$ref":"#/components/schemas/Delta","description":"Additional difference (delta) of the result."},"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."},"logprobs":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/LogProbs","description":"The log probabilities of each output token returned in the content of message."}]}}},"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."}}},"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`."}}},"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."}}}]},"CompactionOutputItem":{"type":"object","description":"A compaction item from a previous `/v1/responses/compact` call.\n\nAccepted as input in `/v1/responses` calls. Clients must treat\n`encrypted_content` as opaque — do not parse or depend on its\ninternal 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_<uuid>`)."},"type":{"type":"string","description":"The type of the item. Always `\"compaction\"`."}}},"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}}},"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\"`."}}},"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."}}},"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."},"ContentFormat":{"type":"string","description":"Format of the downloaded file content.","enum":["original","text"]},"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`."}}},"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."}}},"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."}}},"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`."}}},"Delta":{"type":"object","properties":{"content":{"type":["string","null"]},"images":{"type":["array","null"],"items":{"type":"string"},"description":"Images generated by the model."},"reasoning_content":{"type":["string","null"]},"role":{"type":["string","null"]},"tool_calls":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ToolCall"}}}},"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."}]}}},"DownloadFileContentParams":{"type":"object","description":"Query parameters for downloading file content.","properties":{"format":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ContentFormat","description":"Format of the downloaded content."}]}}},"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.\nFor 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.\nMutually exclusive with `image`. When multiple images are provided,\nrefer to them as \\<IMAGE_0\\>, \\<IMAGE_1\\>, 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`.\nOnly 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."}}},"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."}}},"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\"`."}}},"EmbeddingContent":{"oneOf":[{"type":"string","description":"Embedding in base64 string."},{"type":"array","items":{"type":"number","format":"float"},"description":"Embedding as an array of floats."}]},"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"}}}]},"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 <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."},"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."}}},"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."}}},"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."}]}}},"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."}}},"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).\nDefaults 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.\nInput video must be between 2 and 30 seconds long."}}},"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."}}},"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."}}},"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`."}}},"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.\nProto3 omits float fields with value 0.0; default to 0.0 when absent."},"text":{"type":"string","description":"The text of the file search result."}}},"Function":{"type":"object","required":["name","arguments"],"properties":{"arguments":{"type":"string"},"name":{"type":"string"}}},"FunctionCall":{"type":"object","required":["name","arguments"],"properties":{"arguments":{"type":"string","description":"Arguments available to the function."},"name":{"type":"string","description":"Name of the function."}}},"FunctionChoice":{"type":"object","description":"Function name.","required":["name"],"properties":{"name":{"type":"string"}}},"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\nresponse."},"parameters":{"description":"A JSON schema describing the function parameters. The model _should_ follow the schema,\nhowever, this is not enforced at the moment."},"strict":{"type":["boolean","null"],"description":"Not supported. Only maintained for compatibility reasons."}}},"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,\nand `\"web_search_call\"` or `\"x_search_call\"` or `\"code_interpreter_call\"` or `\"mcp_call\"` for server-side tool calls."}}},"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`."}}},"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`.\nDefaults to `auto` for automatically selecting the best ratio for the prompt.\nOnly 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`.\nOnly 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."}}},"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.\nAlso accepts `seconds` for OpenAI API compatibility.\nAccepts 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.\nIf provided, generates video with this image as the first frame.\nAlso 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\nreference-to-video (R2V). Optional for image-to-video (I2V) — when\nomitted, 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.\nWhen provided generates video using these images\nas 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."}}},"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."}}},"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."}]}}},"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.\nThe field will be true if the video respects moderation rules. Otherwise\nthe field will be false and the video url field will be empty."},"url":{"type":["string","null"],"description":"A url to the generated video."}}},"GetDeferredVideoRequest":{"type":"object","description":"Request to get deferred video result with a request ID.","required":["request_id"],"properties":{"request_id":{"type":"string","description":"The request ID returned by a previous video generation request."}}},"GetDeferredVideoResponse":{"type":"object","description":"Response for getting deferred video result.","required":["status"],"properties":{"response":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/VideoResponse","description":"The generated video response. Only present if status is \"done\" or \"failed\".\nWhen failed, the `error` field in VideoResponse describes the failure."}]},"status":{"type":"string","description":"Status of the deferred request: \"pending\", \"done\", or \"failed\"."}}},"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\").\nAt least one key is required."}}},"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."},"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."},"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.\nValid range is [1, 100]. Defaults to 1 when unset."}}},"ImageAspectRatio":{"type":"string","description":"Aspect ratio for image generation.\nOnly 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"]},"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."}}},"ImageResolution":{"type":"string","description":"Resolution for image generation.\nOnly supported by grok-imagine models.","enum":["1k","2k"]},"ImageUrl":{"type":"object","description":"Image input for generation and editing requests.\nAccepts 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`.\nThe 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).\nAlso accepts `image_url` for compatibility.\nRequired when `file_id` is not set."}}},"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."},"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."}}},"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."}]}}},"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 <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."},"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."}}},"ListEmbeddingModelsResponse":{"type":"object","required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddingModel"},"description":"Array of available embedding models."}}},"ListFilesParams":{"type":"object","description":"Parameters to control listing of files.","properties":{"after":{"type":["string","null"],"description":"Only included for compatibility. Use `pagination_token` instead."},"limit":{"type":["integer","null"],"format":"int32","description":"The maximum number of objects to be returned in a single response.","default":100,"example":100,"maximum":100,"minimum":1},"order":{"type":["string","null"],"description":"The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.","default":"desc"},"pagination_token":{"type":["string","null"],"description":"The pagination token returned by the previous list files request."},"sort_by":{"type":["string","null"],"description":"The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.","default":"created_at"}}},"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."}}},"ListImageGenerationModelsResponse":{"type":"object","required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/ImageGenerationModel"},"description":"Array of available image generation models."}}},"ListLanguageModelsResponse":{"type":"object","required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/LanguageModel"},"description":"Array of available language models."}}},"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\"`."}}},"ListVideoGenerationModelsResponse":{"type":"object","required":["models"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/VideoGenerationModel"},"description":"Array of available video generation models."}}},"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)."}}},"LogProbs":{"type":"object","properties":{"content":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TokenLogProb"},"description":"An array the log probabilities of each output token returned."}}},"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`."}}},"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.\nOne USD cent equals 100,000,000 ticks, so one US dollar equals\n10,000,000,000 ticks."}}},"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."},"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."}}},"MessageContent":{"oneOf":[{"type":"string","description":"Text prompt."},{"type":"array","items":{"$ref":"#/components/schemas/MessageContentPart"},"description":"An array of message content parts."}]},"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"]}}}]},"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."}}}]},"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."}}},"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}}},"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."}}},"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"]}}}]},"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."},"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\"`."}}},"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."}}},"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"}}},"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 <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>."},"object":{"type":"string","description":"The object type, which is always `\"model\"`."},"owned_by":{"type":"string","description":"Owner of the model."}}},"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."},"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."}]},"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).\n\nWhen set, the file content is provided directly in the request and does NOT need\nto be uploaded to the Files API first.\n\nExactly 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.\n\nSet this to reference a previously-uploaded file.\nExactly one of `file_id`, `file_data`, or `file_url` should be set."},"file_url":{"type":["string","null"],"description":"Public URL for a file attachment.\n\nWhen set, the file content is fetched from this URL.\nExactly one of `file_id`, `file_data`, or `file_url` should be set."},"filename":{"type":["string","null"],"description":"Filename for inline uploads.\n\nRequired 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"]}}}]},"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."}]},"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"}]}]},"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.\nIf not set, defaults to the server's global cap.\nThis 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 <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.","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."}}},"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.\nNot used at the moment. Just for OpenResponses compatibility.\nWhether 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."}}},"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."}]}}},"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."},"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\nwhere only those websites can be selected. A maximum of 5 websites can be selected.\n\nNote: 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\nthe 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\nsubdomains. A maximum of 5 websites can be excluded.\n\nNote: 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.\nFor 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\nsearch. Available values are `low`, `medium`, or `high`.\nFor 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.\nFor 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.\n\nNote: 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.\n\nNote: 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\n<https://en.wikipedia.org/wiki/ISO_8601>.","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\n<https://en.wikipedia.org/wiki/ISO_8601>.","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.\nFor 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.\nFor 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\nuploaded file IDs to make available to your code.\nFor 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."},"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."},"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:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich 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."}}},"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."}}},"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`."}}},"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"]}}}]},"OutputTokensDetails":{"type":"object","required":["reasoning_tokens"],"properties":{"reasoning_tokens":{"type":"integer","format":"int32","description":"Tokens generated by the model for reasoning."}}},"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)."}}},"RagPipeline":{"type":"string","enum":["chroma_db","es"]},"RankingMetric":{"type":"string","description":"Deprecated: Metric now comes from collection creation.","enum":["RANKING_METRIC_UNKNOWN","RANKING_METRIC_L2_DISTANCE","RANKING_METRIC_COSINE_SIMILARITY"]},"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`."}}},"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`."}}},"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`."}}},"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."}}},"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."}}},"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."},"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."},"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."}}},"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."}]},"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."}}},"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."}]}}},"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."}}},"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\n<https://en.wikipedia.org/wiki/ISO_8601>.","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:\n* `off`: no search performed and no external will be considered.\n* `on` (default): the model will search in every sources for relevant data.\n* `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\n<https://en.wikipedia.org/wiki/ISO_8601>.","example":"2024-12-24"}}},"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.\nUses AIP-160 filter syntax for querying document metadata.\nSupports comparison operators: `=`, `!=`, `>`, `>=`, `<`, `<=`\nSupports logical operators: `AND`, `OR`\nSupports range syntax: `field:10..20` (inclusive)\nExamples: `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).\nWhen set, results are grouped by the specified key(s) and only the\ntop-k records per group are returned. Applied after ranking and filtering.\nDocuments missing a group_by key are placed in a shared null group.\nGrouping 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.\nWill always return the top matching chunks.\nOptional, defaults to 10."},"query":{"type":"string","description":"The query to search for which will be embedded using the\nsame 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."}}},"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."}}},"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\nany 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.\n`included_x_handles` is the new name but we keep both for backward compatibility.\n\nX 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.\nX 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\nwhere only those websites can be selected. A maximum of 5 websites can be selected.\n\nNote 1: If no relevant information is found on those websites, the number of results\nreturned might be smaller than `max_search_results`.\n\nNote 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\nwill be considered. See <https://en.wikipedia.org/wiki/ISO_3166-2>.","example":"BE"},"excluded_websites":{"type":["array","null"],"items":{"type":"string"},"description":"List of website to exclude from the search results without protocol specification or\nsubdomains. A maximum of 5 websites can be excluded.\n\nNote 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\nwill be considered. See <https://en.wikipedia.org/wiki/ISO_3166-2>.","example":"BE"},"excluded_websites":{"type":["array","null"],"items":{"type":"string"},"description":"List of website to exclude from the search results without protocol specification or\nsubdomains. 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"]}}}]},"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."}]}}},"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."}}},"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`."}}},"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`."}}},"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."},"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\nand 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`."}}},"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."}}},"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."}}},"StartDeferredChatResponse":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","description":"A unique request ID for the chat response."}}},"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."}}},"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."}}},"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`."}}},"SystemMessageContent":{"oneOf":[{"type":"string","description":"Text content of system prompt."},{"type":"array","items":{"$ref":"#/components/schemas/SystemMessagePart"},"description":"An array of system prompt parts."}]},"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\"`."}}},"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."}}},"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."}}},"TokenizeResponse":{"type":"object","required":["token_ids"],"properties":{"token_ids":{"type":"array","items":{"$ref":"#/components/schemas/TokenizeResponseToken"},"description":"A list of tokens."}}},"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}}},"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."},"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\"`"}}},"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."},"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\nstring or an array of typed content blocks (e.g. `[{\"type\": \"text\", \"text\": \"...\"}]`)."},"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."},"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."}}},"UploadFileMultipartRequest":{"type":"object","description":"Multipart form fields accepted by `POST /v1/files`. The `expires_after`\nfield MUST appear before `file` in the multipart body when both are\npresent (the upload handler streams `file` straight to gRPC and cannot\nrewind 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\n3600 (1 hour) and 2592000 (30 days). If unset the file does not expire.\n\nAccepts either a plain integer or the OpenAI SDK deepObject form\n(`expires_after[anchor]=created_at` + `expires_after[seconds]=N`)\nas separate multipart fields. The anchor+seconds form must arrive\nbefore the `file` part."},"file":{"type":"string","format":"binary","description":"The file to upload. The filename from the multipart\n`Content-Disposition: filename=` header is recorded as the file's\n`filename`."},"purpose":{"type":["string","null"],"description":"Optional purpose label, accepted for OpenAI SDK compatibility. xAI\ndoes not enforce or interpret this field. Setting `\"assistants\"`\nis the conventional choice."}}},"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:\nTICKS_IN_USD_CENT: i64 = 100_000_000\nwhich 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."}}},"VideoAspectRatio":{"type":"string","description":"Aspect ratio for video generation.","enum":["1:1","16:9","9:16","4:3","3:4","3:2","2:3"]},"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.\nSee `VideoErrorCode` for all possible values."},"message":{"type":"string","description":"Human-readable error message describing the failure."}}},"VideoErrorCode":{"type":"string","description":"Machine-readable error codes for video generation failures.\n\nThese are the codes that can appear in `VideoError.code` when polling a\ndeferred video generation result. Authentication errors, model-not-found\nerrors, and rate-limit errors are returned synchronously as HTTP errors\nand never appear in `VideoError`.\n\nSerializes to/from snake_case strings (e.g. `\"invalid_argument\"`,\n`\"internal_error\"`) for JSON compatibility.","enum":["invalid_argument","permission_denied","failed_precondition","internal_error"]},"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."}}},"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."}}},"VideoResolution":{"type":"string","description":"Resolution for video generation.","enum":["480p","720p","1080p"]},"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.\nOnly 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).\n- When status is \"pending\": progress is between 0-99, indicating current completion.\n- When status is \"done\": progress is 100.\n- 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\"."}]}}},"VideoUrl":{"type":"object","description":"Video input for editing and extension requests.\nAccepts 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`.\nThe 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).\nThe video must have the `.mp4` file extension and be encoded with `.mp4` supported codecs such as H.265, H.264, AV1, etc.\nRequired when `file_id` is not set."}}},"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"]}}}]},"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.\nIncludes 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`."}}},"WebSearchFilters":{"type":"object","properties":{"allowed_domains":{"type":["array","null"],"items":{"type":"string"},"description":"List of website domains (without protocol specification or subdomains)\nto restrict search results to (e.g., [\"example.com\"]). A maximum of 5 websites can be allowed.\nUse this as a whitelist to limit results to only these specific sites; no other websites will\nbe considered. If no relevant information is found on these websites, the number of results\nreturned might be smaller than `max_search_results` set in `SearchParameters`. Note: This\nparameter 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\"]).\nUse this to prevent results from unwanted sites. A maximum of 5 websites can be excluded.\nThis parameter cannot be set together with `allowed_domains`.","example":["example.com"],"maxItems":5}}},"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."}}},"WebSearchSource":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The type of source."},"url":{"type":"string","description":"The URL of the source."}}},"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\"`."}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}