Claude API: руководство для разработчиков

Claude от Anthropic — одна из сильнейших языковых моделей на рынке. API Claude доступен через Anthropic Console и Amazon Bedrock, поддерживает тексты до 200 000 токенов контекста и предлагает семейство моделей от быстрого Haiku до мощного Opus. Разберём, как интегрировать Claude API в приложение на Python.

Получение API-ключа

Зарегистрируйтесь на console.anthropic.com и создайте API-ключ в разделе «API Keys». Ключ начинается с sk-ant-. Anthropic предоставляет бесплатные кредиты для тестирования — обычно $5, которых достаточно для нескольких тысяч запросов.

Установите SDK:

pip install anthropic

Первый запрос

from anthropic import Anthropic

client = Anthropic()  # Берёт ключ из ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Объясни разницу между Docker и виртуальной машиной"}
    ]
)

print(message.content[0].text)

API Claude использует формат Messages — аналогичный OpenAI, но с отличиями. Главное отличие: системный промпт передаётся отдельным параметром system, а не как сообщение с ролью «system».

Модели и цены

Anthropic предлагает три уровня моделей с разным балансом скорости и качества:

Claude Opus 4 — флагманская модель. Лучшие результаты на сложных задачах: программирование, анализ, рассуждения. Контекст: 200K токенов. Стоимость: $15 за 1М входных, $75 за 1М выходных токенов.

Claude Sonnet 4 — оптимальный баланс. Быстрее Opus при сопоставимом качестве для большинства задач. Контекст: 200K. Стоимость: $3/$15.

Claude Haiku 3.5 — быстрая и дешёвая модель для высоконагруженных сценариев. Контекст: 200K. Стоимость: $0.25/$1.25. Идеальна для классификации, извлечения данных, простых вопросов.

Для выбора модели под конкретную задачу смотрите наше руководство по выбору LLM.

Системный промпт и параметры

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    system="Ты — технический писатель. Отвечай структурированно, с примерами кода.",
    temperature=0.7,    # 0.0 — детерминированно, 1.0 — креативно
    top_p=0.9,          # Nucleus sampling
    messages=[
        {"role": "user", "content": "Напиши функцию для валидации email на Python"}
    ]
)

print(f"Модель: {message.model}")
print(f"Токены: {message.usage.input_tokens} вход, {message.usage.output_tokens} выход")
print(f"Причина остановки: {message.stop_reason}")
print(message.content[0].text)

Параметр temperature контролирует «креативность» ответа. Для кода и фактических вопросов используйте 0–0.3, для текстов и идей — 0.7–1.0.

Стриминг

Для интерактивных приложений используйте стриминг — ответ начинает отображаться сразу, не дожидаясь полной генерации:

with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Расскажи о трёх главных трендах в ИИ"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Мультимодальность: работа с изображениями

Claude умеет анализировать изображения — полезно для описания скриншотов, чтения документов и извлечения данных из графиков:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data
                }
            },
            {
                "type": "text",
                "text": "Опиши, что изображено на скриншоте"
            }
        ]
    }]
)

Поддерживаемые форматы: JPEG, PNG, GIF, WebP. Максимальный размер — 5 МБ на изображение. О мультимодальных моделях в целом — в нашей обзорной статье.

Tool Use (вызов функций)

Claude поддерживает вызов функций — модель определяет, когда нужно вызвать внешний инструмент, и формирует структурированный запрос:

tools = [{
    "name": "get_weather",
    "description": "Получить текущую погоду в городе",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "Название города"}
        },
        "required": ["city"]
    }
}]

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Какая погода в Москве?"}]
)

# Claude вернёт tool_use блок с {"city": "Москва"}
for block in message.content:
    if block.type == "tool_use":
        print(f"Вызов функции: {block.name}({block.input})")

Tool Use — основа для создания ИИ-агентов, которые взаимодействуют с внешними сервисами: базами данных, API, файловыми системами.

Обработка ошибок

from anthropic import RateLimitError, APIStatusError
import time

def safe_request(messages, retries=3):
    for attempt in range(retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=1024,
                messages=messages
            )
        except RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limit, жду {wait} сек...")
            time.sleep(wait)
        except APIStatusError as e:
            print(f"API ошибка {e.status_code}: {e.message}")
            raise
    raise Exception("Превышено число попыток")

Лимиты по умолчанию: 50 запросов в минуту, 40 000 токенов в минуту. Для продакшена запросите повышение через Anthropic Console.

Claude vs OpenAI API: ключевые отличия

Системный промпт — отдельный параметр, а не сообщение. Нет параметра n (количество вариантов ответа) — Claude генерирует один ответ. Нет function_calling — вместо него tool_use с похожим, но не идентичным синтаксисом. Контекст 200K токенов по умолчанию для всех моделей — у OpenAI это зависит от модели. Формат ответа — массив content блоков, а не один message.content строкой.

Подробнее: Полный гайд по LLM для разработчиков

Быстрый старт с Anthropic API

pip install anthropic

Базовый запрос:

import anthropic
client = anthropic.Anthropic(api_key='sk-ant-...')
message = client.messages.create(
    model='claude-sonnet-4-6',
    max_tokens=1024,
    messages=[{'role': 'user', 'content': 'Объясни квантовые вычисления'}]
)
print(message.content[0].text)

Модели Claude: выбор для задачи

Streaming

with client.messages.stream(
    model='claude-sonnet-4-6', max_tokens=1024,
    messages=[{'role': 'user', 'content': 'Напиши статью об ИИ'}]
) as stream:
    for text in stream.text_stream:
        print(text, end='', flush=True)

Tool Use (Function Calling)

Claude поддерживает вызов внешних инструментов. Определите инструменты в параметре tools, Claude вернёт stop_reason='tool_use' с именем инструмента и аргументами. После вызова передайте результат обратно в следующем сообщении с role='tool'.

Vision: анализ изображений

Claude 3+ поддерживает передачу изображений в формате base64 или URL. Максимум 5 изображений за запрос. Поддерживаемые форматы: JPEG, PNG, GIF, WebP. Максимальный размер: 5MB на изображение, 5 000×5 000 пикселей.

Batch API: скидка 50%

Message Batches API позволяет отправить до 10 000 запросов одним батчем. Обработка занимает до 24 часов, стоимость — 50% от стандартной цены. Идеально для массовой обработки данных, генерации контента, классификации.

Лучшие практики

• Всегда указывайте max_tokens — без этого запрос может вернуть ошибку
• Проверяйте stop_reason: 'end_turn' — нормал, 'max_tokens' — обрезан
• Используйте retry с exponential backoff для ошибок 529 (overload)
• Системный промпт в system параметре, не в messages
• Для JSON-вывода добавьте в системный промпт 'Отвечай только JSON без объяснений'