# 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](/docs/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](/docs/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](/docs/chat-completions#cost)).

```
"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_delta`s 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](/docs/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](/docs/rate-limits).

| 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}'
```
