Messages API

Read MarkdownFor agents

POST /api/v1/messages, the Anthropic Messages dialect. Agent frameworks that target Anthropic (tool use, content blocks) work unchanged. It serves KhaBot models (khabot/…) and passes any other model id through to OpenRouter, billed from credit at the provider's cost, see Drop-in from OpenRouter.

Why agents want it

The Messages format models assistant turns as ordered content blocks (text, tool_use, tool_result), which maps cleanly to multi-step tool-calling agents. If your stack is built on it, use this endpoint; otherwise Chat Completions is fine.

Request

{
  "model": "khabot/claude-sonnet-5",
  "max_tokens": 512,
  "system": "You are a helpful assistant.",
  "messages": [{"role": "user", "content": "Give me three bullet points."}],
  "stream": true
}

Usage and cost

A response's usage carries input_tokens, output_tokens, cache_read_input_tokens and cache_creation_input_tokens. For KhaBot models it also carries cost, the USD billed for the call, and cost_source: plan or credit (see Chat Completions).

"usage": {
  "input_tokens": 1830,
  "output_tokens": 212,
  "cache_read_input_tokens": 1536,
  "cache_creation_input_tokens": 0,
  "cost": 0.004101,
  "cost_source": "credit"
}

Streaming events

SSE events follow the Anthropic sequence:

event: message_start        → { message: { usage: { input_tokens } } }
event: content_block_start  → { index, content_block: { type: "text" } }
event: content_block_delta  → { delta: { type: "text_delta", text: "…" } }
event: content_block_stop
event: message_delta        → { delta: { stop_reason }, usage: { input_tokens, output_tokens,
                                cache_read_input_tokens, cache_creation_input_tokens, cost, cost_source } }
event: message_stop

Accumulate text_deltas for the reply. Read the final usage from message_delta: it carries the real input_tokens, cache_read_input_tokens and cache_creation_input_tokens along with output_tokens and, for KhaBot models, the cost. message_start may show input_tokens: 0, don't rely on it.

Images

Models whose input_modalities include "image" (see Models & pricing) accept images in the request. Send them inline as base64:

{
  "model": "khabot/claude-sonnet-5",
  "max_tokens": 512,
  "messages": [{
    "role": "user",
    "content": [
      { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo…" } },
      { "type": "text", "text": "What is in this picture?" }
    ]
  }]
}

The same limits apply on both dialects, /chat/completions and /messages, and on every plan:

LimitValue
Images per request20
Size of one image5 MiB, decoded
All images together16 MiB, decoded
Request body25 MB (26,214,400 bytes) of JSON, base64 included

KhaBot doesn't check pixel dimensions; the model's own limits on image size still apply, so very large images may be refused or scaled down by the model.

A request over a limit is refused before it reaches the model: it isn't billed and doesn't use up your rate limit.

HTTPcodeWhendetails
400invalid_imageAn image can't be decoded or isn't a supported imageindex, reason
400image_too_largeOne image is over 5 MiB decodedindex, bytes, max_bytes
400too_many_imagesMore than 20 imagescount, max_images
400images_too_largeAll images together are over 16 MiB decodedbytes, max_bytes
413payload_too_largeThe request body is over 25 MB (26,214,400 bytes)max_body_bytes

index says which image: the images are counted in the order they appear in messages, starting at 0.

{ "error": { "code": "image_too_large", "message": "Image too large",
  "details": { "index": 2, "bytes": 6291456, "max_bytes": 5242880 } } }

Thinking blocks

Reasoning models can return thinking content blocks. In multi-turn tool use you can send an assistant turn back exactly as you received it: thinking blocks may be echoed back in messages[]; blocks with an empty signature are ignored.

curl -N https://khabot.com/api/v1/messages \
  -H "Authorization: Bearer kb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"khabot/claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"hi"}],"stream":true}'