Skip to main content

POST /v1/messages

The Anthropic Messages API, translated onto the same lineup, keys, and billing as chat completions. Use it when your SDK or agent (Anthropic SDKs, Claude Code, and other Anthropic-native tools) speaks Messages instead of OpenAI chat.
Each request runs as one chat generation. Model ids, billing, and error statuses match /v1/chat/completions. Errors come back in the Anthropic shape.

Authentication

Send your key either way:
  • x-api-key: abl_… (what Anthropic SDKs send)
  • Authorization: Bearer abl_…
anthropic-version and anthropic-beta headers are accepted and ignored. This endpoint takes API keys only, not console sessions.

Request

Other fields (metadata, service_tier, cache_control, and so on) are accepted and ignored.

Content blocks

Turns with role: "system" or "developer" inside messages are folded into the system prompt instead of being rejected. Anthropic-hosted server tools (web_search_*, code_execution_*, and others with no input_schema) are skipped. These models cannot run them.

Non-streamed response

  • thinking blocks appear on reasoning models. signature is always empty.
  • Tool calls come back as { "type": "tool_use", "id": "…", "name": "…", "input": {…} } blocks.
  • stop_reason is end_turn, max_tokens, or tool_use. It is never stop_sequence, and stop_sequence is always null.
  • cache_read_input_tokens is set when prompt caching applies. As in the Anthropic API, input_tokens does not include cached tokens. cache_creation_input_tokens is always 0.

Streaming

Set stream: true for the standard Anthropic event sequence: message_start → ping → content_block_start → content_block_delta (×N) → content_block_stop → … → message_delta (with stop_reason and final usage) → message_stop.
  • Text (text_delta) and thinking (thinking_delta) stream live.
  • Tool calls are buffered. Each tool_use block is sent whole at the end, as one input_json_delta holding the complete arguments.
  • usage in message_start is an estimate. Use the message_delta usage for real counts.
  • On long waits the server sends keep-alives before the first event, so proxies do not time out the connection.
  • A failure mid-stream sends an error event, then the stream closes.

Thinking and effort

Anthropic thinking settings map to our reasoning levels: The result is fitted to the levels the model offers, so a thinking setting never causes a 400. If you ask for off and the model cannot turn reasoning off, the model default applies. Otherwise you get the closest level at or below your request, else the lowest one above it. budget_tokens is not a hard limit on thinking length. If you send reasoning_effort yourself, it is not fitted. It is checked as strictly as on /v1/chat/completions.

Example

With the Anthropic SDK, set the base URL to the host without /v1. The SDK adds /v1/messages itself. See SDKs.

Count tokens

Takes the same body as /v1/messages and returns:
This is an estimate: the same one used to size the credit hold. It is free. Nothing is billed and no model runs.

Errors

Errors use the Anthropic shape:
Full table of causes: Errors.