Как использовать Claude API: практические примеры на Python

Claude API от Anthropic — один из самых востребованных интерфейсов для работы с LLM. Модели Claude стабильно занимают топовые позиции в бенчмарках, а API предлагает функциональность, которой нет у конкурентов: расширенное мышление (extended thinking), tool use с JSON Schema и нативную работу с PDF.

Это руководство — практическое. Минимум теории, максимум рабочего кода. Все примеры на Python с использованием официального SDK.

Настройка

Установите SDK и получите API-ключ:

pip install anthropic

API-ключ создаётся в Anthropic Console. Сохраните его в переменной окружения:

export ANTHROPIC_API_KEY="sk-ant-..."

SDK автоматически подтянет ключ из переменной окружения. Явно передавать его в код не нужно.

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

import anthropic

client = anthropic.Anthropic()

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

print(message.content[0].text)

Параметры:

• model — идентификатор модели. Актуальные: claude-opus-4-6 (самая мощная), claude-sonnet-4-6 (баланс скорости и качества), claude-haiku-4-5-20251001 (быстрая и дешёвая)
• max_tokens — максимум токенов в ответе. Обязательный параметр
• messages — массив сообщений диалога

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

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    temperature=0.3,
    system="Ты технический писатель. Пиши кратко, используй примеры кода.",
    messages=[
        {"role": "user", "content": "Как обработать ошибки в async Python?"}
    ]
)

temperature контролирует случайность: 0 — детерминированный ответ, 1 — максимальная вариативность. Для кода и аналитики используйте 0–0.3, для текстов — 0.5–0.7.

Многоходовый диалог

Claude не хранит историю между запросами. Для диалога передавайте всю историю сообщений:

messages = [
    {"role": "user", "content": "Что такое декоратор в Python?"},
    {"role": "assistant", "content": "Декоратор — это функция, которая принимает другую функцию и расширяет её поведение без изменения исходного кода..."},
    {"role": "user", "content": "Покажи пример декоратора для замера времени выполнения."}
]

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=messages
)

Streaming

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

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Напиши обзор паттерна Repository в Python."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Streaming не влияет на стоимость — вы платите за те же токены, просто получаете их постепенно.

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

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

import base64
from pathlib import Path

image_data = base64.standard_b64encode(Path("screenshot.png").read_bytes()).decode()

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

Поддерживаемые форматы: PNG, JPEG, GIF, WebP. Максимальный размер — 20 МБ на изображение.

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

Tool use — возможность Claude вызывать ваши функции. Вы описываете доступные инструменты, Claude решает, когда и с какими параметрами их вызвать.

import json

tools = [
    {
        "name": "get_weather",
        "description": "Получить текущую погоду в указанном городе",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Название города, например: Москва"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Единицы измерения температуры"
                }
            },
            "required": ["city"]
        }
    }
]

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

# Claude вернёт tool_use блок с параметрами
for block in message.content:
    if block.type == "tool_use":
        print(f"Вызов: {block.name}")
        print(f"Параметры: {json.dumps(block.input, ensure_ascii=False)}")

После получения tool_use нужно выполнить функцию и отправить результат обратно:

# Выполняем функцию (ваша логика)
weather_result = {"temperature": 5, "condition": "облачно", "humidity": 78}

# Отправляем результат Claude
followup = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "Какая погода в Москве?"},
        {"role": "assistant", "content": message.content},
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": message.content[0].id,  # ID из tool_use блока
                "content": json.dumps(weather_result, ensure_ascii=False)
            }]
        }
    ]
)

print(followup.content[0].text)
# "В Москве сейчас 5°C, облачно, влажность 78%."

Extended Thinking

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

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000  # лимит на размышления
    },
    messages=[{
        "role": "user",
        "content": "Проанализируй этот SQL-запрос и найди потенциальные проблемы с производительностью: SELECT * FROM orders o JOIN users u ON o.user_id = u.id WHERE o.created_at > '2025-01-01' ORDER BY o.total DESC"
    }]
)

for block in message.content:
    if block.type == "thinking":
        print("Размышления:", block.thinking[:200], "...")
    elif block.type == "text":
        print("Ответ:", block.text)

Extended thinking заметно улучшает качество на сложных задачах: математика, логика, код-ревью, архитектурные решения. Но увеличивает стоимость и время ответа.

Стоимость и оптимизация

Советы по экономии:

• Prompt caching — повторяющиеся системные промпты кешируются, стоимость снижается до 90%
• Выбор модели по задаче — для классификации и простых задач хватает Haiku, для кода и анализа — Sonnet, Opus — для сложных многошаговых задач
• Batches API — для офлайн-обработки больших объёмов со скидкой 50%
• Контроль max_tokens — не ставьте 4096, если ожидаете 200 токенов

Подробнее об архитектуре LLM и выборе между моделями — в нашем гайде по LLM для разработчиков.

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

import anthropic

try:
    message = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Привет"}]
    )
except anthropic.RateLimitError:
    print("Превышен лимит запросов, подождите")
except anthropic.APIStatusError as e:
    print(f"Ошибка API: {e.status_code} — {e.message}")
except anthropic.APIConnectionError:
    print("Не удалось подключиться к API")

SDK автоматически делает ретраи при 429 (rate limit) и 5xx ошибках с экспоненциальной задержкой. Для продакшн-сценариев этого обычно достаточно.

Claude API предоставляет всё необходимое для построения AI-продуктов: от простого чат-бота до сложного AI-агента с tool use. Начните с Sonnet для прототипа, переходите на Opus для задач, требующих максимального качества.