xAI /v1/messages — Anthropic-compatible Messages endpoint (DEPRECATED) — compatibility matrix
Status: DOCUMENTED + DEPRECATED ("The Anthropic SDK compatibility is fully deprecated. Please migrate to the Responses API or gRPC") + LIVE_VERIFIED (2026-09-19, grok-4.3: minimal, system array with cache_control, tools + forced tool_use + tool_result round trip, image url/base64 blocks, streaming, thinking param; 400/422 paths). Machine-readable: parameters/xai-messages-compat.json, objects/xai-inference-objects.json (MessageResponse, MessageUsage), streaming-events/xai-inference.json (api messages_compat).
Sources: https://docs.x.ai/developers/rest-api-reference/inference/legacy#post-v1messages · OpenAPI MessageRequest, MessageBody, MessageContentPart, MessageTools, MessageToolChoice, MessageResponse, MessageUsage
Last verified: 2026-09-19
Endpoint: POST https://api.x.ai/v1/messages, auth Authorization: Bearer $XAI_API_KEY (Anthropic headers x-api-key/anthropic-version are ignored, not required). Works with anthropic SDK pointed at base_url="https://api.x.ai" — unofficial. No /v1/messages/count_tokens (404), no batches, no Admin.
Request parameters
| Anthropic param | xAI spec | Live 2026-09-19 |
|---|---|---|
model |
required | ✅ grok-4.3, grok-4.20-0309-non-reasoning |
max_tokens |
required | ✅ — counts output incl. reasoning (output_tokens 86 for "OK.") |
messages[] {role: user|assistant|system, content} |
string or block array | ✅ (system also allowed as a role) |
system |
string | [{type:"text", text, cache_control}] |
✅ both |
temperature (0–2) / top_p |
yes | ✅ |
top_k |
"(Unsupported)" | ❌ 400 "Argument not supported: top_k" |
stop_sequences (≤4) |
not on reasoning models | ❌ 400 "Model grok-4.3 does not support parameter stop" |
stream |
yes | ✅ Anthropic events (see streaming) |
metadata.user_id |
yes | doc (sent only alongside a rejected field) |
tools[] {name, description, input_schema{type:"object", properties, required}, cache_control} |
functions only | ✅; description required (422 "missing field description"); cache_control ignored |
tool_choice {type:"auto"} | {type:"any"} | {type:"tool", name} |
yes | ✅ tool forced; disable_parallel_tool_use → 400 schema validation |
thinking {type, budget_tokens} |
not in spec | accepted, ignored (reasoning is always on; no thinking block in a plain text answer) |
service_tier, container, other unknown fields |
not in spec | silently ignored |
Anthropic server tools (web_search_20250305, …) |
no | ❌ 422 (parsed as a function tool missing description) |
anthropic-beta features (files, PDFs, citations, MCP connector, batches, count_tokens) |
no | not available |
Content blocks
| Block | Input | Output |
|---|---|---|
text (+cache_control ignored) |
✅ | ✅ |
image {source:{type:"url", url}} (data URLs work) / {type:"base64", media_type, data} |
✅ both | — |
tool_use {id, name, input} |
✅ (replay) | ✅ id call-<uuid>-<n>, stop_reason:"tool_use" |
tool_result {tool_use_id, content: string | [text | image blocks], is_error} |
✅ | — |
thinking {thinking, signature} |
✅ replay (signature "") |
✅ (with tool_use responses and in streams; signature empty) |
redacted_thinking {data} |
spec | not observed |
document (PDF/text) |
❌ 422 "did not match any variant of untagged enum MessageContent" | — |
search_result, server_tool_use, web_search_tool_result, citations |
❌ | — |
Response
{"id":"dfdeb5c4-…","type":"message","role":"assistant","model":"grok-4.3","stop_reason":"tool_use","stop_sequence":null,
"content":[{"type":"thinking","signature":"","thinking":"The user asked about the weather in Paris."},{"type":"tool_use","id":"call-d84004a8-…-0","name":"get_weather","input":{"city":"Paris"}}],
"usage":{"input_tokens":160,"cache_creation_input_tokens":0,"cache_read_input_tokens":128,"output_tokens":181}}stop_reason: end_turn, max_tokens, stop_sequence, tool_use. usage.input_tokens = non-cached tokens; cache_read_input_tokens = automatic prefix cache; cache_creation_input_tokens always 0. No service_tier, no container, no context_management in the response.
Verdict
Good enough for simple text + function-calling clients that already speak Anthropic Messages; anything else (documents, citations, server tools, extended-thinking control, batches, token counting) is absent. xAI's migration target is /v1/responses. Examples: examples/xai/messages-compat/; tests tests/xai/test_messages_compat.py.