--- title: "Generates a response based on text or image prompts. The response ID can be used to retrieve the response later or to continue the conversation without repeating prior context. New responses will be stored for 30 days and then permanently deleted." method: POST path: "/v1/responses" tags: ["v1"] --- # Generates a response based on text or image prompts. The response ID can be used to retrieve the response later or to continue the conversation without repeating prior context. New responses will be stored for 30 days and then permanently deleted. `POST /v1/responses` ## Request body - ModelRequest — The request body for `/v1/responses` endpoint. - `background` boolean, nullable — (Unsupported) Whether to process the response asynchronously in the background. - `context_management` unknown[], nullable — Optional context-management directives (e.g. compaction). Parsed but not yet executed. - unknown - `include` string[], nullable — What additional output data to include in the response. Supported values include `reasoning.encrypted_content` (encrypted reasoning tokens) and tool-output options. OpenAI's `message.output_text.logprobs` is accepted for compatibility but silently ignored. - `input` union, required — Content of the input passed to a `/v1/response` request. - string — Text input. - ModelInputPart[] — A list of input items to the model. Can be of different types. - union - object — Message input to the model. - `content` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - … - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages. - `role` string, required — The role of the message. Possible values are `user`, `assistant`, `system` and `developer`. - `type` string, nullable — The type of the message, which is always `message`. - object — The model output from previous responses. - `content` OutputMessageContent[], required — Content of the output message. - union - … - `id` string — The unique ID of the output message. - `role` string, required — The role of the output message, which can be `assistant` or `tool`. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the output message, which is always `message`. - object — The model output from previous responses. - `arguments` string, required — The arguments to pass to the function, as a JSON string. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string — The unique ID of the function tool call. - `name` string, required — The name of the function. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls. - object — The model output from previous responses. - `content` ReasoningText[] — The reasoning text contents. - `text` string, required — Reasoning done by the model. - `type` string, required — The type of the object, which is always `reasoning_text`. - `encrypted_content` string, nullable — The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`. - `id` string — The unique ID of the reasoning content. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `summary` SummaryText[], required — The summarized reasoning text contents. - `text` string, required — Summary of the reasoning done by the model. - `type` string, required — The type of the object, which is always `summary_text`. - `type` string, required — The type of the object, which is always `reasoning`. - object — The model output from previous responses. - `action` union, required - object — Action type "search" - Performs a web search query. - … - object — Action type "open_page" - Opens a specific URL from search results. - … - object — Action type "find_in_page": Searches for a pattern within a loaded page. Wire shape mirrors OpenAI's `ActionFind` so the OpenAI Python SDK's typed `web_search_call.action` parses correctly — note the `find_in_page` tag (not `find`) and the flat `url` (not nested under a `source` field). - … - `id` string — The unique ID of the web search tool call. - `status` string — The status of the web search tool call. - `type` string, required — The type of the web search tool call. Always `web_search_call`. - object — The model output from previous responses. - `id` string — The unique ID of the file search tool call. - `queries` string[], required — The queries used to search for files. - `results` FileSearchResult[], required — The results of the file search tool call. - `file_id` string, required — The file ID of the file search result. - `filename` string, required — The filename of the file search result. - `score` number, double — The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent. - `text` string, required — The text of the file search result. - `status` string — The status of the file search tool call. - `type` string, required — The type of the file search tool call. Always `file_search_call`. - object — The model output from previous responses. - `code` string — The code of the code interpreter tool call. - `id` string — The unique ID of the code interpreter tool call. - `outputs` CodeInterpreterOutput[], required — The outputs of the code interpreter tool call. - union - … - `status` string — The status of the code interpreter tool call. - `type` string, required — The type of the code interpreter tool call. Always `code_interpreter_call`. - object — The model output from previous responses. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `error` string — The error message of the MCP tool call. - `id` string — The unique ID of the MCP tool call. - `name` string, required — The name of the tool that was run. - `output` string, required — The output of the MCP tool call. - `server_label` string, required — The label of the MCP server running the tool. - `status` string — The status of the MCP tool call. - `type` string, required — The type of the MCP tool call. Always `mcp_call`. - object — The model output from previous responses. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, required — The status of the custom tool call. - `input` string — The unique ID of the custom tool call, - `name` string, required — An identifier used to map this custom tool call to a tool call output. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The input for the custom tool call generated by the model. - object — The model output from previous responses. - `action` ShellCallAction, required — The shell commands and limits that describe how to run the tool call. - `commands` string[], required — The commands to run. - `max_output_length` integer, nullable — Optional maximum number of characters to return from each command. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the commands. - `type` string, nullable — The type of the action, which is always `exec`. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `environment` ShellEnvironment — The environment configuration for a shell tool. - `skills` LocalShellSkill[] — An optional list of skills available in the local environment. - … - `type` string, required — The type of the environment. Currently only `local` is supported. - `id` string — The unique ID of the shell call item. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the output item, which is always `shell_call`. - object — The model output from previous responses. - `id` string — The unique ID of the image generation tool call. - `prompt` string, nullable — The prompt used to generate the image. - `result` string, nullable — The generated image encoded in base64 (OpenAI-compatible: bare base64, no data-URL prefix), or `null` while the call is still in progress or has failed. The image format can be determined from the decoded magic bytes (typically JPEG or PNG). - `status` string — The status of the image generation tool call. One of `in_progress`, `generating`, `completed` or `failed`. - `type` 'image_generation_call', required — Type tag for [`ImageGenerationCall`]. Serializes as `"image_generation_call"`. A single-variant enum rather than a `String`: `ImageGenerationCall` lives in the untagged `ModelOutput` / `ModelInputPart` enums and every other field is defaulted or optional, so with a plain `String` type field the struct would match *any* JSON object carrying a `type` key — swallowing `function_call_output` (and similar) input items before their own variants are tried. - object — The output of a function call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - … - `type` string, required — The type of the function tool call, which is always `function_call_output`. - object — The output of a shell call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `max_output_length` integer, nullable — The maximum length of the shell command output. Generated by the model and should be passed back with the raw output. - `output` ShellCallOutputResult[], required — An array of shell call output contents. - `outcome` union, required — The outcome of a shell command execution. - … - `stderr` string — The standard error output that was captured. - `stdout` string — The standard output that was captured. - `type` string, required — The type of the output item, which is always `shell_call_output`. - object — A compaction item from a previous `/v1/responses/compact` call. - `encrypted_content` string, required — The encrypted content of the compacted conversation. - `id` string, nullable — The unique ID of the compaction item (e.g. `cmp_`). - `type` string, required — The type of the item. Always `"compaction"`. - `instructions` string, nullable — 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` boolean, nullable — 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. - `max_output_tokens` integer, nullable — Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. Defaults to 128,000 when unset; set a larger value to allow longer generations. - `max_turns` integer, nullable — Maximum number of agentic tool calling turns allowed for this request. If not set, defaults to the server's global cap. This parameter will be ignored for any non-agentic requests. - `metadata` unknown - `min_p` number, float, nullable — 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. - `model` string — Model name for the model to use. Obtainable from or . - `parallel_tool_calls` boolean, nullable — Whether to allow the model to run parallel tool calls. - `previous_response_id` string, nullable — The ID of the previous response from the model. - `prompt_cache_key` string, nullable — Plumbed to x-grok-conv-id for Open Responses compatibility, used for routing. - `reasoning` ReasoningConfiguration - `effort` string, nullable — Constrains how hard a reasoning model thinks before responding. Only supported by `grok-4.3`. Possible values are `none` (disables reasoning completely), `low` (this is the default if not specified), `medium` and `high` (uses the most reasoning tokens). - `generate_summary` string, nullable — Only included for compatibility. - `summary` string, nullable — 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`. - `reasoning_effort` string, nullable — reasoning_effort alternative to reasoning configuration. This is a non-standard field meant to ease user experience. We only look at this if the reasoning field is unset. - `search_parameters` SearchParameters — Parameters to control realtime data. - `from_date` string, date, nullable — Date from which to consider the results in ISO-8601 YYYY-MM-DD. See . - `max_search_results` integer, nullable — Maximum number of search results to use. - `mode` string, nullable — Choose the mode to query realtime data: * `off`: no search performed and no external will be considered. * `on` (default): the model will search in every sources for relevant data. * `auto`: the model choose whether to search data or not and where to search the data. - `return_citations` boolean, nullable — Whether to return citations in the response or not. - `sources` SearchSource[], nullable — List of sources to search in. If no sources specified, the model will look over the web and X by default. - union - object - `excluded_x_handles` string[], nullable — List of X handles to exclude from the search results. X posts returned will not include any posts authored by these handles. - `included_x_handles` string[], nullable — NOTE: `included_x_handles` and `x_handles` are the same parameter. `included_x_handles` is the new name but we keep both for backward compatibility. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`. - `post_favorite_count` integer, nullable — The minimum favorite count of the X posts to consider. - `post_view_count` integer, nullable — The minimum view count of the X posts to consider. - `type` 'x', required - `x_handles` string[], nullable — DEPRECATED in favor of `included_x_handles`. Use `included_x_handles` instead. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`. - object - `allowed_websites` string[], nullable — List of website to allow in the search results. This parameter act as a whitelist where only those websites can be selected. A maximum of 5 websites can be selected. Note 1: If no relevant information is found on those websites, the number of results returned might be smaller than `max_search_results`. Note 2: This parameter cannot be set with `excluded_websites`. - `country` string, iso3166-1-alpha-2, nullable — ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See . - `excluded_websites` string[], nullable — List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. Note 2: This parameter cannot be set with `allowed_websites` - `safe_search` boolean, nullable — If set to true, mature content won't be considered during the search. Default to `true`. - `type` 'web', required - object - `country` string, iso3166-1-alpha-2, nullable — ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See . - `excluded_websites` string[], nullable — List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. - `safe_search` boolean, nullable — If set to true, mature content won't be considered during the search. Default to `true`. - `type` 'news', required - object - `links` string[], required — Links of the RSS feeds. - `type` 'rss', required - `to_date` string, date, nullable — Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See . - `service_tier` 'default' | 'priority' — Processing tier for a request. Determines scheduling priority and billing. - `store` boolean, nullable — Whether to store the input message(s) and model response for later retrieval. - `stream` boolean, nullable — If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message. - `temperature` number, float, nullable — 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. - `text` ModelResponseConfiguration - `format` union — Response format parameter for structured outputs. - object — Specify text response format, always `"text"`. - `type` 'text', required - object — Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this. - `type` 'json_object', required - object — Specify json_schema response format with a given schema. Type is always `"json_schema"`. - `description` string, nullable — Only included for compatibility. - `name` string, nullable — Only included for compatibility. - `schema` unknown, required - `strict` boolean, nullable — Only included for compatibility. - `type` 'json_schema', required - `tool_choice` union — Parameter to control how model chooses the tools. - string — 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. - object - `name` string, required — Name of the function to use. - `type` string, required — Type is always `"function"`. - `tools` ModelTool[], nullable — A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`. - union — Definition of one tool that the model can call. - object — A function that the model can call. - `description` string, nullable — A description of the function to indicate to the model when to call it. - `name` string, required — The name of the function. If the model calls the function, this name is used in the response. - `parameters` unknown, required - `strict` boolean, nullable — Not supported. Only maintained for compatibility reasons. - `type` 'function', required - object — Search X. - `allowed_x_handles` string[], nullable — List of X Handles of the users from whom to consider the posts. Note: This parameter cannot be set with `excluded_x_handles`. - `enable_image_understanding` boolean, nullable — Enable image understanding during X search. - `enable_video_understanding` boolean, nullable — Enable video understanding during X search. - `excluded_x_handles` string[], nullable — List of X Handles of the users from whom to exclude the posts. Note: This parameter cannot be set with `allowed_x_handles`. - `from_date` string, date, nullable — Date from which to consider the results in ISO-8601 YYYY-MM-DD. See . - `to_date` string, date, nullable — Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See . - `type` 'x_search', required - object — Generate images from text prompts. - `action` string, nullable — Which image capabilities to expose to the model. One of `auto` (the default; both generation and editing), `generate` (text-to-image only), or `edit` (image editing only). - `type` 'image_generation', required - object — Search the knowledge bases. - `filters` unknown - `max_num_results` integer, nullable - `ranking_options` unknown - `type` 'file_search', required - `vector_store_ids` string[], required — List of vector store IDs to search within. - object — Execute code. - `container` unknown - `type` 'code_interpreter', required - object — A remote MCP server to use. - `allowed_tools` string[], nullable - `authorization` string, nullable - `connector_id` string, nullable - `headers` object, nullable - `require_approval` string, nullable - `server_description` string, nullable - `server_label` string, required - `server_url` string, required - `type` 'mcp', required - object — A local shell execution tool. - `environment` ShellEnvironment, required — The environment configuration for a shell tool. - `skills` LocalShellSkill[] — An optional list of skills available in the local environment. - `description` string, required — A description of what the skill does. - `name` string, required — The name of the skill. - `path` string, required — The path to the directory containing the skill (with a SKILL.md file). - `type` string, required — The type of the environment. Currently only `local` is supported. - `type` 'shell', required - `top_k` integer, nullable — Top-k sampling: only the `top_k` most probable tokens are considered at each sampling step. Disabled when unset. - `top_logprobs` integer, nullable — 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. - `top_p` number, float, nullable — 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. - `truncation` string, nullable — Not supported. Only maintained for compatibility reasons. - `user` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. ## Response `200` Success - ModelResponse — The response body for `/v1/responses` endpoint. - `background` boolean, required — OpenResponses compatibility fields. Not used at the moment. Just for OpenResponses compatibility. Whether to process the response asynchronously in the background. - `completed_at` integer, nullable — The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed. - `created_at` integer, required — The Unix timestamp (in seconds) for the response creation time. - `error` unknown - `frequency_penalty` number, float, required — (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` string, required — Unique ID of the response. - `incomplete_details` union — Details about why a response is incomplete. - object - `reason` 'max_output_tokens', required - object - `reason` 'max_prompt_tokens', required - object - `reason` 'max_time_limit', required - `instructions` string, nullable — A system (or developer) message inserted into the model's context. - `max_output_tokens` integer, nullable — Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. - `max_tool_calls` integer, nullable — The maximum number of tool calls allowed for this response. - `metadata` unknown, required - `model` string, required — Model name used to generate the response. - `object` string, required — The object type of this resource. Always set to `response`. - `output` ModelOutput[], required — The response generated by the model. - union - OutputMessage — An output message from the model. - `content` OutputMessageContent[], required — Content of the output message. - union - object — Text output. - … - object — Refusal. - … - `id` string — The unique ID of the output message. - `role` string, required — The role of the output message, which can be `assistant` or `tool`. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the output message, which is always `message`. - FunctionToolCall — A tool call to run a function. - `arguments` string, required — The arguments to pass to the function, as a JSON string. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string — The unique ID of the function tool call. - `name` string, required — The name of the function. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls. - Reasoning — The reasoning done by the model. - `content` ReasoningText[] — The reasoning text contents. - `text` string, required — Reasoning done by the model. - `type` string, required — The type of the object, which is always `reasoning_text`. - `encrypted_content` string, nullable — The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`. - `id` string — The unique ID of the reasoning content. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `summary` SummaryText[], required — The summarized reasoning text contents. - `text` string, required — Summary of the reasoning done by the model. - `type` string, required — The type of the object, which is always `summary_text`. - `type` string, required — The type of the object, which is always `reasoning`. - WebSearchCall — The output of a web search tool call. - `action` union, required - object — Action type "search" - Performs a web search query. - `query` string, required — The search query. - `sources` WebSearchSource[] — The sources used in the search. - … - `type` 'search', required - object — Action type "open_page" - Opens a specific URL from search results. - `type` 'open_page', required - `url` string, required — The URL of the page to open. - object — Action type "find_in_page": Searches for a pattern within a loaded page. Wire shape mirrors OpenAI's `ActionFind` so the OpenAI Python SDK's typed `web_search_call.action` parses correctly — note the `find_in_page` tag (not `find`) and the flat `url` (not nested under a `source` field). - `pattern` string, required — The pattern or text to search for within the page. - `type` 'find_in_page', required - `url` string, required — The URL of the page being searched within. - `id` string — The unique ID of the web search tool call. - `status` string — The status of the web search tool call. - `type` string, required — The type of the web search tool call. Always `web_search_call`. - FileSearchCall — The output of a web search tool call. - `id` string — The unique ID of the file search tool call. - `queries` string[], required — The queries used to search for files. - `results` FileSearchResult[], required — The results of the file search tool call. - `file_id` string, required — The file ID of the file search result. - `filename` string, required — The filename of the file search result. - `score` number, double — The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent. - `text` string, required — The text of the file search result. - `status` string — The status of the file search tool call. - `type` string, required — The type of the file search tool call. Always `file_search_call`. - CodeInterpreterCall — The output of a code interpreter tool call. - `code` string — The code of the code interpreter tool call. - `id` string — The unique ID of the code interpreter tool call. - `outputs` CodeInterpreterOutput[], required — The outputs of the code interpreter tool call. - union - object — The output of the code interpreter tool call. - … - object — The error of the code interpreter tool call. - … - `status` string — The status of the code interpreter tool call. - `type` string, required — The type of the code interpreter tool call. Always `code_interpreter_call`. - McpCall — The output of a MCP tool call. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `error` string — The error message of the MCP tool call. - `id` string — The unique ID of the MCP tool call. - `name` string, required — The name of the tool that was run. - `output` string, required — The output of the MCP tool call. - `server_label` string, required — The label of the MCP server running the tool. - `status` string — The status of the MCP tool call. - `type` string, required — The type of the MCP tool call. Always `mcp_call`. - CustomToolCall — The output of a custom tool call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, required — The status of the custom tool call. - `input` string — The unique ID of the custom tool call, - `name` string, required — An identifier used to map this custom tool call to a tool call output. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The input for the custom tool call generated by the model. - ShellCall — A shell command call emitted by the model for local execution. - `action` ShellCallAction, required — The shell commands and limits that describe how to run the tool call. - `commands` string[], required — The commands to run. - `max_output_length` integer, nullable — Optional maximum number of characters to return from each command. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the commands. - `type` string, nullable — The type of the action, which is always `exec`. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `environment` ShellEnvironment — The environment configuration for a shell tool. - `skills` LocalShellSkill[] — An optional list of skills available in the local environment. - `description` string, required — A description of what the skill does. - `name` string, required — The name of the skill. - `path` string, required — The path to the directory containing the skill (with a SKILL.md file). - `type` string, required — The type of the environment. Currently only `local` is supported. - `id` string — The unique ID of the shell call item. - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`. - `type` string, required — The type of the output item, which is always `shell_call`. - ImageGenerationCall — The output of an image generation tool call. - `id` string — The unique ID of the image generation tool call. - `prompt` string, nullable — The prompt used to generate the image. - `result` string, nullable — The generated image encoded in base64 (OpenAI-compatible: bare base64, no data-URL prefix), or `null` while the call is still in progress or has failed. The image format can be determined from the decoded magic bytes (typically JPEG or PNG). - `status` string — The status of the image generation tool call. One of `in_progress`, `generating`, `completed` or `failed`. - `type` 'image_generation_call', required — Type tag for [`ImageGenerationCall`]. Serializes as `"image_generation_call"`. A single-variant enum rather than a `String`: `ImageGenerationCall` lives in the untagged `ModelOutput` / `ModelInputPart` enums and every other field is defaulted or optional, so with a plain `String` type field the struct would match *any* JSON object carrying a `type` key — swallowing `function_call_output` (and similar) input items before their own variants are tried. - `parallel_tool_calls` boolean, required — Whether to allow the model to run parallel tool calls. - `presence_penalty` number, float, required — (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` string, nullable — The ID of the previous response from the model. - `prompt_cache_key` string, nullable — The cache key used for the prompt for routing to the correct engine. - `reasoning` ReasoningConfiguration - `effort` string, nullable — Constrains how hard a reasoning model thinks before responding. Only supported by `grok-4.3`. Possible values are `none` (disables reasoning completely), `low` (this is the default if not specified), `medium` and `high` (uses the most reasoning tokens). - `generate_summary` string, nullable — Only included for compatibility. - `summary` string, nullable — 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`. - `safety_identifier` string, nullable — A stable identifier used to help detect users of your application that may be violating xAI's usage policies. - `service_tier` 'default' | 'priority', required — Processing tier for a request. Determines scheduling priority and billing. - `status` string, required — Status of the response. One of `completed`, `in_progress` or `incomplete`. - `store` boolean, required — Whether to store the input message(s) and model response for later retrieval. - `temperature` number, float, nullable — 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. - `text` ModelResponseConfiguration, required - `format` union — Response format parameter for structured outputs. - object — Specify text response format, always `"text"`. - `type` 'text', required - object — Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this. - `type` 'json_object', required - object — Specify json_schema response format with a given schema. Type is always `"json_schema"`. - `description` string, nullable — Only included for compatibility. - `name` string, nullable — Only included for compatibility. - `schema` unknown, required - `strict` boolean, nullable — Only included for compatibility. - `type` 'json_schema', required - `tool_choice` union, required — Parameter to control how model chooses the tools. - string — 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. - object - `name` string, required — Name of the function to use. - `type` string, required — Type is always `"function"`. - `tools` ModelTool[], required — A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported. - union — Definition of one tool that the model can call. - object — A function that the model can call. - `description` string, nullable — A description of the function to indicate to the model when to call it. - `name` string, required — The name of the function. If the model calls the function, this name is used in the response. - `parameters` unknown, required - `strict` boolean, nullable — Not supported. Only maintained for compatibility reasons. - `type` 'function', required - object — Search X. - `allowed_x_handles` string[], nullable — List of X Handles of the users from whom to consider the posts. Note: This parameter cannot be set with `excluded_x_handles`. - `enable_image_understanding` boolean, nullable — Enable image understanding during X search. - `enable_video_understanding` boolean, nullable — Enable video understanding during X search. - `excluded_x_handles` string[], nullable — List of X Handles of the users from whom to exclude the posts. Note: This parameter cannot be set with `allowed_x_handles`. - `from_date` string, date, nullable — Date from which to consider the results in ISO-8601 YYYY-MM-DD. See . - `to_date` string, date, nullable — Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See . - `type` 'x_search', required - object — Generate images from text prompts. - `action` string, nullable — Which image capabilities to expose to the model. One of `auto` (the default; both generation and editing), `generate` (text-to-image only), or `edit` (image editing only). - `type` 'image_generation', required - object — Search the knowledge bases. - `filters` unknown - `max_num_results` integer, nullable - `ranking_options` unknown - `type` 'file_search', required - `vector_store_ids` string[], required — List of vector store IDs to search within. - object — Execute code. - `container` unknown - `type` 'code_interpreter', required - object — A remote MCP server to use. - `allowed_tools` string[], nullable - `authorization` string, nullable - `connector_id` string, nullable - `headers` object, nullable - `require_approval` string, nullable - `server_description` string, nullable - `server_label` string, required - `server_url` string, required - `type` 'mcp', required - object — A local shell execution tool. - `environment` ShellEnvironment, required — The environment configuration for a shell tool. - `skills` LocalShellSkill[] — An optional list of skills available in the local environment. - `description` string, required — A description of what the skill does. - `name` string, required — The name of the skill. - `path` string, required — The path to the directory containing the skill (with a SKILL.md file). - `type` string, required — The type of the environment. Currently only `local` is supported. - `type` 'shell', required - `top_logprobs` integer, required — An integer between 0 and 8 specifying the number of most likely tokens to return at each token position. - `top_p` number, float, nullable — 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. - `truncation` string, required — The truncation strategy to use for the model response. - `usage` ModelUsage - `context_details` ContextDetails — Token counts for the latest context window seen by the model. In the non-agentic path these mirror `input_tokens` / `output_tokens`. In the agentic path (multi-agents) these are reset on every step and reflect the most recent step's prompt and output sizes — useful for understanding how the live context window evolves across tool calls. Informational only; not used for billing. - `input_tokens` integer, required — Prompt tokens in the latest context (sourced from `SamplingUsage.context_prompt_tokens`). - `output_tokens` integer, required — Completion + reasoning tokens in the latest context (sourced from `SamplingUsage.context_output_tokens`). - `cost_in_nano_usd` integer, nullable — Cost in nano US dollars for this request. - `cost_in_usd_ticks` integer, nullable — Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10'000'000'000 ticks in one *dollar*. - `input_tokens` integer, required — Number of input tokens used. - `input_tokens_details` InputTokensDetails, required - `cached_tokens` integer, required — Token cached by xAI from previous requests and reused for this request. - `num_server_side_tools_used` integer, required — Number of server side tools used. - `num_sources_used` integer, required — Number of sources used (for live search). - `output_tokens` integer, required — Number of output tokens used. - `output_tokens_details` OutputTokensDetails, required - `reasoning_tokens` integer, required — Tokens generated by the model for reasoning. - `server_side_tool_usage_details` ServerSideToolUsageDetails - `code_interpreter_calls` integer, required — Number of code interpreter calls. - `document_search_calls` integer, required — Number of document search calls. - `file_search_calls` integer, required — Number of file search calls. - `image_generation_calls` integer, required — Number of image generation calls. - `mcp_calls` integer, required — Number of MCP calls. - `web_search_calls` integer, required — Number of web search calls. - `x_search_calls` integer, required — Number of X search calls. - `total_tokens` integer, required — Total tokens used. - `user` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. ## Other responses - `400` — Bad request. The request is invalid or an invalid API key is provided. - `422` — Unprocessable Entity. There are missing fields in the request body. --- [API](https://skmtc.net/x/apis/xai-s-rest-api.md) · [All operations](https://skmtc.net/x/apis/xai-s-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/x/xai-s-rest-api/versions/8f6014272113/schema)