{ "openapi": "3.1.0", "info": { "title": "Grok 4.7 API", "version": "2026-10-10" }, "servers": [ { "url": "https://api.seedrouter.ai" } ], "paths": { "/v1/responses": { "post": { "operationId": "grok47_responses", "summary": "Create a Grok 4.7 responses response", "description": "Native xAI request format. Unknown and officially ignored parameters are discarded. Response-ID continuation, stored-response retrieval/deletion and deferred Chat are currently unavailable; preserve full history for stateless continuation. Failed requests are not charged.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The request body for `/v1/responses` endpoint.", "required": [ "model", "input" ], "properties": { "include": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "What additional output data to include in the response. Supported values include\n`reasoning.encrypted_content` (encrypted reasoning tokens) and tool-output options.\nOpenAI's `message.output_text.logprobs` is accepted for compatibility but silently ignored." }, "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." }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Max number of tokens that can be generated in a response. Only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to 128,000 when unset; set a larger value to allow longer generations.", "minimum": 1, "maximum": 1073741823, "default": 128000 }, "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, and for\nagentic SLOP requests that have neither a server-side tool nor a file\nattachment." }, "min_p": { "type": [ "number", "null" ], "format": "float", "description": "Min-p sampling: tokens whose probability is below `min_p` times the probability of the most likely token are excluded from sampling. Disabled when unset.", "maximum": 1, "minimum": 0 }, "model": { "type": "string", "enum": [ "grok-4.7" ] }, "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." } ] }, "reasoning_effort": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "xhigh", null ], "default": "high" }, "safety_identifier": { "type": [ "string", "null" ], "description": "Supplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-policy violation can be attributed to that user rather than to the API key." }, "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": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Processing tier. `\"fast\"` and `\"priority\"` are interchangeable: on models with a fast\ndeployment both use it and its rates; otherwise both mean higher scheduling priority at a\nhigher price. Valid: `\"auto\"`, `\"priority\"`, `\"fast\"`." } ] }, "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 350 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`.", "maxItems": 350 }, "top_k": { "type": [ "integer", "null" ], "format": "int32", "description": "Top-k sampling: only the `top_k` most probable tokens are considered at each sampling step. Disabled when unset.", "minimum": 1 }, "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." } } } } } }, "responses": { "200": { "description": "Complete response or server-sent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." } } } }, "/v1/chat/completions": { "post": { "operationId": "grok47_chat", "summary": "Create a Grok 4.7 chat response", "description": "Native xAI request format. Unknown and officially ignored parameters are discarded. Response-ID continuation, stored-response retrieval/deletion and deferred Chat are currently unavailable; preserve full history for stateless continuation. Failed requests are not charged.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 }, "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 128,000 when unset; set a larger value to allow longer generations.", "example": 8192, "minimum": 1, "maximum": 1073741823, "default": 128000 }, "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, "minimum": 1, "maximum": 1073741823 }, "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", "enum": [ "grok-4.7" ] }, "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 }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "A stable cache key for best-effort sticky routing / prompt-cache hits\nacross requests sharing a prompt prefix. Plumbed to `x-grok-conv-id`,\nsame as on `/v1/responses`." }, "reasoning_effort": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "xhigh", null ], "default": "high" }, "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." } ] }, "safety_identifier": { "type": [ "string", "null" ], "description": "Supplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-policy violation can be attributed to that user rather than to the API key." }, "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." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Processing tier. `\"fast\"` and `\"priority\"` are interchangeable: on models with a fast\ndeployment both use it and its rates; otherwise both mean higher scheduling priority at a\nhigher price. Valid: `\"auto\"`, `\"priority\"`, `\"fast\"`." } ] }, "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 350 functions are supported.", "maxItems": 350 }, "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." } ] } }, "required": [ "model", "messages" ] } } } }, "responses": { "200": { "description": "Complete response or server-sent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." } } } }, "/v1/messages": { "post": { "operationId": "grok47_messages", "summary": "Create a Grok 4.7 messages response", "description": "Native xAI request format. Unknown and officially ignored parameters are discarded. Response-ID continuation, stored-response retrieval/deletion and deferred Chat are currently unavailable; preserve full history for stateless continuation. Failed requests are not charged.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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.", "minimum": 1, "maximum": 1073741823 }, "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", "enum": [ "grok-4.7" ] }, "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 350 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 } }, "required": [ "model", "messages", "max_tokens" ] } } } }, "responses": { "200": { "description": "Complete response or server-sent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "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." } } }, "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. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.", "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 128,000 when unset; set a larger value to allow longer generations.", "example": 8192 }, "max_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "\\[DEPRECATED\\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`.", "example": 8192 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "A list of messages that make up the chat conversation. Different models support different message types, such as image and text." }, "model": { "type": "string", "description": "Model name for the model to use. Obtainable from or .", "example": "latest" }, "n": { "type": [ "integer", "null" ], "format": "int32", "description": "How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.", "default": 1, "example": 1, "minimum": 1 }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "If set to false, the model can perform maximum one tool call.", "default": true, "example": false }, "presence_penalty": { "type": [ "number", "null" ], "format": "float", "description": "(Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.", "default": 0, "maximum": 2, "minimum": -2 }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "A stable cache key for best-effort sticky routing / prompt-cache hits\nacross requests sharing a prompt prefix. Plumbed to `x-grok-conv-id`,\nsame as on `/v1/responses`." }, "reasoning_effort": { "type": [ "string", "null" ], "description": "Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model." }, "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." } ] }, "safety_identifier": { "type": [ "string", "null" ], "description": "Supplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-policy violation can be attributed to that user rather than to the API key." }, "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." }, "service_tier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Processing tier. `\"fast\"` and `\"priority\"` are interchangeable: on models with a fast\ndeployment both use it and its rates; otherwise both mean higher scheduling priority at a\nhigher price. Valid: `\"auto\"`, `\"priority\"`, `\"fast\"`." } ] }, "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 350 functions are supported.", "maxItems": 350 }, "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. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.", "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", "service_tier" ], "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." }, "service_tier": { "$ref": "#/components/schemas/ServiceTier", "description": "The processing tier used for this request." }, "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." } } }, "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`.", "enum": [ "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_`)." }, "type": { "type": "string", "description": "The type of the item. Always `\"compaction\"`.", "enum": [ "compaction" ] } } }, "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." }, "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": "Image prompt. An object `{url, detail}` on chat completions, or a string\nURL on Responses `input_image`." } ] }, "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`.\n`input_text` and `input_image` are accepted so a tool result can use the\nsame content items as `/v1/responses` `function_call_output`." } } }, "ContextDetails": { "type": "object", "description": "Token counts for the latest context window seen by the model.\n\nIn the non-agentic path these mirror `input_tokens` / `output_tokens`.\nIn the agentic path (multi-agents) these are reset on every step and\nreflect the most recent step's prompt and output sizes — useful for\nunderstanding how the live context window evolves across tool calls.\nInformational only; not used for billing.", "required": [ "input_tokens", "output_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int32", "description": "Prompt tokens in the latest context (sourced from\n`SamplingUsage.context_prompt_tokens`)." }, "output_tokens": { "type": "integer", "format": "int32", "description": "Completion + reasoning tokens in the latest context (sourced from\n`SamplingUsage.context_output_tokens`)." } } }, "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.", "enum": [ "custom_tool_call" ] } } }, "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`.", "enum": [ "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" } } }, "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": { "defer_loading": { "type": [ "boolean", "null" ], "description": "When true, the definition is hidden from the model's prompt but stays\ncallable, loaded via a `tool_search` step (`/v1/responses` only)." }, "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.", "enum": [ "function_call", "web_search_call", "x_search_call", "code_interpreter_call", "mcp_call" ] } } }, "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": { "$ref": "#/components/schemas/ModelInputContent", "description": "The output of the function tool call. Can be a plain string or a list\nof content items (`input_text`, `input_image`, `input_file`)." }, "type": { "type": "string", "description": "The type of the function tool call, which is always `function_call_output`.", "enum": [ "function_call_output" ] } } }, "ImageGenerationCall": { "type": "object", "description": "The output of an image generation tool call.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The unique ID of the image generation tool call." }, "prompt": { "type": [ "string", "null" ], "description": "The prompt used to generate the image." }, "result": { "type": [ "string", "null" ], "description": "The generated image encoded in base64 (OpenAI-compatible: bare\nbase64, no data-URL prefix), or `null` while the call is still in\nprogress or has failed. The image format can be determined from the\ndecoded magic bytes (typically JPEG or PNG)." }, "status": { "type": "string", "description": "The status of the image generation tool call. One of `in_progress`,\n`generating`, `completed` or `failed`." }, "type": { "oneOf": [ { "type": "string", "description": "Type tag for [`ImageGenerationCall`]. Serializes as\n`\"image_generation_call\"`.\n\nA single-variant enum rather than a `String`: `ImageGenerationCall` lives\nin the untagged `ModelOutput` / `ModelInputPart` enums and every other\nfield is defaulted or optional, so with a plain `String` type field the\nstruct would match *any* JSON object carrying a `type` key — swallowing\n`function_call_output` (and similar) input items before their own\nvariants are tried.", "enum": [ "image_generation_call" ] } ], "description": "The type of the image generation tool call. Always `image_generation_call`." } } }, "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." } } }, "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`.", "enum": [ "mcp_call" ] } } }, "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 350 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 not served from cache (Anthropic semantics)." }, "output_tokens": { "type": "integer", "format": "int32", "description": "Number of output tokens used" } } }, "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": { "anyOf": [ { "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": { "anyOf": [ { "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" } ] }, { "allOf": [ { "$ref": "#/components/schemas/ImageGenerationCall" } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchCall" } ] }, { "allOf": [ { "$ref": "#/components/schemas/ToolSearchOutput" } ] } ] }, "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. Supported values include\n`reasoning.encrypted_content` (encrypted reasoning tokens) and tool-output options.\nOpenAI's `message.output_text.logprobs` is accepted for compatibility but silently ignored." }, "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. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.", "default": false }, "max_output_tokens": { "type": [ "integer", "null" ], "format": "int32", "description": "Max number of tokens that can be generated in a response. Only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to 128,000 when unset; set a larger value to allow longer generations." }, "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, and for\nagentic SLOP requests that have neither a server-side tool nor a file\nattachment." }, "metadata": { "description": "Not supported. Only maintained for compatibility reasons." }, "min_p": { "type": [ "number", "null" ], "format": "float", "description": "Min-p sampling: tokens whose probability is below `min_p` times the probability of the most likely token are excluded from sampling. Disabled when unset.", "maximum": 1, "minimum": 0 }, "model": { "type": "string", "description": "Model name for the model to use. Obtainable from or .", "example": "latest" }, "parallel_tool_calls": { "type": [ "boolean", "null" ], "description": "Whether to allow the model to run parallel tool calls.", "default": true }, "previous_response_id": { "type": [ "string", "null" ], "description": "The ID of the previous response from the model." }, "prompt_cache_key": { "type": [ "string", "null" ], "description": "Plumbed to x-grok-conv-id for Open Responses compatibility, used for routing." }, "reasoning": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReasoningConfiguration", "description": "Reasoning configuration. Only for reasoning models." } ] }, "reasoning_effort": { "type": [ "string", "null" ], "description": "Non-standard alternative to `reasoning.effort` that accepts the same values. We only look at this if the reasoning field is unset." }, "safety_identifier": { "type": [ "string", "null" ], "description": "Supplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-policy violation can be attributed to that user rather than to the API key." }, "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": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ServiceTier", "description": "Processing tier. `\"fast\"` and `\"priority\"` are interchangeable: on models with a fast\ndeployment both use it and its rates; otherwise both mean higher scheduling priority at a\nhigher price. Valid: `\"auto\"`, `\"priority\"`, `\"fast\"`." } ] }, "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 350 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`.", "maxItems": 350 }, "top_k": { "type": [ "integer", "null" ], "format": "int32", "description": "Top-k sampling: only the `top_k` most probable tokens are considered at each sampling step. Disabled when unset.", "minimum": 1 }, "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. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.", "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. Only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls)." }, "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": { "oneOf": [ { "$ref": "#/components/schemas/ServiceTier", "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 350 tools are supported.", "maxItems": 350 }, "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.", "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.", "example": "2024-12-24" }, "type": { "type": "string", "enum": [ "x_search" ] } } }, { "type": "object", "description": "Generate images from text prompts.", "required": [ "type" ], "properties": { "action": { "type": [ "string", "null" ], "description": "Which image capabilities to expose to the model. One of `auto`\n(the default; both generation and editing), `generate`\n(text-to-image only), or `edit` (image editing only).", "example": "auto" }, "type": { "type": "string", "enum": [ "image_generation" ] } } }, { "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" ] }, "defer_loading": { "type": [ "boolean", "null" ], "description": "When true, this server's tool definitions are hidden from the\nmodel's prompt but stay callable, loaded via a `tool_search` step." }, "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" ] } } }, { "type": "object", "description": "Search over deferred tool definitions (server-side execution only).", "required": [ "type" ], "properties": { "execution": { "type": [ "string", "null" ], "description": "Where the search runs. Only `\"server\"` (or unset) is supported." }, "type": { "type": "string", "enum": [ "tool_search" ] } } } ], "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": { "context_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContextDetails", "description": "Token counts for the **latest context** sent to / produced by the\nmodel. For agentic responses this reflects the most recent step\nrather than the cumulative total. Informational only — not used\nfor billing." } ] }, "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`.", "enum": [ "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)." } } }, "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`.", "enum": [ "reasoning" ] } } }, "ReasoningConfiguration": { "type": "object", "properties": { "effort": { "type": [ "string", "null" ], "description": "Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model." }, "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`." } } }, "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." }, "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.", "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.", "example": "2024-12-24" } } }, "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 .", "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 .", "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" ] } } } ] }, "ServerSideToolUsageDetails": { "type": "object", "required": [ "web_search_calls", "x_search_calls", "x_posts_fetched", "x_users_fetched", "code_interpreter_calls", "file_search_calls", "mcp_calls", "document_search_calls", "image_generation_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." }, "image_generation_calls": { "type": "integer", "format": "int32", "description": "Number of image generation 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_posts_fetched": { "type": "integer", "format": "int32", "description": "Number of X posts fetched across all X search calls, including nested\nparent/quote posts and every post of a fetched thread, without\nde-duplication. X search is billed per fetched item." }, "x_search_calls": { "type": "integer", "format": "int32", "description": "Number of X search calls." }, "x_users_fetched": { "type": "integer", "format": "int32", "description": "Number of X user profiles fetched across all X search calls, without\nde-duplication. X search is billed per fetched item." } } }, "ServiceTier": { "type": "string", "description": "Processing tier for a request. `Fast` and `Priority` are interchangeable: the model's fast\ndeployment and its rates where configured, else higher scheduling priority at a higher price.", "enum": [ "auto", "default", "priority", "fast" ] }, "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`.", "enum": [ "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`.", "enum": [ "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." } } }, "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." } } }, "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." }, "ToolSearchCall": { "type": "object", "description": "A server-side tool search call made by the model.", "required": [ "id", "type" ], "properties": { "arguments": { "description": "The arguments of the tool search call: `{\"query\": ..., \"limit\": ...}`." }, "call_id": { "type": [ "string", "null" ], "description": "Always `null`; present for OpenAI compatibility." }, "execution": { "type": "string", "description": "Where the search runs. Always `server`." }, "id": { "type": "string", "description": "The unique ID of the tool search call item." }, "status": { "type": "string", "description": "Status of the item. One of `in_progress`, `completed` or\n`incomplete` (a failed search)." }, "type": { "oneOf": [ { "type": "string", "description": "Type tag for [`ToolSearchCall`]; a single-variant enum (not a `String`)\nfor the same untagged-enum disambiguation as [`ImageGenerationCallType`].", "enum": [ "tool_search_call" ] } ], "description": "The type of the item. Always `tool_search_call`." } } }, "ToolSearchOutput": { "type": "object", "description": "The tool definitions loaded by a completed tool search call.", "required": [ "id", "type" ], "properties": { "call_id": { "type": [ "string", "null" ], "description": "Always `null`; present for OpenAI compatibility." }, "execution": { "type": "string", "description": "Where the search ran. Always `server`." }, "id": { "type": "string", "description": "The unique ID of the tool search output item." }, "status": { "type": "string", "description": "Status of the item. Always `completed`." }, "tools": { "type": "array", "items": {}, "description": "The loaded tool definitions, echoed in the shape they were supplied in." }, "type": { "oneOf": [ { "type": "string", "description": "Type tag for [`ToolSearchOutput`]. Serializes as `\"tool_search_output\"`.\nSee [`ToolSearchCallType`] for why this is a single-variant enum.", "enum": [ "tool_search_output" ] } ], "description": "The type of the item. Always `tool_search_output`." } } }, "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." } } }, "Usage": { "type": "object", "required": [ "prompt_tokens", "completion_tokens", "total_tokens", "prompt_tokens_details", "completion_tokens_details", "num_sources_used" ], "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." }, "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." }, "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 token used, the sum of prompt token and completion token amount." } } }, "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_in_page\": Searches for a pattern within a loaded\npage. Wire shape mirrors OpenAI's `ActionFind` so the OpenAI Python\nSDK's typed `web_search_call.action` parses correctly — note the\n`find_in_page` tag (not `find`) and the flat `url` (not nested\nunder a `source` field).", "required": [ "url", "pattern", "type" ], "properties": { "pattern": { "type": "string", "description": "The pattern or text to search for within the page." }, "type": { "type": "string", "enum": [ "find_in_page" ] }, "url": { "type": "string", "description": "The URL of the page being searched within." } } } ] }, "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`.", "enum": [ "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\"`." } } } } } }