GET
/v1/schemas/grok/chat/v1%2Fchat%2Fcompletions
Accept:
Request body
29 properties · 0 required · 20 $defs| property | type | description | constraints |
|---|---|---|---|
| deferred | any | 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 | any | (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. | -2 ≤ n ≤ 2 · format: float · default: 0 |
| guidelines | any | Per-category instructions for model output. See [`Guideline`]. Omitted requests leave this unset. A request whose guidelines cannot be applied, for example on a multi-agent model or with `stop`, fails with 400. | |
| logit_bias | any | (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 m… | |
| logprobs | any | 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 | any | 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 gener… | format: int32 |
| max_tokens | any | \[DEPRECATED\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`. | format: int32 |
| messages | Message[] | 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 | any | 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. | n ≥ 1 · format: int32 · default: 1 |
| parallel_tool_calls | any | If set to false, the model can perform maximum one tool call. | default: true |
| presence_penalty | any | (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. | -2 ≤ n ≤ 2 · format: float · default: 0 |
| prompt_cache_key | any | 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 | any | 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 | object | object | object | 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. | nullable |
| safety_identifier | any | 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-polic… | |
| search_parameters | SearchParameters | Deprecated: live search has been removed, and requests that set this field fail. Use the Agent Tools API instead: <https://docs.x.ai/developers/tools/overview>. | nullable |
| seed | any | 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` respons… | format: int32 |
| service_tier | enum | Processing tier. `"fast"` and `"priority"` are interchangeable: on models with a fast deployment both use it and its rates; otherwise both mean higher scheduling priority at a higher price. Valid: `"auto"`, `"priority"`, `"fast"`. | default | priority | fast · nullable |
| stop | any | (Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens. | |
| stream | any | 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 |
| stream_options | StreamOptions | Options for streaming response. Only set this when you set `stream: true`. | nullable |
| temperature | any | What sampling temperature to use, between 0 and 2. Values above 1 are sampled at 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. | 0 ≤ n ≤ 2 · format: float · default: 1 |
| tool_choice | string | object | 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 … | nullable |
| tools | any | 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 1000 functions are supported. | items ≤ 1000 |
| top_logprobs | any | 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 w… | 0 ≤ n ≤ 8 · format: int32 |
| top_p | any | 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 reco… | 0 < n ≤ 1 · format: float · default: 0.95 |
| user | any | A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. | |
| web_search_options | WebSearchOptions | Deprecated: live search has been removed, and requests that set this field fail. Use the Agent Tools API instead: <https://docs.x.ai/developers/tools/overview>. | nullable |
Validate a payload
before you spend tokensshell
$ curl -X POST https://modelschemas.com/v1/validate \
-d '{"provider":"grok","endpointId":"v1/chat/completions","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}