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./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
thinkingblocks appear on reasoning models.signatureis always empty.- Tool calls come back as
{ "type": "tool_use", "id": "…", "name": "…", "input": {…} }blocks. stop_reasonisend_turn,max_tokens, ortool_use. It is neverstop_sequence, andstop_sequenceis alwaysnull.cache_read_input_tokensis set when prompt caching applies. As in the Anthropic API,input_tokensdoes not include cached tokens.cache_creation_input_tokensis always0.
Streaming
Setstream: 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_useblock is sent whole at the end, as oneinput_json_deltaholding the complete arguments. usageinmessage_startis an estimate. Use themessage_deltausage 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
errorevent, 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
/v1. The
SDK adds /v1/messages itself. See SDKs.
Count tokens
/v1/messages and returns:
Errors
Errors use the Anthropic shape:
Full table of causes: Errors.