spb/doc-api

1# xAI `/v1/messages` — Anthropic-compatible Messages endpoint (DEPRECATED) — compatibility matrix23**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`).45**Sources:** https://docs.x.ai/developers/rest-api-reference/inference/legacy#post-v1messages · OpenAPI `MessageRequest`, `MessageBody`, `MessageContentPart`, `MessageTools`, `MessageToolChoice`, `MessageResponse`, `MessageUsage`6**Last verified:** 2026-09-1978Endpoint: `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.910## Request parameters1112| Anthropic param | xAI spec | Live 2026-09-19 |13|---|---|---|14| `model` | required | ✅ grok-4.3, grok-4.20-0309-non-reasoning |15| `max_tokens` | required | ✅ — counts **output incl. reasoning** (`output_tokens` 86 for "OK.") |16| `messages[]` `{role: user\|assistant\|system, content}` | string or block array | ✅ (`system` also allowed as a role) |17| `system` | string \| `[{type:"text", text, cache_control}]` | ✅ both |18| `temperature` (0–2) / `top_p` | yes | ✅ |19| `top_k` | "(Unsupported)" | ❌ 400 "Argument not supported: top_k" |20| `stop_sequences` (≤4) | not on reasoning models | ❌ 400 "Model grok-4.3 does not support parameter stop" |21| `stream` | yes | ✅ Anthropic events (see [streaming](streaming.md#3-v1messages-anthropic-compatible-deprecated)) |22| `metadata.user_id` | yes | doc (sent only alongside a rejected field) |23| `tools[]` `{name, description, input_schema{type:"object", properties, required}, cache_control}` | functions only | ✅; **`description` required** (422 "missing field `description`"); `cache_control` ignored |24| `tool_choice` `{type:"auto"}` \| `{type:"any"}` \| `{type:"tool", name}` | yes | ✅ `tool` forced; `disable_parallel_tool_use` → 400 schema validation |25| `thinking {type, budget_tokens}` | not in spec | accepted, **ignored** (reasoning is always on; no thinking block in a plain text answer) |26| `service_tier`, `container`, other unknown fields | not in spec | silently ignored |27| Anthropic server tools (`web_search_20250305`, …) | no | ❌ 422 (parsed as a function tool missing `description`) |28| `anthropic-beta` features (files, PDFs, citations, MCP connector, batches, count_tokens) | no | not available |2930## Content blocks3132| Block | Input | Output |33|---|---|---|34| `text` (+`cache_control` ignored) | ✅ | ✅ |35| `image` `{source:{type:"url", url}}` (data URLs work) / `{type:"base64", media_type, data}` | ✅ both | — |36| `tool_use {id, name, input}` | ✅ (replay) | ✅ `id` `call-<uuid>-<n>`, `stop_reason:"tool_use"` |37| `tool_result {tool_use_id, content: string \| [text \| image blocks], is_error}` | ✅ | — |38| `thinking {thinking, signature}` | ✅ replay (signature `""`) | ✅ (with tool_use responses and in streams; `signature` empty) |39| `redacted_thinking {data}` | spec | not observed |40| `document` (PDF/text) | ❌ 422 "did not match any variant of untagged enum MessageContent" | — |41| `search_result`, `server_tool_use`, `web_search_tool_result`, citations | ❌ | — |4243## Response44```json45{"id":"dfdeb5c4-…","type":"message","role":"assistant","model":"grok-4.3","stop_reason":"tool_use","stop_sequence":null,46 "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"}}],47 "usage":{"input_tokens":160,"cache_creation_input_tokens":0,"cache_read_input_tokens":128,"output_tokens":181}}48```49`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.5051## Verdict52Good 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`.53