#### Inference API

# Chat Completions

The Chat Completions API is the stateless, OpenAI-compatible predecessor of the [Responses API](/developers/rest-api-reference/inference/responses). New integrations should use Responses; see [Migrating from Chat Completions](/developers/model-capabilities/text/comparison).

***

## POST /v1/chat/completions

Create a chat response from text/image chat prompts. This is the endpoint for making requests to chat and image understanding models.

### Request Body

* `deferred` (boolean | null) — 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 | null) — (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 | null) — (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 | null) — 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 | null) — 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 | null) — \\\[DEPRECATED\\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of \`max\_completion\_tokens\`.

* `messages` (array\<object | object | object | object | object>) — A list of messages that make up the chat conversation. Different models support different message types, such as image and text.

* `model` (string) — Model name for the model to use. Obtainable from \<https://console.x.ai/team/default/models> or \<https://docs.x.ai/docs/models>.

* `n` (integer | null) — 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 | null) — If set to false, the model can perform maximum one tool call.

* `presence_penalty` (number | null) — (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 | null) — 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 | null) — Constrains how hard a reasoning model thinks before responding. Supported by some models; models that do not support it reject the request with an error. Possible values are \`none\` (disables reasoning completely), \`low\`, \`medium\`, \`high\` (uses the most reasoning tokens) and \`xhigh\`. The accepted values and the default used when unspecified vary per model. See the model's documentation page for details.

* `response_format` (object | object | object)

* `search_parameters` (object)

  * `from_date` (string | null) — Date from which to consider the results in ISO-8601 YYYY-MM-DD. See
    \<https://en.wikipedia.org/wiki/ISO\_8601>.

  * `max_search_results` (integer | null) — Maximum number of search results to use.

  * `mode` (string | null) — 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 | null) — Whether to return citations in the response or not.

  * `sources` (array | null) — List of sources to search in. If no sources specified, the model will look over the web and X by default.

  * `to_date` (string | null) — Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See
    \<https://en.wikipedia.org/wiki/ISO\_8601>.

* `seed` (integer | null) — 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")

* `stop` (array | null) — (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens.

* `stream` (boolean | null) — 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` (object)

  * `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 | null) — 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` (string | object)

* `tools` (array | null) — A list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.

* `top_logprobs` (integer | null) — 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 | null) — 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 | null) — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

* `web_search_options` (object)

  * `filters` (object) — Only included for compatibility.

  * `search_context_size` (string | null) — This field included for compatibility reason with OpenAI's API. It is mapped to \`max\_search\`.

  * `user_location` (object) — Only included for compatibility.

### Response Body

* `choices` (array\<object>, required) — A list of response choices from the model. The length corresponds to the \`n\` in request body (default to 1).

  * `finish_reason` (string | null) — 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` (object)

    * `content` (array | null) — An array the log probabilities of each output token returned.

  * `message` (object, required)

    * `content` (string | null) — The content of the message.

    * `reasoning_content` (string | null) — The reasoning trace generated by the model.

    * `refusal` (string | null) — 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` (array | null) — A list of tool calls asked by model for user to perform.

* `citations` (array | null) — 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` (array | null) — Files generated during the response (e.g., by the code execution tool).
  Only populated when \`code\_execution\_files\_output\` is included.

* `service_tier` ("default" | "priority", required) — Processing tier for a request. Determines scheduling priority and billing.

* `system_fingerprint` (string | null) — System fingerprint, used to indicate xAI system configuration changes.

* `usage` (object)

  * `completion_tokens` (integer, required) — Total completion token used.

  * `completion_tokens_details` (object, 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` (object, 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.

\*\*Request example:\*\*

```json
{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant that can answer questions and help with tasks."
    },
    {
      "role": "user",
      "content": "What is 101*3?"
    }
  ],
  "model": "latest"
}
```

\*\*Response example:\*\*

```json
{
  "id": "a3d1008e-4544-40d4-d075-11527e794e4a",
  "object": "chat.completion",
  "created": 1752854522,
  "model": "latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "101 multiplied by 3 is 303.",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 9,
    "total_tokens": 135,
    "prompt_tokens_details": {
      "text_tokens": 32,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 6
    },
    "completion_tokens_details": {
      "reasoning_tokens": 94,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "num_sources_used": 0
  },
  "system_fingerprint": "fp_3a7881249c"
}
```

***

## GET /v1/chat/deferred-completion/\{request\_id}

Tries to fetch a result for a previously-started deferred completion. Returns \`200 Success\` with the response body, if the request has been completed. Returns \`202 Accepted\` when the request is pending processing.

### Path Parameters

* `request_id` (string, required) — The deferred request id returned by a previous deferred chat request.

### Response Body

* `choices` (array\<object>, required) — A list of response choices from the model. The length corresponds to the \`n\` in request body (default to 1).

  * `finish_reason` (string | null) — 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` (object)

    * `content` (array | null) — An array the log probabilities of each output token returned.

  * `message` (object, required)

    * `content` (string | null) — The content of the message.

    * `reasoning_content` (string | null) — The reasoning trace generated by the model.

    * `refusal` (string | null) — 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` (array | null) — A list of tool calls asked by model for user to perform.

* `citations` (array | null) — 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` (array | null) — Files generated during the response (e.g., by the code execution tool).
  Only populated when \`code\_execution\_files\_output\` is included.

* `service_tier` ("default" | "priority", required) — Processing tier for a request. Determines scheduling priority and billing.

* `system_fingerprint` (string | null) — System fingerprint, used to indicate xAI system configuration changes.

* `usage` (object)

  * `completion_tokens` (integer, required) — Total completion token used.

  * `completion_tokens_details` (object, 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` (object, 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.

\*\*Response example:\*\*

```json
{
  "id": "335b92e4-afa5-48e7-b99c-b9a4eabc1c8e",
  "object": "chat.completion",
  "created": 1743770624,
  "model": "latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "101 multiplied by 3 is 303.",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 11,
    "total_tokens": 42,
    "prompt_tokens_details": {
      "text_tokens": 31,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_156d35dcaa"
}
```