Claude API: ключи, Messages API, tool use, кэширование промптов и официальные SDK
Claude API от Anthropic — это REST-интерфейс, через который любое приложение обращается к моделям Claude напрямую: отправляет сообщения, вызывает инструменты и получает ответы в JSON. Подробный обзор Claude AI поможет понять, чем модели отличаются друг от друга, прежде чем приступать к интеграции. Согласно официальной документации Anthropic, базовый адрес API — api.anthropic.com, а каждый запрос обязан содержать обязательные заголовки: x-api-key (или Authorization: Bearer), anthropic-version и content-type: application/json.
В этой статье разобраны все ключевые части платформы: как завести API-ключ и настроить аутентификацию, как устроены запрос и ответ Messages API, как работают tool use и кэширование промптов, какие официальные SDK предлагает Anthropic и сколько стоит обращение к моделям Opus, Sonnet и Haiku.
Отдельно рассмотрен вопрос, болезненный для читателя из РФ: Россия не входит в список поддерживаемых регионов Anthropic, и здесь же собраны практические варианты доступа и оплаты — от облачных платформ до посредников.
Что такое Claude API и кто за ним стоит
Claude API — это REST-интерфейс компании Anthropic по адресу api.anthropic.com для программного обращения к моделям Claude. Anthropic — американская AI-компания, основанная в 2021 году выходцами из OpenAI, которая разрабатывает семейство моделей Claude и делает акцент на безопасности и управляемости языковых моделей.
Важно понимать разницу между чатом claude.ai и API. Чат — визуальный интерфейс для людей: в нём нет SDK, нет контроля над токенами и нет программного доступа. API, напротив, предназначен для приложений: оплата идёт по потреблённым токенам, лимиты задаются отдельно, и к нему не применяются подписки Pro или Max — это независимый биллинг со своим балансом.
Платформа API Anthropic состоит из нескольких частей:
- Claude Console — веб-консоль управления на platform.claude.com: здесь создаются ключи, задаются воркспейсы и отслеживается расход.
- Messages API — основной эндпоинт POST /v1/messages для диалога с моделью.
- Message Batches API — асинхронная пакетная обработка больших объёмов запросов.
- Token Counting API — предварительный подсчёт токенов перед отправкой запроса.
- Models API — список доступных моделей и их параметров.
- Files API — загрузка и управление файлами для передачи в контекст.
Через API доступны все три уровня моделей: Haiku для быстрых и дешёвых задач, Sonnet как баланс цены и качества, Opus для сложных рассуждений и агентных сценариев. Каждая модель имеет собственное строковое имя, которое передаётся в поле model каждого запроса.
Как получить API-ключ и настроить аутентификацию
API-ключ создаётся в разделе Account Settings → API Keys консоли Claude Console, после чего передаётся в заголовке x-api-key каждого запроса к API. Запрос к API требует также заголовок anthropic-version, без которого сервер вернёт ошибку. Весь процесс занимает несколько минут при наличии аккаунта и пополненного баланса.
Шаги создания ключа
- Зарегистрируйтесь или войдите в аккаунт на platform.claude.com.
- Пополните баланс в разделе Billing — без средств на счету ключ не примет запросы.
- Перейдите в Settings → API Keys и нажмите Create Key.
- Выберите тип ключа, срок действия и воркспейс (отдельное окружение для проекта или команды).
- Скопируйте ключ сразу после создания — он отображается только один раз и не восстанавливается.
После сохранения ключ становится недоступен в интерфейсе, поэтому его нужно сразу поместить в менеджер секретов или переменную окружения.
Обязательные заголовки запроса
Каждый HTTP-запрос к api.anthropic.com должен содержать три заголовка. Первый — x-api-key: <ваш ключ> (альтернатива — Authorization: Bearer <ваш ключ>). Второй — anthropic-version: 2023-06-01, который фиксирует версию API и защищает ваш код от неожиданных изменений поведения. Третий — content-type: application/json.
Официальные SDK подставляют все три заголовка автоматически — вам достаточно передать ключ через переменную окружения. При прямых HTTP-запросах (curl, requests) заголовки нужно указывать явно.
Безопасность ключа
Ключ нельзя хранить непосредственно в коде или коммитить в репозиторий — даже в приватный. Стандартная практика: переменная окружения ANTHROPIC_API_KEY, которую SDK считывает автоматически. Для разных сред (разработка, стейджинг, продакшн) создавайте отдельные ключи в разных воркспейсах — так можно отозвать ключ одной среды, не затронув другие.
При создании ключа задавайте срок действия и отслеживайте расход через лимит расходов в консоли. Если ключ случайно утёк, немедленно отзовите его в Settings → API Keys — это занимает несколько секунд.
Messages API: как устроены запрос и ответ
Сообщения отправляются методом POST /v1/messages с обязательными полями model, max_tokens и messages, а ответ приходит в JSON с блоками content, stop_reason и usage с числом токенов. Этот единственный эндпоинт покрывает большинство сценариев: от простого вопрос-ответ до многоходовых диалогов с инструментами и стримингом.
Обязательные и полезные параметры
В теле запроса три поля обязательны: model задаёт модель, max_tokens ограничивает длину ответа, messages — массив объектов с полями role (user или assistant) и content. Системный промпт передаётся в отдельном поле верхнего уровня system, а не внутри массива messages.
| Параметр | Тип | Обязателен |
|---|---|---|
| model | string | да |
| max_tokens | integer | да |
| messages | array | да |
| system | string | нет |
| temperature | float | нет |
| stop_sequences | array | нет |
| stream | boolean | нет |
| tools | array | нет |
| tool_choice | object | нет |
| metadata | object | нет |
Структура ответа
Ответ Messages API содержит поля id (уникальный идентификатор запроса), role (всегда assistant), content (массив блоков типа text или tool_use), model (название модели), stop_reason и usage. Поле stop_reason принимает значения end_turn (нормальное завершение), max_tokens (обрезано по лимиту), stop_sequence (сработала стоп-последовательность) и tool_use (модель запросила инструмент).
Поле usage сообщает числа input_tokens и output_tokens — именно по ним начисляется оплата. Эти данные полезно логировать, чтобы отслеживать реальное потребление и заблаговременно реагировать на приближение к лимитам.
Многоходовой диалог
Claude Messages API не хранит состояние на стороне сервера — каждый запрос независим. Для многоходового диалога клиент сам накапливает историю: после каждого хода добавляет в массив messages объект с ролью user (вопрос) и объект с ролью assistant (ответ модели из предыдущего запроса).
При длинных диалогах контекст растёт и увеличивает стоимость. Практика: обрезать старые ходы или суммаризировать историю, оставляя в контексте только релевантные фрагменты. Именно здесь кэширование промптов даёт наибольший эффект для стабильных частей системного промпта.
Tool use: подключаем внешние инструменты
Tool use позволяет Claude вызывать заданные вами функции: модель возвращает блок tool_use со stop_reason tool_use, ваш код исполняет вызов и присылает tool_result обратно. Этот механизм — основа агентных приложений, где модель принимает решения, а реальные действия (поиск, запросы к базам, вычисления) выполняются на стороне клиента или серверными инструментами Anthropic.
Цикл вызова инструмента
Полный цикл function calling выглядит так. Сначала вы описываете инструмент в поле tools: передаёте name, description (объясняет модели, когда использовать) и input_schema в формате JSON Schema. Затем отправляете запрос с сообщением пользователя.
Если модель решает воспользоваться инструментом, она возвращает stop_reason: tool_use и блок tool_use с полями id (уникальный идентификатор вызова), name (имя инструмента) и input (аргументы). Ваш код исполняет функцию локально, а результат оборачивает в блок tool_result с tool_use_id и передаёт обратно в messages. Финальный ответ модели приходит в следующем обращении к API.
Управление вызовами: tool_choice
Параметр tool_choice управляет тем, как Claude выбирает инструменты. Значение auto (по умолчанию) позволяет модели самой решать, вызывать инструмент или отвечать текстом. Значение any обязывает вызвать хотя бы один из доступных инструментов. Значение tool с указанием name принудительно вызывает конкретный инструмент. Значение none запрещает любые вызовы — модель отвечает только текстом.
Дополнительные опции: disable_parallel_tool_use запрещает параллельные вызовы (полезно, если инструменты имеют побочные эффекты), а strict: true включает строгое соответствие JSON Schema в поле input.
Клиентские и серверные инструменты
Клиентские инструменты исполняет ваше приложение: всё взаимодействие с внешними системами — на вашей стороне, Anthropic передаёт только параметры вызова. Серверные инструменты — web_search, web_fetch и code_execution — исполняет сама Anthropic: результат возвращается в том же ответе без дополнительного цикла запрос-ответ.
Серверные инструменты тарифицируются отдельно поверх стандартной стоимости токенов. Это удобно для прототипов и агентов, где настраивать собственный поиск или среду выполнения кода нецелесообразно.
Кэширование промптов: как экономить на токенах
Кэширование промптов сохраняет постоянный префикс запроса, чтобы при повторе брать его из кэша по сниженной цене вместо полной обработки. Это один из самых эффективных способов снизить расходы в приложениях, где системный промпт, примеры или документы остаются неизменными от запроса к запросу.
Как включить cache_control
Для активации кэширования добавьте cache_control: {type: ephemeral} к стабильному блоку контента — системному промпту, блоку tools, длинному документу в начале диалога. Отметка ставится на последний блок, который вы хотите включить в кэш: всё до него кэшируется как единый префикс.
Минимальное число токенов для кэширования зависит от модели: у разных моделей этот порог различается. Блоки ниже этого порога кэшироваться не будут, и вы получите полную тарификацию по цене ввода. Перед включением убедитесь, что кэшируемый блок действительно стабилен: любое изменение сбрасывает кэш.
Срок жизни и цена кэша
Существуют два TTL для кэша. По умолчанию кэш живёт несколько минут и записывается с небольшой наценкой к базовой стоимости ввода. Расширенный кэш с параметром ttl: 1h живёт час и стоит дороже при записи — 2x базовой цены ввода. Чтение из кэша при любом TTL обходится значительно дешевле базовой цены.
| Тип кэша | Запись | Чтение | TTL |
|---|---|---|---|
| Ephemeral (5 мин) | 1.25x | 0.1x | 5 минут |
| Extended (1 час) | 2x | 0.1x | 1 час |
| Без кэша | 1x | — | — |
Хиты в течение TTL продлевают кэш бесплатно: каждый успешный запрос к тому же префиксу обнуляет таймер, и кэш живёт столько, сколько он используется.
Что кэшировать и как отслеживать
Кэшировать стоит всё, что не меняется между запросами: системные инструкции, немногочисленные примеры few-shot, определения инструментов в поле tools, большие документы или базы знаний в начале контекста. Переменная часть — конкретный вопрос пользователя — всегда идёт после кэшируемого блока.
Эффективность кэширования отслеживается через поля usage ответа: cache_creation_input_tokens показывает, сколько токенов было записано в кэш, а cache_read_input_tokens — сколько взято из него. Если cache_read_input_tokens стабильно растёт, кэш работает и расходы на ввод снижаются в разы.
Официальные SDK: языки, установка и первый запрос
Anthropic предоставляет официальные SDK для семи языков — Python, TypeScript, C#, Go, Java, PHP и Ruby, — которые сами подставляют обязательные заголовки, управляют повторными попытками и обрабатывают стриминг. Благодаря этому от установки до первого рабочего запроса — не больше десяти строк кода.
Семь официальных SDK
Полный список клиентских библиотек:
- Python —
pip install anthropic - TypeScript / Node.js —
npm install @anthropic-ai/sdk - Go —
go get github.com/anthropics/anthropic-sdk-go - Java — доступен через Maven / Gradle
- Ruby —
gem install anthropic - C# — доступен через NuGet
- PHP —
composer require anthropics/anthropic-sdk-php
Помимо SDK, Anthropic предоставляет CLI-инструмент ant для скриптов и поддерживает совместимость с OpenAI SDK — это позволяет переключиться на модели Claude без переписывания клиентского кода, изменив лишь базовый URL и модель.
Инициализация клиента на Python
Минимальный рабочий пример на Python: import anthropic; client = anthropic.Anthropic(). Конструктор автоматически считывает ключ из переменной окружения ANTHROPIC_API_KEY — явно передавать его не требуется. Вызов client.messages.create(model=..., max_tokens=..., messages=[{"role": "user", "content": "Hello"}]) возвращает типизированный объект ответа.
SDK самостоятельно выставляет заголовки anthropic-version и content-type, поэтому ошибки с версионированием исключены. Клиент поддерживает асинхронный режим через AsyncAnthropic — полезно в приложениях на asyncio или FastAPI.
Стриминг и повторы
Для потокового вывода используется параметр stream=True (Python) или аналогичный метод в других SDK: ответ отдаётся по частям через SSE (Server-Sent Events), что снижает воспринимаемую задержку в интерактивных приложениях. SDK сам собирает поток в финальный объект, если нужен полный текст.
Встроенная логика повторных попыток автоматически обрабатывает ошибки 429 (rate limit) с экспоненциальным бэкоффом. Тайм-ауты и максимальное число ретраев задаются при инициализации клиента. Типобезопасные модели ответа в Python и TypeScript позволяют обращаться к полям через атрибуты, а не парсить сырой JSON вручную.
Цены, лимиты и usage tiers
Claude API тарифицируется по токенам: у каждой модели своя цена за входные и выходные токены — у Haiku дешевле, у Opus дороже, а лимиты растут по usage tiers. Message Batches API даёт скидку 50% на асинхронную обработку, что существенно снижает стоимость при больших объёмах. Подробное сравнение моделей Claude поможет выбрать оптимальный вариант под конкретный сценарий.
Цены по моделям
Тарификация постфактум: счёт выставляется за фактически потреблённые токены, без абонентской платы. Минимальная единица — один токен. Opus — самая дорогая модель, Sonnet занимает среднюю ценовую позицию, Haiku — наиболее доступная. При кэшировании промптов реальная стоимость входных токенов при повторных запросах падает до 0.1x от этих значений.
Оплата идёт отдельно от подписок claude.ai — это независимый баланс в Claude Console. Средства на счёт добавляются вручную или настраивается автопополнение по порогу расхода.
Как выбрать модель
Haiku подходит для задач, где важны скорость и минимальная стоимость: классификация, короткие ответы, массовая обработка. Sonnet покрывает большинство продакшн-сценариев: суммаризация, генерация кода, диалоговые агенты. Opus ориентирован на сложные многошаговые рассуждения, исследовательские задачи и агентные системы, где качество ответа критичнее цены.
Модель задаётся строкой в поле model каждого запроса, что позволяет менять её динамически — например, использовать Haiku для первичной фильтрации и Opus для финального ответа в одном приложении.
Лимиты и способы экономии
Rate limits задаются по двум измерениям: RPM (запросов в минуту) и TPM (токенов в минуту). Оба лимита зависят от usage tier — уровня, который растёт автоматически при накоплении достаточного расхода. При необходимости tier можно повысить, подав заявку в Claude Console.
Основные инструменты экономии: кэширование промптов существенно снижает стоимость повторных входных токенов, а Message Batches API даёт значительную скидку на асинхронную обработку — идеален для задач, где ответ нужен не мгновенно. Token Counting позволяет заранее вычислить стоимость запроса и не превышать бюджет.
Доступ и оплата Claude API из России
Claude API из России напрямую недоступен: Россия не входит в список поддерживаемых регионов Anthropic, поэтому для получения ключа и оплаты нужны обходные пути через зарубежные реквизиты или облачные платформы. Подробнее о том, как организовать доступ к Claude из России, можно узнать в отдельном материале.
Почему прямой доступ не работает
Россия отсутствует в официальном перечне регионов, которые Anthropic поддерживает. При этом соседние страны — Казахстан, Грузия, Армения, Азербайджан и Украина (за исключением Крыма, Донецкой и Луганской областей) — в списке присутствуют. Это означает, что регистрация через российские реквизиты технически не предусмотрена: платёжный адрес должен относиться к поддерживаемой стране, а при обнаружении российской локации возможна блокировка аккаунта или ключа.
Список регионов периодически обновляется, поэтому перед стартом проекта стоит сверяться с актуальной версией на сайте Anthropic — ограничения могут меняться.
Возможные варианты
Практические пути, которыми пользуются разработчики из РФ:
- Зарубежная банковская карта или юрлицо, зарегистрированное в поддерживаемой стране, с подключением через VPN из неограниченного региона.
- Amazon Bedrock — AWS-платформа, которая предоставляет доступ к моделям Claude через собственную инфраструктуру и правила доступа AWS.
- Google Cloud Vertex AI — аналогичный путь через Google Cloud с моделями Claude.
- Сторонние API-агрегаторы, перепродающие доступ к API Anthropic как посредники.
Каждый из вариантов несёт риски: нарушение Terms of Service Anthropic, блокировка ключа при выявлении реальной локации, юридическая неопределённость при оплате через посредников.
Юридический и практический аспект
Использование обходных путей для доступа к Claude API — на ответственность пользователя. Условия использования Anthropic прямо запрещают регистрацию из регионов, не включённых в список поддерживаемых: нарушение может привести к немедленному отзыву ключей и блокировке аккаунта без возврата средств.
Наиболее устойчивый вариант для коммерческого использования — оформить доступ через Amazon Bedrock или Google Cloud Vertex AI: эти платформы работают по собственным условиям, а отношения с Anthropic остаются косвенными. Перед запуском продакшн-проекта рекомендуется проконсультироваться с юристом о применимости условий к конкретной ситуации.
Дополнительные возможности и обработка ответов
Помимо базового запроса API Claude даёт стриминг ответов, пакетную обработку со скидкой 50% и предварительный подсчёт токенов, а надёжный код всегда опирается на stop_reason и usage из ответа. Грамотная обработка этих полей — разница между прототипом и продакшн-сервисом.
Стриминг отдаёт ответ по частям через SSE. При stream: true API начинает передавать токены немедленно, не дожидаясь завершения генерации. Это радикально снижает воспринимаемую задержку в чат-интерфейсах: пользователь видит начало ответа уже через сотни миллисекунд. SDK обрабатывает SSE-поток прозрачно и по завершении собирает итоговый объект с полными полями usage и stop_reason.
Message Batches API существенно снижает стоимость асинхронных задач. Отправив пакет запросов через этот эндпоинт, вы получаете значительную скидку на обработку в обмен на отложенный результат. Это оптимально для массового анализа документов, генерации описаний товаров, оффлайн-суммаризации — любых задач, где мгновенный ответ не нужен.
Для контроля бюджета до отправки запроса используется Token Counting — эндпоинт POST /v1/messages/count_tokens. Он принимает те же параметры, что и Messages API, и возвращает точное число токенов без реальной генерации. Это позволяет заранее отсечь запросы, превышающие лимит или бюджет.
Ключевые сигналы в ответе, на которые нужно реагировать в коде:
- stop_reason: end_turn — нормальное завершение, ответ полный.
- stop_reason: max_tokens — ответ обрезан, увеличьте max_tokens или используйте стриминг с накоплением.
- stop_reason: tool_use — необходимо выполнить вызов инструмента и вернуть tool_result.
- HTTP 401 — ключ недействителен или отозван.
- HTTP 429 — превышен rate limit, применяйте ретрай с экспоненциальным бэкоффом.
- HTTP 413 request_too_large — запрос превышает 32 МБ, уменьшите контекст.
- HTTP 5xx — проблема на стороне Anthropic, логируйте request-id из заголовка ответа и передавайте его в поддержку.