Messages

Быстро

Диалект Anthropic Messages обслуживается как есть, а не переведён из другого: max_tokens обязателен и умолчания не имеет, системный промпт — член запроса, инструменты несут input_schema без обёртки-функции, а ответ говорит блоками и 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": "Отвечай одним предложением.",
    "messages": [{ "role": "user", "content": "Объясни токены." }]
  }'

Два носителя ключа

Ключ предъявляется либо как Authorization: Bearer <ключ>, либо, как это делает нативный API, голым в заголовке x-api-key. Оба носителя называют один и тот же ключ Kumo, и любой из них допускает вызов. SDK Anthropic шлёт второй и никакого Authorization не отправляет вовсе — поэтому он и объявлен на этих операциях.

Предъявить оба сразу законно. Побеждает Authorization: если он присутствует и корректно оформлен, именно он аутентифицирует запрос, а голый x-api-key в этом случае не читается вовсе. Обычный клиент шлёт ровно один из двух — второй появляется только у самодельных обёрток, дописывающих заголовки поверх готового SDK.

Как пишется заголовок → Проверить ключ →

Члены запроса

Ход разговора несёт role (user, assistant, system) и content — строкой либо списком типизированных блоков: text, tool_use, tool_result. Ход system ходом разговора не считается: его текст поднимается в системный промпт, после блоков, которые назвал сам член system.

tool_result.content принимает строку либо до 32 блоков с типом text или image. Изображение передаётся источником base64 с полями media_type и data; источники URL отвергаются. Нативный Messages передаёт эти блоки без изменений. Маршрут Chat Completions не может представить изображение внутри результата инструмента и отвергает такой результат, а не удаляет изображение.

Ответ

{
  "id": "msg-71c3d0aa4e",
  "type": "message",
  "role": "assistant",
  "model": "<model>",
  "content": [{ "type": "text", "text": "Токены — куски текста, которыми модель меряет ввод и вывод." }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 16,
    "output_tokens": 22,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

Поток

"stream": true отвечает text/event-stream в именованных событиях протокола: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. Кроме них приходят ping и error.

Отказ, решённый до первого события, приходит обычной JSON-ошибкой этого протокола. Сбой после первого события выражается только в потоке — событием error, — и дальше поток кончается без message_stop. Поэтому целый ответ здесь виден по message_stop, и по нему одному.

Все события трёх диалектов →

Подсчёт токенов

POST /v1/messages/count_tokens принимает подмножество членов /v1/messages — model, messages, system, tools, tool_choice, thinking, metadata и context_management — и отвечает детерминированной локальной оценкой входных токенов. К провайдеру она не обращается, запроса и резерва не создаёт, баланса не трогает и квоту темпа не тратит — поэтому её удобно ставить перед крупным вызовом.

Всё остальное относится к генерации, а не ко входу, и на этой операции отвергается: max_tokens, stream, output_config, stop_sequences, temperature и 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": "Отвечай одним предложением.",
    "messages": [{ "role": "user", "content": "Объясни токены." }]
  }'

Ответ несёт два члена: input_tokens — саму оценку, и estimated, который остаётся true, пока нет точного локального токенизатора.

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

Что дальше