Полное руководство по разработке с Claude API: от ключа до продакшена

Claude API предоставляет доступ к трём классам моделей: Opus (максимальная точность), Sonnet (баланс скорости и качества) и Haiku (минимальная задержка).

В отличие от OpenAI API, здесь нет system-роли в массиве messages — системный промпт передаётся отдельным параметром верхнего уровня.

Версионирование моделей жёсткое: строка вида claude-sonnet-4-5-20250929 гарантирует воспроизводимость результатов.

Зарегистрируйтесь на console.anthropic.com.
Перейдите в Settings → API Keys → Create Key.
Ключ отображается один раз — сохраните в переменную окружения немедленно.

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

Кредитные лимиты. Новый аккаунт стартует на Tier 1: 50 000 входящих + 10 000 исходящих токенов в минуту (TPM). Tier автоматически повышается при накопленных расходах: $5 → Tier 2, $50 → Tier 3. Текущий лимит и использование доступны в Console → Usage.

Не хардкодьте ключ в коде. Для локальной разработки используйте .env + python-dotenv:

# .env ANTHROPIC_API_KEY=sk-ant-api03-...

from dotenv import load_dotenv import os load_dotenv() api_key = os.environ["ANTHROPIC_API_KEY"]

pip install anthropic

import anthropic client = anthropic.Anthropic() # читает ANTHROPIC_API_KEY из окружения message = client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=256, system="Отвечай строго по делу, без вводных фраз.", messages=[ {"role": "user", "content": "Что такое контекстное окно модели?"} ] ) print(message.content[0].text) # >>> Контекстное окно — максимальная длина последовательности токенов... print(f"Использовано токенов: {message.usage.input_tokens} in / {message.usage.output_tokens} out")

npm install @anthropic-ai/sdk

import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // читает process.env.ANTHROPIC_API_KEY const message = await client.messages.create({ model: "claude-sonnet-4-5-20250929", max_tokens: 256, system: "Отвечай строго по делу, без вводных фраз.", messages: [{ role: "user", content: "Что такое контекстное окно модели?" }], }); console.log(message.content[0].text); console.log(`Tokens: ${message.usage.input_tokens}/${message.usage.output_tokens}`);

curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-haiku-4-5-20251001", "max_tokens": 128, "messages": [{"role": "user", "content": "Ping"}] }'

Заголовок anthropic-version обязателен. Актуальная версия: 2023-06-01.

Модели Sonnet и Opus поддерживают мультимодальный ввод. Изображение передаётся как base64 или по URL.

import base64, anthropic with open("screenshot.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") client = anthropic.Anthropic() message = client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=512, messages=[ { "role": "user", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": image_data, }, }, {"type": "text", "text": "Перечисли все UI-элементы на скриншоте."}, ], } ], ) print(message.content[0].text)

Поддерживаемые форматы: image/jpeg, image/png, image/gif, image/webp. Лимит — 20 МБ на изображение, до 100 изображений в одном запросе.

Tool Use позволяет модели вернуть структурированный вызов функции вместо свободного текста.

import anthropic, json client = anthropic.Anthropic() tools = [ { "name": "get_stock_price", "description": "Возвращает текущую цену акции по тикеру.", "input_schema": { "type": "object", "properties": { "ticker": {"type": "string", "description": "Тикер, например AAPL"} }, "required": ["ticker"], }, } ] response = client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=512, tools=tools, messages=[{"role": "user", "content": "Какая цена акции Apple?"}], ) # Если модель решила вызвать инструмент: if response.stop_reason == "tool_use": tool_block = next(b for b in response.content if b.type == "tool_use") print(f"Вызов: {tool_block.name}, аргументы: {json.dumps(tool_block.input)}") # >>> Вызов: get_stock_price, аргументы: {"ticker": "AAPL"}

После получения результата инструмента добавьте его в messages с ролью user и type: tool_result, затем отправьте повторный запрос для финального ответа.

Нативного JSON Mode нет — принудительный JSON-вывод достигается через системный промпт:

message = client.messages.create( model="claude-haiku-4-5-20251001", max_tokens=256, system="Отвечай ТОЛЬКО валидным JSON. Без пояснений, без markdown-блоков.", messages=[ { "role": "user", "content": "Верни объект с полями name='Alice' и age=30." } ], ) import json data = json.loads(message.content[0].text) print(data) # {'name': 'Alice', 'age': 30}

Для гарантированного JSON используйте Tool Use с input_schema нужной формы — это надёжнее, чем промпт-инструкция.

Anthropic Console → Workbench — интерактивная среда для итерации над промптами без написания кода.

Что доступно в Workbench:

Переключение моделей (Opus / Sonnet / Haiku) с сохранением истории.
Настройка temperature (0.0–1.0), max_tokens, top_p, top_k.
Сравнение двух промптов рядом (A/B).
Экспорт в код: кнопка Get Code генерирует готовый сниппет на Python, TypeScript или cURL.

Prompt Generator (вкладка внутри Workbench): опишите задачу на естественном языке → модель создаёт структурированный системный промпт. Результат доступен для немедленного редактирования.

# Промпт, экспортированный из Workbench: message = client.messages.create( model="claude-opus-4-5-20251101", max_tokens=1024, temperature=0.2, system="You are a senior code reviewer. ...", # сгенерировано Workbench messages=[{"role": "user", "content": "{{CODE}}"}], )

import anthropic, time client = anthropic.Anthropic() def create_with_retry(messages, model="claude-sonnet-4-5-20250929", max_retries=5): for attempt in range(max_retries): try: return client.messages.create( model=model, max_tokens=512, messages=messages, ) except anthropic.RateLimitError as e: if attempt == max_retries - 1: raise wait = 2 ** attempt # 1, 2, 4, 8, 16 секунд print(f"Rate limit. Повтор через {wait}с...") time.sleep(wait) except anthropic.APIStatusError as e: if e.status_code == 529: # overloaded time.sleep(60) else: raise

Python SDK автоматически делает 2 retry по умолчанию. Кастомное число: anthropic.Anthropic(max_retries=5).

Если stop_reason == "max_tokens", ответ обрезан. Проверяйте явно:

if message.stop_reason == "max_tokens": raise ValueError("Ответ обрезан. Увеличьте max_tokens или сократите промпт.")

Используйте метод count_tokens — он не тарифицируется:

response = client.messages.count_tokens( model="claude-sonnet-4-5-20250929", system="Ты помощник по коду.", messages=[{"role": "user", "content": "Объясни алгоритм быстрой сортировки."}], ) print(response.input_tokens) # >>> 42

Для оценки: 1 токен ≈ 4 символа английского текста, ≈ 3–3.5 символа русского. Точный подсчёт — только через API или библиотеку anthropic-tokenizer.

Единственное изменение — строка model. Все остальные параметры идентичны:

# Для задач, где точность критична (сложный анализ, юридические тексты) model = "claude-opus-4-5-20251101" # $15 / $75 за 1M токенов (in/out) # Баланс качества и скорости (большинство продакшн-задач) model = "claude-sonnet-4-5-20250929" # $3 / $15 за 1M токенов # Максимальная скорость, минимальная стоимость (классификация, routing) model = "claude-haiku-4-5-20251001" # $0.25 / $1.25 за 1M токенов

Да. Параметр stream=True возвращает SSE-поток:

with client.messages.stream( model="claude-sonnet-4-5-20250929", max_tokens=512, messages=[{"role": "user", "content": "Напиши функцию бинарного поиска на Python."}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True)

API stateless. Контекст передаётся вручную через массив messages:

history = [] def chat(user_input: str) -> str: history.append({"role": "user", "content": user_input}) response = client.messages.create( model="claude-sonnet-4-5-20250929", max_tokens=512, messages=history, ) assistant_text = response.content[0].text history.append({"role": "assistant", "content": assistant_text}) return assistant_text

При длинных диалогах следите за суммарным числом токенов — при превышении контекстного окна (200k для Sonnet/Opus) старые сообщения нужно усекать вручную.

Актуальная документация: docs.anthropic.com

Console: console.anthropic.com

Полное руководство по разработке с Claude API: от ключа до продакшена

Получение доступа и настройка окружения

Anthropic Console и API-ключ

Переменные окружения (рекомендуемый способ)

Установка SDK и первый запрос

Python SDK

Hello World через messages.create:

JavaScript / TypeScript SDK

Прямой вызов через cURL (REST API)

Продвинутые возможности

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

Function Calling (Tool Use)

JSON Mode через параметр system

Workbench и генерация промптов

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

Коды ошибок и стратегии

Retry с экспоненциальным backoff (Python)

Обработка max_tokens exceeded

FAQ

Как считать токены до отправки запроса?

Разница между моделями в коде

Поддерживает ли API потоковую передачу (streaming)?

Как сохранять контекст между запросами?