--- title: "Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models." method: POST path: "/v1/chat/completions" tags: ["v1"] --- # Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models. `POST /v1/chat/completions` ## Request body - ChatRequest — The chat request body for `/v1/chat/completions` endpoint. - `deferred` boolean, nullable — 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}`. - `frequency_penalty` number, float, nullable — (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. - `logit_bias` object, nullable — (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. - `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_completion_tokens` integer, nullable — 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. - `max_tokens` integer, nullable — \[DEPRECATED\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`. - `messages` Message[] — A list of messages that make up the chat conversation. Different models support different message types, such as image and text. - union — Chat message objects. - object — System message, usually instructions for the model to respond in a certain way. - `content` union, required — Content of each chat message. - string — Text prompt. - ContentPart[] — An array of content parts of different types, such as image, text or text file. - `file` FileRef - … - `image_url` ImageUrl — Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API. - … - `text` string, nullable — Text prompt. - `type` string, required — The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. - `role` 'system', required - object — User message, typically request from user for the model to answer. - `content` union, required — Content of each chat message. - string — Text prompt. - ContentPart[] — An array of content parts of different types, such as image, text or text file. - `file` FileRef - … - `image_url` ImageUrl — Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API. - … - `text` string, nullable — Text prompt. - `type` string, required — The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. - `role` 'user', required - object — Assistant role message, previous chat messages from the model. - `content` union — Content of each chat message. - string — Text prompt. - ContentPart[] — An array of content parts of different types, such as image, text or text file. - `file` FileRef - … - `image_url` ImageUrl — Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API. - … - `text` string, nullable — Text prompt. - `type` string, required — The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. - `reasoning_content` string, nullable — Assistant reasoning content. - `role` 'assistant', required - `tool_calls` ToolCall[], nullable — An array of tool calls available to the model on your machine. - `function` Function, required - `arguments` string, required - `name` string, required - `id` string, required — 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` integer, nullable — Index of the tool call. - `type` string, nullable — Type of tool call, should be `"function"` or `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` - object — Tool call role message, used to return function call result to the model. - `content` union, required — Content of each chat message. - string — Text prompt. - ContentPart[] — An array of content parts of different types, such as image, text or text file. - `file` FileRef - … - `image_url` ImageUrl — Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API. - … - `text` string, nullable — Text prompt. - `type` string, required — The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. - `role` 'tool', required - `tool_call_id` string, nullable — The ID of the tool call received from assistant message response. - object — Function call role message. Deprecated in favor of `{"role": "tool"}`. - `content` union, required — Content of each chat message. - string — Text prompt. - ContentPart[] — An array of content parts of different types, such as image, text or text file. - `file` FileRef - … - `image_url` ImageUrl — Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API. - … - `text` string, nullable — Text prompt. - `type` string, required — The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. - `role` 'function', required - `model` string — Model name for the model to use. Obtainable from or . - `n` integer, nullable — 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. - `parallel_tool_calls` boolean, nullable — If set to false, the model can perform maximum one tool call. - `presence_penalty` number, float, nullable — (Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `prompt_cache_key` string, nullable — A stable cache key for best-effort sticky routing / prompt-cache hits across requests sharing a prompt prefix. Plumbed to `x-grok-conv-id`, same as on `/v1/responses`. - `reasoning_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). - `response_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"`. - `json_schema` unknown, required - `type` 'json_schema', required - `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 . - `seed` integer, nullable — 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` 'default' | 'priority' — Processing tier for a request. Determines scheduling priority and billing. - `stop` string[], nullable — (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. - `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. - `stream_options` StreamOptions — Options available when using streaming response. - `include_usage` boolean, required — Set an additional chunk to be streamed before the `data: [DONE]` message. The other chunks will return `null` in `usage` field. - `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. - `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 - `function` FunctionChoice — Function name. - `name` string, required - `type` string, required — Type is always `"function"`. - `tools` Tool[], nullable — A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. - union — Definition of one tool that the model can call. - object - `function` FunctionDefinition, required — Definition of the tool call made available to the model. - `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 - `sources` SearchSource[], required - union - object - … - object - … - object - … - object - … - `type` 'live_search', required - `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. - `user` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. - `web_search_options` WebSearchOptions - `filters` unknown - `search_context_size` string, nullable — This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`. - `user_location` unknown ## Response `200` Success - ChatResponse — The chat response body for `/v1/chat/completions` endpoint. - `choices` Choice[], required — A list of response choices from the model. The length corresponds to the `n` in request body (default to 1). - `finish_reason` string, nullable — 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` integer, required — Index of the choice within the response choices, starting from 0. - `logprobs` LogProbs - `content` TokenLogProb[], nullable — An array the log probabilities of each output token returned. - `bytes` integer[], nullable — The ASCII encoding of the output character. - `logprob` number, float, required — The log probability of returning this token. - `token` string, required — The token. - `top_logprobs` TopLogProb[], required — An array of the most likely tokens to return at this token position. - `bytes` integer[], nullable — The ASCII encoding of the output character. - `logprob` number, float, required — The log probability of returning this token. - `token` string, required — The token. - `message` ChoiceMessage, required - `content` string, nullable — The content of the message. - `reasoning_content` string, nullable — The reasoning trace generated by the model. - `refusal` string, nullable — The reason given by model if the model is unable to generate a response. null if model is able to generate. - `role` string, required — The role that the message belongs to, the response from model is always `"assistant"`. - `tool_calls` ToolCall[], nullable — A list of tool calls asked by model for user to perform. - `function` Function, required - `arguments` string, required - `name` string, required - `id` string, required — 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` integer, nullable — Index of the tool call. - `type` string, nullable — Type of tool call, should be `"function"` or `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` - `citations` string[], nullable — List of all the external pages used by the model to answer. - `created` integer, required — The chat completion creation time in Unix timestamp. - `id` string, required — A unique ID for the chat response. - `model` string, required — Model ID used to create chat completion. - `object` string, required — The object type, which is always `"chat.completion"`. - `output_files` OutputFile[], nullable — Files generated during the response (e.g., by the code execution tool). Only populated when `code_execution_files_output` is included. - `file_id` string, required — The file ID from the Files API. Use this to download the file. - `name` string, required — The display name of the file. - `service_tier` 'default' | 'priority', required — Processing tier for a request. Determines scheduling priority and billing. - `system_fingerprint` string, nullable — System fingerprint, used to indicate xAI system configuration changes. - `usage` Usage - `completion_tokens` integer, required — Total completion token used. - `completion_tokens_details` CompletionUsageDetail, required — Details of completion usage. - `accepted_prediction_tokens` integer, required — The number of tokens in the prediction that appeared in the completion. - `audio_tokens` integer, required — Audio input tokens generated by the model. - `reasoning_tokens` integer, required — Tokens generated by the model for reasoning. - `rejected_prediction_tokens` integer, required — The number of tokens in the prediction that did not appear in the completion. - `cost_in_usd_ticks` integer, required — Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10'000'000'000 ticks in one *dollar*. - `num_sources_used` integer, required — Number of individual live search source used. - `prompt_tokens` integer, required — Total prompt token used. - `prompt_tokens_details` PromptUsageDetail, required — Details of prompt usage. - `audio_tokens` integer, required — Audio prompt token used. - `cached_tokens` integer, required — Token cached by xAI from previous requests and reused for this request. - `image_tokens` integer, required — Image prompt token used. - `text_tokens` integer, required — Total text prompt token used (cached + non-cached text tokens). - `total_tokens` integer, required — Total token used, the sum of prompt token and completion token amount. ## 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)