Skip to main content

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.

This endpoint is only for models whose API format column lists Anthropic on the Models & Pricing page. For any other model it answers 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
modelRequired. The ID of a model whose API format lists Anthropic.
max_tokensRequired. A positive integer no larger than the model’s context limit, and larger than thinking.budget_tokens when thinking is enabled.
messagesRequired and non-empty. Roles user and assistant, plus system for a text-only instruction inside the conversation. A message has only role and content.
systemOptional. A string or an array of text blocks.
streamOptional. true for Server-Sent Events.
toolsOptional. Tools that your application runs. See Tools below.
tool_choiceOptional. {"type":"auto"}, {"type":"any"}, {"type":"tool","name":"…"} or {"type":"none"}. The first three also take disable_parallel_tool_use.
temperature
top_p
top_k
Optional. Non-negative numbers; top_k is an integer. Some models refuse them, see the note below the table.
stop_sequencesOptional. An array of strings.
thinkingOptional. {"type":"enabled","budget_tokens":N}, {"type":"adaptive"}, {"type":"disabled"} or {"type":"between_tools"}. display may be summarized or omitted.
output_configOptional. effort (low, medium, high, xhigh or max) and format for structured output: {"type":"json_schema","schema":{…}}.
cache_controlOptional. {"type":"ephemeral"} for the 5-minute prompt cache. See Prompt caching below.
metadataOptional.
service_tierOptional. 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 toolsTool 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, containerMCP 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_geoOther service tiers, fast mode and a chosen inference region are priced differently.
betas, context_management, diagnostics, thread, fallbacksThey 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_formatUse output_config.format.
file sourcesAn image or document given by file ID. Send it as base64 or by URL.
Any other field or block typeRefused, 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
textIn any message and in system. May carry cache_control.
imageA base64 source (JPEG, PNG, GIF or WebP) or a url source.
documentA 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_resultsource, title and a content array of text blocks.
tool_useIn assistant messages: a tool call the model made, sent back as it was returned.
tool_resultIn 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_thinkingIn 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, an input_schema and usually a description. strict, input_examples, eager_input_streaming and cache_control are accepted.
  • The Anthropic-defined tools that you run yourself are accepted too: bash_20250124, text_editor_20250728 and memory_20250818.
  • defer_loading: true and allowed_callers other than direct are 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_tokens and billed at the model’s cache-write rate. Tokens read from it are reported as cache_read_input_tokens and billed at the cache-read rate.
  • Both rates are on Models & Pricing. For a model that has no cache rates, cache_control is refused with 400; 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-alive is 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-state header is streaming, and the billing outcome is sent as the SSE comment : x-billing-state settled (or released or pending) 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.

Start with any balance,
however small.

Create a free accountSign in AI API · pay as you go