Claude API: первый запрос на Python

API Claude позволяет встроить модель в свою программу: бота, сервис, скрипт обработки документов. Разберём, как получить ключ, отправить первый запрос на Python и не допустить типичных ошибок.

Чем API отличается от чата

Чат на claude.ai — готовый интерфейс с подпиской. API — это доступ к модели из вашего кода с оплатой за объём текста (токены). Подписка Pro не даёт доступа к API: это отдельный аккаунт в консоли разработчика и отдельный баланс.

Что подготовить

Зарегистрируйтесь в консоли Anthropic (console.anthropic.com) и пополните баланс.
Создайте API-ключ в разделе API Keys. Ключ показывается один раз — сохраните его.
Установите Python 3.10 или новее и библиотеку: pip install anthropic.
Сохраните ключ в переменную окружения ANTHROPIC_API_KEY, а не в код.

Минимальный пример

import anthropic

client = anthropic.Anthropic()  # ключ из ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=500,
    messages=[
        {"role": "user",
         "content": "Объясни, что такое API, в двух предложениях."}
    ],
)
print(message.content[0].text)

Что здесь важно:

model — идентификатор модели. Актуальный список — в документации Anthropic, названия периодически обновляются.
max_tokens — предельная длина ответа. Если ответ обрывается, увеличьте значение.
messages — история диалога. Чтобы продолжить разговор, добавляйте в список предыдущие реплики с ролями user и assistant.

Чтобы задать тон и роль, передайте параметр system, например system="Ты — вежливый консультант интернет-магазина". Подробнее — в статье System prompt в Claude.

Запрос без SDK

API работает по обычному HTTP. Запрос отправляется методом POST на адрес https://api.anthropic.com/v1/messages с заголовками x-api-key, anthropic-version: 2023-06-01 и content-type: application/json. Это удобно, если вы пишете не на Python.

Частые ошибки

401 authentication_error — неверный или отсутствующий ключ.
400 invalid_request_error — ошибка в параметрах: неверное имя модели, пустые сообщения, нет max_tokens.
429 rate_limit_error — превышен лимит запросов; нужно подождать и повторить.
529 overloaded_error — сервис временно перегружен.

Подробный разбор — в статье Claude API: ошибки и rate limit.

Как не удивиться счёту

Установите лимит расходов в консоли.
Для простых операций используйте более дешёвую модель, например Haiku.
Не отправляйте в каждом запросе всю историю, если она не нужна.
Считайте токены: в ответе API есть поле usage с количеством входных и выходных токенов.

Безопасность ключа

Не храните ключ в коде и не публикуйте его на GitHub. Если ключ утёк, сразу удалите его в консоли и создайте новый. В клиентских приложениях (сайт, мобильное приложение) ключ использовать нельзя: запросы должны идти через ваш сервер.