Claude API docs на русском: Messages API без лишнего

Официальные claude api docs написаны по-английски и разбросаны по десятку страниц, а на практике почти всё сводится к одному эндпоинту: POST /v1/messages. Ниже — сжатая выжимка по Messages API (по-английски эта тема называется building with the Claude API): какие поля обязательны, как устроены роли и ответ, что стоит знать про стриминг, инструменты, кэш и ошибки. Все примеры рассчитаны на шлюз Zukko, но формат запроса у Anthropic один и тот же. Первоисточник — документация Anthropic (раздел API reference, страница Messages), и при любых расхождениях верьте ей, а не пересказу.

Claude API docs: запрос в одном экране

Минимальный вызов выглядит так:

curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Привет, Claude"}]
  }'

Заголовки: anthropic-version (в Zukko нужен 2023-06-01, SDK подставляют его сами), content-type и ключ. Ключ можно передать как Authorization: Bearer fetch_... или как x-api-key, который по умолчанию шлёт Anthropic SDK. Если вы работаете через официальный SDK, base_url указывается без /v1 (https://api.zukko.pro), потому что SDK добавляет путь сам. Подробности и примеры — в справке по Messages API↗.

Параметры тела запроса

Про max_tokens стоит помнить две вещи. Во-первых, это потолок, а не цель: модель может остановиться раньше. Во-вторых, это ещё и потолок цены ответа. Пример: на claude-sonnet-5-5 выход стоит $2 за 1M токенов, значит, при max_tokens: 1024 один ответ не станет дороже 1024 × 2 / 1 000 000 ≈ $0.002 (цены на 18 октября 2026).

Что устарело: temperature, top_p, top_k

В справочнике Anthropic эти три параметра помечены как deprecated. Там сказано, что модели, вышедшие после Claude Opus 4.6, не поддерживают установку temperature: значение 1.0 принимается для обратной совместимости, любое другое вызовет ошибку 400. Для top_p принимается значение от 0.99, для top_k любое значение отклоняется. Если ваш код всегда шлёт temperature=0.2, на новых моделях Claude его придётся убрать. Точные правила для вашей модели смотрите в документации Anthropic.

Роли, system и префилл

В messages используются только роли user и assistant, которые должны чередоваться. Идущие подряд реплики одной роли API склеивает в одну. Системную инструкцию кладут не в messages, а в отдельное поле system:

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.zukko.pro",
    api_key="fetch_ваш_ключ",
)

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system="Отвечай коротко и по делу, на русском.",
    messages=[{"role": "user", "content": "Что такое идемпотентность?"}],
)
print(message.content[0].text)

Если последняя реплика в списке имеет роль assistant, ответ продолжит её текст: это называется prefill. По документации, на моделях, которые префилл не поддерживают, такой запрос вернёт 400.

Как читать ответ

content в ответе — это список блоков, а не строка: обычно блок type: "text", но могут быть блоки инструментов и рассуждений. Поэтому код message.content[0].text годится для простых случаев, а в общем случае перебирайте блоки и проверяйте type. Дальше смотрите:

• stop_reason: end_turn (модель закончила), max_tokens (упёрлись в потолок, ответ обрезан), stop_sequence, tool_use (модель просит вызвать инструмент);
• usage: input_tokens, output_tokens и, если использовался кэш, cache_creation_input_tokens и cache_read_input_tokens.

Стриминг

С stream: true ответ приходит потоком server-sent events. В Python удобнее помощник SDK, который собирает текст сам:

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Напиши короткий тост"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Ошибка в середине потока может прийти уже после ответа 200, в виде отдельного события error, поэтому статус-коды тут не помогут: обрабатывайте события. Для запросов, которые генерируются долго, Anthropic рекомендует именно стриминг.

Инструменты

Инструменты описываются в tools: имя, описание и JSON-схема входа в input_schema. Если модель решила вызвать инструмент, ответ приходит с stop_reason: "tool_use" и блоком tool_use. Вы выполняете функцию сами и возвращаете результат следующей репликой роли user с блоком tool_result. Весь цикл разобран в статье про tool use↗.

Кэш промптов и подсчёт токенов

Чтобы переиспользовать длинный повторяющийся префикс (например, большой system), на блок вешают cache_control: {"type": "ephemeral"}. По документации Anthropic, кэш по умолчанию живёт 5 минут, есть и вариант на 1 час с параметром ttl, а слишком короткие префиксы не кэшируются без ошибки. Проверять, сработал ли кэш, нужно по полям usage. Шлюз видит чтение и запись кэша у Claude только в Anthropic-формате, то есть именно через /v1/messages; как это отражается на цене, разобрано в статье «Claude: Messages или Chat Completions»↗.

Узнать размер запроса до отправки можно через POST /v1/messages/count_tokens с теми же model, system, messages, tools. В ответ придёт input_tokens. Описание — в справке по count tokens↗.

Коды ошибок

Ошибка всегда приходит JSON-объектом с полями type: "error" и error.type, error.message, плюс request_id. Основные коды Anthropic: 400 invalid_request_error, 401 authentication_error, 403 permission_error, 404 not_found_error, 413 request_too_large, 429 rate_limit_error, 500 api_error, 529 overloaded_error. Через шлюз к ним добавляются свои причины:

Для 429 и 5xx официальный SDK по умолчанию повторяет запрос два раза с задержкой. При лимитах ключа повторы бесполезны: лимит нужно поднять в кабинете. Полный список моделей для ключа смотрите в GET /v1/models.

Чтобы пройтись по примерам на своём ключе, создайте его в кабинете↗ и подставьте в запросы выше.

Частые вопросы

Чем Messages API отличается от Chat Completions?

Формат другой: у Anthropic системная инструкция идёт отдельным полем system, обязателен max_tokens, ответ состоит из блоков content. Шлюз принимает оба формата для любой модели, но скидку за кэш у Claude даёт только Anthropic-формат.

Обязателен ли max_tokens?

Да, в Messages API это обязательное поле. Без него запрос вернёт 400.

Почему на новой модели падает запрос с temperature?

Anthropic пометила temperature, top_p и top_k как устаревшие, и для моделей после Opus 4.6 значения, отличные от допустимых, отклоняются. Уберите параметры из запроса.

Где посмотреть актуальные модели и цены?

GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете. Цены в статье приведены на 18 октября 2026 и могут измениться.