Messages

Quick

The Anthropic Messages dialect is served natively and not translated from another: max_tokens is required and has no default, the system prompt is a member of the request, tools carry input_schema with no function wrapper, and the answer speaks in blocks and a stop_reason.

curl https://api.kumorouter.com/v1/messages \
  -H "x-api-key: $KUMO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 256,
    "system": "Answer in one sentence.",
    "messages": [{ "role": "user", "content": "Explain tokens." }]
  }'

Two carriers for the key

The key is presented either as Authorization: Bearer <key> or, as the native API does it, bare in the x-api-key header. Both name the same Kumo key, and either admits the call. An Anthropic SDK sends the second and no Authorization header at all, which is why it is declared on these operations.

Presenting both is legal. Authorization wins: when it is present and well formed, it is the one that authenticates, and the bare x-api-key is not read at all in that case. An ordinary client sends exactly one of the two — the second header shows up only in a hand-built wrapper that layers headers on top of a ready-made SDK.

How the header is written → Check your key →

Request members

A turn carries a role (user, assistant, system) and content — a string, or a list of typed blocks: text, tool_use, tool_result. A system turn is not a turn of the conversation: its text is lifted into the system prompt, after the blocks the system member itself states.

tool_result.content accepts a string or up to 32 blocks of type text or image. Image bytes use a base64 source with media_type and data; URL sources are rejected. Native Messages carries these blocks unchanged. A Chat Completions route cannot represent an image inside a tool result and refuses that result rather than discarding the image.

The response

{
  "id": "msg-71c3d0aa4e",
  "type": "message",
  "role": "assistant",
  "model": "<model>",
  "content": [{ "type": "text", "text": "Tokens are the pieces of text a model measures input and output in." }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 16,
    "output_tokens": 22,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

Streaming

"stream": true answers as text/event-stream in the protocol's own named events: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. Alongside them arrive ping and error.

A refusal decided before the first event is this protocol's ordinary JSON error. A failure after the first event can only be expressed in the stream — as the error event — and the stream then ends without message_stop. So here a whole answer is marked by message_stop, and by nothing else.

Every event of all three dialects →

Counting tokens

POST /v1/messages/count_tokens takes a subset of the /v1/messages members — model, messages, system, tools, tool_choice, thinking, metadata and context_management — and answers with a deterministic local estimate of the input tokens. It calls no provider, creates no request or reservation, touches no balance and consumes no rate quota — which is what makes it easy to put in front of a large call.

Everything else describes the generation rather than the input, and is refused on this operation: max_tokens, stream, output_config, stop_sequences, temperature and top_p.

curl https://api.kumorouter.com/v1/messages/count_tokens \
  -H "x-api-key: $KUMO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "<model>",
    "system": "Answer in one sentence.",
    "messages": [{ "role": "user", "content": "Explain tokens." }]
  }'

The reply carries two members: input_tokens, the estimate itself, and estimated, which stays true until an exact local tokenizer is available.

{ "input_tokens": 16, "estimated": true }

Next