Grok 4

xai/grok-4 — a llm model by xAI. Call it through the gateway’s standard OpenAI-compatible door using the catalog slug; the full parameter schema is reproduced in full below.

Catalog slug	xai/grok-4
Kind	llm
Vendor	xAI

How to call

Through the Sociaro SDK / OpenAI-compatible door

from sociaro_ai import Sociaro

client = Sociaro(api_key="gw_live_...")   # base_url defaults to https://api.sociaro.com

resp = client.chat.completions.create(
    model="xai/grok-4",          # always the catalog slug
    messages=[{"role": "user", "content": "Hello"}],
    # any parameter from the schema below is passed through unchanged
)
print(resp.choices[0].message.content)

TypeScript: client.chat.completions.create({ model: "xai/grok-4", messages: [...] }) — see the TypeScript SDK.

Parameters — full schema

The complete, one-to-one API schema for this model, transcribed from the official source. Nothing omitted. Examples in the schema may use a representative model of the family — for this model use the slug xai/grok-4 as shown in How to call above.

Coverage map (gateway slugs → upstream)

Grok is reached through the gateway’s standard OpenAI-compatible chat door only: POST https://api.sociaro.com/v1/chat/completions, addressing the model by its catalog slug in the model field. There is no /xai gateway prefix and no separate Responses endpoint exposed to clients.

Gateway slug	Upstream	model value	Capabilities
xai/grok-4	xAI	xai/grok-4	text, vision (image understanding), tools/function-calling, reasoning (always-on, not configurable), Live Search
xai/grok-code-fast-1	xAI	xai/grok-code-fast-1	text, tools, reasoning, agentic coding (no vision)

Auth (all): Authorization: Bearer $SOCIARO_API_KEY header.

---

Critical per-model differences

xAI reasoning models (both grok-4 and grok-code-fast-1 are reasoning models):

• reasoning is always on and cannot be turned off for grok-4 and grok-code-fast-1. reasoning_effort is Only supported by grok-4.3 per the xAI source — for grok-4 / grok-code-fast-1 it is not a tuning knob. Possible values when it does apply: none (disables reasoning completely), low (default), medium, high.
• Fields the xAI source marks “Not supported by reasoning models” → ignored/discarded for grok-4 and grok-code-fast-1: frequency_penalty, presence_penalty (also explicitly “Not supported by grok-3”), stop.
• logit_bias is marked (Unsupported) at xAI globally.
• logprobs / top_logprobs: “Not supported by models grok-4.20 and newer; silently ignored”. For grok-4 / grok-code-fast-1 they may work partially — verify on a live response.
• Vision: grok-4 accepts image input (content as array with image_url); grok-code-fast-1 is text-only.
• reasoning_content is returned in the assistant message for reasoning models (the reasoning trace).

---

1. Chat Completions — POST https://api.sociaro.com/v1/chat/completions (grok-4, grok-code-fast-1)

The OpenAI-compatible chat door. This is the only contract for reaching Grok through the gateway: send to POST https://api.sociaro.com/v1/chat/completions with Authorization: Bearer $SOCIARO_API_KEY and set model to the catalog slug (xai/grok-4 or xai/grok-code-fast-1).

Request body shape

{
  "model": "xai/grok-4",
  "messages": [ { "role": "system|user|assistant|tool", "content": "..." } ],
  "...optional params..."
}

Full request parameter table (Chat Completions)

Parameters are listed in the order/spelling of the OpenAI-compatible chat schema.

Parameter	Type	Required	Default	Allowed values / range	Description
frequency_penalty	number | null	no	0	−2.0 … 2.0	(Not supported by reasoning models) Positive values penalize tokens by existing frequency, reducing verbatim repetition.
logit_bias	object | null	no	null	map tokenID→bias (−100 … 100)	(Unsupported at xAI) Bias added to logits before sampling; ±1 nudges, ±100 bans/forces a token.
logprobs	boolean | null	no	false	true / false	Return log-probabilities of output tokens. Not supported by grok-4.20 and newer (silently ignored).
max_completion_tokens	integer | null	no	null (generate up to context length)	>0	Upper bound on visible output tokens only (excludes reasoning / function-call tokens).
max_tokens	integer | null	no	null	>0	[DEPRECATED] Max tokens in the chat completion. Deprecated in favor of max_completion_tokens.
messages	array	yes	—	roles: system / user / assistant / tool; content = string or array of parts (text, image_url)	List of messages making up the conversation. Different models support different message types (e.g. text, image).
model	string	yes	—	catalog slug: xai/grok-4 or xai/grok-code-fast-1	Catalog slug of the model to use.
n	integer | null	no	1	≥1	How many completion choices to generate. Billed by total tokens across all choices; keep 1 to minimize cost.
parallel_tool_calls	boolean | null	no	true	true / false	If false, the model performs at most one tool call.
presence_penalty	number | null	no	0	−2.0 … 2.0	(Not supported by grok-3 and reasoning models) Positive values penalize tokens already present, encouraging new topics.
prompt_cache_key	string | null	no	null	string	Stable cache key for best-effort sticky routing / prompt-cache hits across requests sharing a prompt prefix.
reasoning_effort	string | null	no	low	none | low | medium | high	How hard a reasoning model thinks. Only supported by grok-4.3. none disables reasoning; low is the default; high uses the most reasoning tokens.
response_format	object	no	{"type":"text"}	{"type":"text"} | {"type":"json_object"} | {"type":"json_schema","json_schema":{...}}	Output format (text / JSON mode / Structured Outputs by schema).
search_parameters	object	no	—	see sub-fields	Live Search parameters (realtime web/X search).
search_parameters.from_date	string | null	no	null	ISO-8601 YYYY-MM-DD	Date from which to consider results.
search_parameters.max_search_results	integer | null	no	null	>0	Maximum number of search results to use.
search_parameters.mode	string | null	no	on	off | on | auto	Realtime-data mode: off = no search; on (default) = search all sources; auto = model decides whether/where to search.
search_parameters.return_citations	boolean | null	no	—	true / false	Whether to return citations in the response.
search_parameters.sources	array | null	no	web + X	list of sources	Sources to search. If unspecified, the model searches web and X by default.
search_parameters.to_date	string | null	no	null	ISO-8601 YYYY-MM-DD	Date up to which to consider results.
seed	integer | null	no	null	integer	Best-effort deterministic sampling for identical seed+params. Determinism not guaranteed (monitor system_fingerprint).
service_tier	string	no	default	default | priority	Processing tier; determines scheduling priority and billing.
stop	array | null	no	null	up to 4 stop sequences	(Not supported by reasoning models) Sequences where generation stops; stop text is not included in output.
stream	boolean | null	no	false	true / false	Stream partial deltas as SSE; terminated by data: [DONE].
stream_options	object	no	—	see sub-field	Streaming options (only when stream: true).
stream_options.include_usage	boolean	required (within the object)	—	true / false	Emit an extra chunk with usage before data: [DONE]; other chunks return null in usage.
temperature	number | null	no	1	0 … 2	Sampling temperature; higher = more random, lower = more deterministic.
tool_choice	string | object	no	auto if tools present, else none	none | auto | required | {"type":"function","function":{"name":"..."}}	Controls tool selection by the model.
tools	array | null	no	null	JSON-schema; max 128 functions	Tools the model may call. Currently only functions are supported.
top_logprobs	integer | null	no	null	0 … 8	Number of most-likely tokens to return per position (each with logprob). Requires logprobs: true. Not supported by grok-4.20+ (silently ignored).
top_p	number | null	no	1	0 … 1	Nucleus sampling. Recommended to alter this or temperature, not both.
user	string | null	no	null	string	Unique identifier for your end-user; helps xAI monitor and detect abuse.
web_search_options	object	no	—	see sub-fields	OpenAI-compatibility web-search wrapper.
web_search_options.filters	object	no	—	—	Only included for compatibility.
web_search_options.search_context_size	string | null	no	—	string	Included for OpenAI-API compatibility; mapped to max_search.
web_search_options.user_location	object	no	—	—	Only included for compatibility.

content structure (vision — grok-4 only)

Text prompt: "content": "text". Vision: content = array of parts:

"content": [
  { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,<...>", "detail": "high" } },
  { "type": "text", "text": "What is in this image?" }
]

• image_url.detail: auto (default) | low | high.
  • auto: system picks resolution (default, balances speed/detail).
  • low: low-res, faster, fewer tokens, may miss fine detail.
  • high: high-res, slower, more tokens, attends to nuance.
• image_url.url: data-URI or a public Internet URL.
• Image input limits: max size 20 MiB; supported types jpg/jpeg, png; no limit on number of images; any text/image input order is accepted.
• Conversations are stateless — prior turns must be replayed in messages to provide context.

Response body shape (chat.completion)

{
  "id": "...", "object": "chat.completion", "created": 0, "model": "...",
  "choices": [ { "index": 0, "message": {...}, "logprobs": {...}, "finish_reason": "stop" } ],
  "citations": [...],
  "output_files": [...],
  "service_tier": "default",
  "system_fingerprint": "fp_...",
  "usage": {...}
}

Response field	Type	Required	Description
id	string	yes	Unique ID for the chat response.
object	string	yes	Always "chat.completion".
created	integer	yes	Creation time (Unix timestamp).
model	string	yes	Model ID used.
choices[]	array	yes	Response choices; length matches n (default 1).
choices[].index	integer	yes	Choice index, starting at 0.
choices[].finish_reason	string | null	—	stop (stop sequence reached), length (max token length / max_tokens reached), end_turn or null (in streaming when chunk is not the last).
choices[].logprobs	object	—	Log-probabilities object.
choices[].logprobs.content	array | null	—	Array of log-probabilities of each output token returned.
choices[].message.role	string	yes	Always "assistant".
choices[].message.content	string | null	—	The text content of the message.
choices[].message.reasoning_content	string | null	—	Reasoning trace generated by the model (reasoning models).
choices[].message.refusal	string | null	—	Reason if the model cannot generate; null when it can.
choices[].message.tool_calls	array | null	—	Tool calls requested by the model for the user to perform.
citations	array | null	—	All external pages used by the model to answer (Live Search).
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”	yes	Processing tier; determines scheduling priority and billing.
system_fingerprint	string | null	—	System fingerprint indicating xAI system config changes.
usage.prompt_tokens	integer	yes	Total prompt tokens used.
usage.completion_tokens	integer	yes	Total completion tokens used.
usage.total_tokens	integer	yes	Sum of prompt + completion tokens.
usage.num_sources_used	integer	yes	Number of individual live-search sources used.
usage.prompt_tokens_details	object	yes	Prompt-usage breakdown.
usage.prompt_tokens_details.text_tokens	integer	yes	Total text prompt tokens (cached + non-cached).
usage.prompt_tokens_details.audio_tokens	integer	yes	Audio prompt tokens used.
usage.prompt_tokens_details.image_tokens	integer	yes	Image prompt tokens used.
usage.prompt_tokens_details.cached_tokens	integer	yes	Tokens served from xAI cache (reused from prior requests).
usage.completion_tokens_details	object	yes	Completion-usage breakdown.
usage.completion_tokens_details.reasoning_tokens	integer	yes	Tokens generated for reasoning.
usage.completion_tokens_details.audio_tokens	integer	yes	Audio output tokens generated by the model.
usage.completion_tokens_details.accepted_prediction_tokens	integer	yes	Predicted tokens that appeared in the completion.
usage.completion_tokens_details.rejected_prediction_tokens	integer	yes	Predicted tokens that did not appear in the completion.
usage.cost_in_usd_ticks	integer	yes	Accurate cost in USD ticks. TICKS_IN_USD_CENT = 100_000_000; i.e. 10,000,000,000 ticks = 1 dollar.

Minimal example

POST https://api.sociaro.com/v1/chat/completions
Authorization: Bearer $SOCIARO_API_KEY
Content-Type: application/json

{
  "model": "xai/grok-4",
  "messages": [
    { "role": "user", "content": "What is 101*3?" }
  ]
}

Full example (Live Search + tools + streaming + vision)

POST https://api.sociaro.com/v1/chat/completions
Authorization: Bearer $SOCIARO_API_KEY
{
  "model": "xai/grok-4",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": [
      { "type": "image_url", "image_url": { "url": "https://example.com/x.png", "detail": "high" } },
      { "type": "text", "text": "Summarize today's AI news and describe this image." }
    ] }
  ],
  "temperature": 0.7,
  "top_p": 0.95,
  "max_completion_tokens": 1024,
  "n": 1,
  "seed": 42,
  "stream": true,
  "stream_options": { "include_usage": true },
  "response_format": { "type": "text" },
  "tools": [
    { "type": "function", "function": { "name": "get_weather",
      "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "search_parameters": {
    "mode": "auto",
    "return_citations": true,
    "max_search_results": 10,
    "from_date": "2026-06-01",
    "to_date": "2026-06-17",
    "sources": ["web", "x"]
  },
  "prompt_cache_key": "conv-abc-123",
  "service_tier": "default",
  "user": "user-1234"
}

Response example

{
  "id": "a3d1008e-4544-40d4-d075-11527e794e4a",
  "object": "chat.completion",
  "created": 1752854522,
  "model": "xai/grok-4",
  "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"
}