Messages (Anthropic)
POST /v1/messages accepts the Anthropic Messages format, with or without streaming: text, tools, images, documents, extended thinking, structured output and prompt caching. The official anthropic SDK works as is.
400 and tells you to use /v1/chat/completions. Example request
curl https://octalabs.id/v1/messages \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-fable-5", "max_tokens": 256, "system": "Answer briefly.", "messages": [ {"role": "user", "content": "Hi! Explain what an API is in one sentence."} ] }'Supported fields
| Field | Notes |
|---|---|
model | Required. The ID of a model whose API format lists Anthropic. |
max_tokens | Required. A positive integer no larger than the model’s context limit, and larger than thinking.budget_tokens when thinking is enabled. |
messages | Required and non-empty. Roles user and assistant, plus system for a text-only instruction inside the conversation. A message has only role and content. |
system | Optional. A string or an array of text blocks. |
stream | Optional. true for Server-Sent Events. |
tools | Optional. Tools that your application runs. See Tools below. |
tool_choice | Optional. {"type":"auto"}, {"type":"any"}, {"type":"tool","name":"…"} or {"type":"none"}. The first three also take disable_parallel_tool_use. |
temperaturetop_ptop_k | Optional. Non-negative numbers; top_k is an integer. Some models refuse them, see the note below the table. |
stop_sequences | Optional. An array of strings. |
thinking | Optional. {"type":"enabled","budget_tokens":N}, {"type":"adaptive"}, {"type":"disabled"} or {"type":"between_tools"}. display may be summarized or omitted. |
output_config | Optional. effort (low, medium, high, xhigh or max) and format for structured output: {"type":"json_schema","schema":{…}}. |
cache_control | Optional. {"type":"ephemeral"} for the 5-minute prompt cache. See Prompt caching below. |
metadata | Optional. |
service_tier | Optional. Only "auto". |
A missing model, max_tokens or messages is rejected with 422. Anything else that cannot be accepted is rejected with 400 before the request runs, at no cost, and the error message names the field.
Sampling parameters on some models
Some models do not take sampling parameters. For them,top_p, top_k and a temperature other than 1 are refused with 400 (“top_p is not supported by this model; remove it”). Remove the parameter and send the request again. temperature: 1 is always accepted. What is refused
Everything accepted here is billed through the token usage the provider reports. What would be billed another way, or needs a beta feature, is refused by name:
| Refused | Why, and what to do instead |
|---|---|
| Server-side tools | Tool types web_search, web_fetch, code_execution, tool_search_tool, mcp_toolset and advisor, and the content blocks they produce. They run on the provider’s side and are billed per use. Define a tool your application runs instead. |
mcp_servers, container | MCP servers and code execution containers run on the provider’s side. |
cache_control with "ttl": "1h" | The 1-hour cache is not available. Use the default 5-minute cache. |
service_tier other than "auto", speed, inference_geo | Other service tiers, fast mode and a chosen inference region are priced differently. |
betas, context_management, diagnostics, thread, fallbacks | They need a beta feature. The anthropic-beta request header is not passed on, so nothing that depends on it is available. The same goes for members of output_config other than effort and format. |
output_format | Use output_config.format. |
file sources | An image or document given by file ID. Send it as base64 or by URL. |
| Any other field or block type | Refused, so that nothing is billed outside the reported token usage. |
Content blocks
Message content is a string or a non-empty array of these blocks:
| Block | Notes |
|---|---|
text | In any message and in system. May carry cache_control. |
image | A base64 source (JPEG, PNG, GIF or WebP) or a url source. |
document | A base64 PDF, a text source (text/plain), a content source (text and image blocks) or a url source. Optional title, context and citations: {"enabled": true}. |
search_result | source, title and a content array of text blocks. |
tool_use | In assistant messages: a tool call the model made, sent back as it was returned. |
tool_result | In user messages: tool_use_id and the result as a string or as text, image, document or search_result blocks. Optional is_error. |
thinking, redacted_thinking | In assistant messages: thinking from an earlier turn, sent back unchanged. |
- The request body may be up to 16 MB, base64 data included. A larger body is rejected with
413. - A request with an image, a PDF, a document by URL, citations enabled or the memory tool is held against the model’s whole context, because its token count cannot be read from its size. See Billing & balance.
Tools
Define tools that your application runs. The model answers with a tool_use block and stop_reason: "tool_use"; run the tool, then send a tool_result block with the same ID in the next user message.
curl https://octalabs.id/v1/messages \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-fable-5", "max_tokens": 512, "tools": [{ "name": "get_weather", "description": "Get the current weather for a city.", "input_schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } }], "messages": [ {"role": "user", "content": "What is the weather in Jakarta right now?"} ] }'- A custom tool has a
name, aninput_schemaand usually adescription.strict,input_examples,eager_input_streamingandcache_controlare accepted. - The Anthropic-defined tools that you run yourself are accepted too:
bash_20250124,text_editor_20250728andmemory_20250818. defer_loading: trueandallowed_callersother thandirectare refused, because they depend on server-side tools.- Tool definitions are billed as input tokens and tool calls as output tokens, from the usage the provider reports.
Prompt caching
Mark the end of a stable prefix with cache_control: on a content block, on a tool, or at the top level of the request. The prefix is cached for 5 minutes; "ttl": "5m" may be written out, "ttl": "1h" is refused.
cache_control
{ "model": "claude-fable-5", "max_tokens": 512, "system": [ { "type": "text", "text": "<a long, stable system prompt>", "cache_control": {"type": "ephemeral"} } ], "messages": [{"role": "user", "content": "…"}]}- Tokens written to the cache are reported as
cache_creation_input_tokensand billed at the model’s cache-write rate. Tokens read from it are reported ascache_read_input_tokensand billed at the cache-read rate. - Both rates are on Models & Pricing. For a model that has no cache rates,
cache_controlis refused with400; remove it from the request.
Streaming
With "stream": true, Anthropic events (message_start, content_block_delta, message_delta, message_stop) are forwarded unchanged as they arrive. The final usage is read from the message_delta event.
curl -N https://octalabs.id/v1/messages \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-fable-5", "max_tokens": 256, "stream": true, "messages": [{"role": "user", "content": "Hello!"}] }'- While the model is quiet, a comment line
: keep-aliveis sent about every 15 seconds. The official SDK ignores it; a parser you write yourself must skip every line that starts with:. - As with Chat Completions, the
x-billing-stateheader isstreaming, and the billing outcome is sent as the SSE comment: x-billing-state settled(orreleasedorpending) just before the stream closes. - A stream has to start within 90 seconds and may stay silent for up to 300 seconds at a time. See Limits & fields.
Counting tokens
POST /v1/messages/count_tokens returns how many input tokens a Messages request has, without running it. The anthropic SDK calls it through messages.count_tokens.
curl https://octalabs.id/v1/messages/count_tokens \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-fable-5", "system": "Answer briefly.", "messages": [ {"role": "user", "content": "Hi! Explain what an API is in one sentence."} ] }'Response
{ "input_tokens": 27}- Free. Nothing is held or charged, and nothing appears on the Usage page.
- It uses the same API key and counts towards the same request limits as your other requests.
- Send the same body as for
/v1/messages. Fields that only steer the reply (max_tokens,stream,temperature,top_p,top_k,stop_sequences,metadata,service_tier) are accepted and ignored. - The number comes from the model provider; it is never an estimate. Images and documents must be sent as base64 to be counted, and a request with server-side tools cannot be counted (
400). - It is available for Claude models only. For any other model it answers
400(“Token counting is not available for the model …”), including the text-and-tools models that list the Anthropic format. - With an empty balance it answers
402, unless the model is free.
Models that are not Claude models
A few models that list the Anthropic format are not Claude models (the text-and-tools models described under Chat Completions). On this endpoint they accept model, max_tokens, messages, system, stream, tools and tool_choice; metadata is ignored. Content is limited to text, tool_use and tool_result blocks, and tools to custom tools. Sampling parameters, stop_sequences, thinking, output_config, a top-level cache_control, service_tier, images and documents are refused with 400; the message says “for this model”. For these models max_tokens does not cut the reply, and the hold always covers the model’s whole context.
Usage and cost
The cost is calculated from the input_tokens, output_tokens and cache tokens (cache_read_input_tokens, cache_creation_input_tokens) the provider reports, each at its rate on the Models & Pricing page.