Messages API
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:
| Limit | Value |
|---|---|
| Images per request | 20 |
| Size of one image | 5 MiB, decoded |
| All images together | 16 MiB, decoded |
| Request body | 25 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.
| HTTP | code | When | details |
|---|---|---|---|
| 400 | invalid_image | An image can't be decoded or isn't a supported image | index, reason |
| 400 | image_too_large | One image is over 5 MiB decoded | index, bytes, max_bytes |
| 400 | too_many_images | More than 20 images | count, max_images |
| 400 | images_too_large | All images together are over 16 MiB decoded | bytes, max_bytes |
| 413 | payload_too_large | The 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}'