Перейти к содержимому
TelegramGitHub

Claude AI Bible, глава 17: Anthropic API

Главная мысль: API — основа всех продуктов Claude. Он нужен для работы без человека, внутри другой программы или в большом объёме, а для разговоров чат лучше и дешевле.

Прошлые главы, вплоть до главы о MCP, говорили о готовых продуктах. API — это базовая платформа, на которой они построены. С ним вы уже не пользуетесь готовым продуктом, а строите своё. Поэтому дальше автор пишет для тех, кто не боится терминала и пары строк кода, а программистом быть необязательно. Темы главы: когда брать API, ключ, первый вызов, устройство запроса, история, streaming, цена, prompt caching, Batch API и ошибки.

Схема: программа отправляет запрос в Messages API, ответ добавляется в историю, и история уходит со следующим запросом

Схему читают слева направо, а потом по нижней петле: API ничего не помнит, поэтому историю каждый раз отправляете вы.

Автор сначала отговаривает от API: самая дорогая ошибка — писать код там, где хватило бы подписки. Если работу ведёт человек, по одному разговору, то чат-приложение быстрее, дешевле и безопаснее. В нём уже есть загрузка файлов, память проекта и фиксированная цена за месяц, а на API то же самое строят неделями.

API нужен в трёх случаях: работа идёт без человека (по расписанию или событию), Claude работает внутри другой программы (читает из базы, пишет в CRM) или одна операция повторяется тысячи раз. Если чат вас устраивает, оставайтесь в нём. Но мысль «пусть это работает каждое утро» или «для каждой строки файла» означает, что пора на API.

Схема: разговор с человеком ведёт к чат-приложению, а работа без человека, внутри программы или в объёме — к API

Многие считают API дешёвой заменой Pro или Max, но это ошибка. API оплачивается за токены и отдельно от подписки (глава 4), поэтому самодельный чат-бот обычно выходит дороже и хуже. API экономит на автоматизации и объёме, а не на разговорах.

API оплачивается отдельно, через Anthropic Console (console.anthropic.com). Организацию компании автор советует заводить на общую почту, а не на личную.

API-ключ — это секретная строка sk-ant-..., по которой Anthropic узнаёт вас и выставляет счёт. Кто знает ключ, тот может тратить ваши деньги и читать, что ваше приложение отправляет Claude, поэтому правила такие:

  • Не кладите ключ в код репозитория: боты постоянно ищут такие строки на GitHub.
  • Храните его в переменной окружения, а на сервере — в менеджере секретов.
  • Давайте каждому приложению свой ключ, чтобы при утечке отозвать только его.
  • Задайте лимит расходов в Console и меняйте ключи по графику, особенно после ухода сотрудника.

Задание автора: создать ключ book-experiments и лимит $10, которого хватит на всю главу.

Окно терминала
export ANTHROPIC_API_KEY="sk-ant-..." # ключ живёт в окружении, а не в коде
pip install anthropic==2.8.0

Почти всё идёт через один endpoint — Messages API: вы отправляете разговор с настройками и получаете следующее сообщение Claude. Даже вызов инструментов и зрение (vision) — вариации этого вызова. Автор показывает его через curl, а потом через Python SDK, который сам читает ключ из окружения и отдаёт текст как message.content[0].text. Новый запрос автор советует сначала собрать в Workbench, песочнице Console, а затем выгрузить оттуда готовый код.

Большую часть работы несут четыре поля:

ПолеЧто задаёт
modelМодель: claude-opus-4-8 для трудных задач, claude-sonnet-4-6 для обычных, claude-haiku-4-5-20251001 для массовых
messagesРазговор: ходы с ролью user (вы) или assistant (Claude)
systemSystem prompt: роль, правила и контекст на весь разговор
max_tokensОбязательный жёсткий потолок длины ответа в токенах

Имена моделей меняются, их сверяют с docs.claude.com. Самое сильное поле — system, хотя новички о нём забывают: в примере автора оно делает из Claude аналитика грузовой компании, который называет допущение за каждой цифрой. А max_tokens — не цель, а предохранитель: он обрывает слишком длинный ответ и ограничивает цену вызова. Обычно Claude заканчивает ответ раньше.

Поле content бывает строкой или списком блоков для картинок и инструментов (глава 19). Из необязательных полей temperature (от 0 до 1) задаёт случайность: низкое значение нужно для извлечения и классификации, высокое — для идей. Кроме того, stop_sequences останавливает ответ на заданной строке, а metadata помечает запрос для учёта.

Пояснение: в SDK anthropic 2.8.0 у messages.create нет аргумента temperature. Прежде чем на него полагаться, проверьте документацию для своей модели.

API не хранит состояние (stateless): между вызовами он ничего не помнит. Чтобы продолжить, вы добавляете в messages ответ Claude с ролью assistant, затем новый вопрос и отправляете всё заново. Автор видит в этом плюс, потому что вы решаете, что видит модель: историю можно обрезать, править и хранить в своей базе. Но каждый ход дороже прошлого, ведь вы снова платите за всю историю.

Если многошаговый разговор (multi-turn) ведёт себя странно, напечатайте messages. Роли должны чередоваться и начинаться с user, иначе будет ошибка.

Без streaming API отдаёт ответ целиком, а со streaming текст приходит частями, как в чате. Человеку так кажется быстрее, а длинный ответ реже упирается в таймаут. В SDK text_stream отдаёт куски текста, а get_final_message() в конце возвращает весь ответ вместе с числом токенов. Однако для фоновых задач streaming только усложняет код.

Платят за входные токены (всё, что отправили) и выходные (ответ), причём выходные дороже. Рычагов четыре:

  1. Модель. Это самый сильный рычаг: цены отличаются в разы. Opus нужен для трудного анализа и кода, Sonnet — для середины, Haiku — для массовой классификации и извлечения. Автор часто ставит Haiku первым проходом, а спорное отдаёт Sonnet или Opus.
  2. Низкий max_tokens: ждёте абзац — ставьте 300, а не 4096.
  3. Короткая история: старые ходы заменяют кратким пересказом или отправляют только несколько последних.
  4. stop_sequences: генерация останавливается на метке вроде END_OF_LIST.

Например, управляющая компания в Манчестере отвечала жильцам через Opus и платила около £400 в месяц. Около 70% писем были простыми, их отдали Haiku, сложные споры оставили Sonnet, а system prompt сделали строже, чтобы ответы стали короче. В итоге счёт упал ниже £60, а жильцы разницы не заметили.

Если каждый вызов несёт тот же длинный system prompt или полис на 50 страниц, вы каждый раз платите за неизменный текст. Prompt caching хранит помеченное начало запроса у Anthropic. Первый вызов немного доплачивает за запись, а следующие платят за эту часть малую долю цены и отвечают быстрее.

Отсюда правило: стабильное — в начало, меняющееся — в конец. Срок жизни кэша и скидку автор советует сверять с документацией, потому что они меняются.

Схема: первый вызов пишет стабильное начало запроса в кэш, следующие читают его дешевле и быстрее

Ниже наш вариант запроса с кэшем. Это настоящий вызов: нужен ключ, и он стоит денег.

import anthropic
client = anthropic.Anthropic() # ключ берётся из ANTHROPIC_API_KEY
POLICY = open("policy.txt", encoding="utf-8").read() # тысячи токенов, одинаковы в каждом вызове
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[{"type": "text", "text": POLICY,
"cache_control": {"type": "ephemeral"}}], # кэшировать это начало
messages=[{"role": "user", "content": "Покрывает ли полис протечку из лопнувшей трубы?"}],
)
print(message.content[0].text)

Messages API синхронный, поэтому 10 000 вызовов в цикле идут медленно и упираются в лимиты. Batch API принимает их одним пакетом и обрабатывает в фоне, обычно за сутки. Вы теряете скорость, но получаете скидку и объём без забот о лимитах. Ответы сопоставляют со входом по custom_id. Если никто не ждёт каждый ответ, например при описании товаров для каталога или разметке 200 отзывов по темам, автор советует именно Batch API.

Код, который ходит по сети, будет падать. Лимит запросов (rate limit) ограничивает запросы и токены в минуту и растёт с уровнем аккаунта (usage tier). Превышение даёт код 429, и это не баг, а просьба сбавить темп.

На 429, 500 и 529 (перегрузка) отвечают повтором запроса (retry) с паузой, которая каждый раз удваивается, плюс небольшая случайная добавка (backoff). SDK делает это сам. А вот 400 (плохой запрос), 401 (неверный ключ) и 403 (нет прав) повторять бесполезно, их надо исправить.

Схема: успех проверяют по файлу, ошибки 429 и 5xx SDK повторяет, ошибки 400, 401 и 403 исправляют и пишут в лог

Итак, временные сбои повторяет SDK, постоянные громко пишут в лог, а успех задачи проверяют явно. Например, финтех в Сингапуре каждую ночь раскладывал транзакции по категориям. Однажды API отвечал 529, повторов в коде не было, и задача молча падала девять дней, а пустую папку с отчётами команда сочла признаком затишья. Исправление заняло полдня: повторы, сигнал в Slack при отсутствии файла и идемпотентность, чтобы повторный запуск не считал транзакцию дважды. Однако восстанавливать разметку за девять дней пришлось гораздо дольше.

  • API нужен для работы без человека, внутри других программ и в большом объёме, но для разговоров он не дешевле подписки.
  • API-ключ хранят в окружении или менеджере секретов, свой на каждое приложение и с лимитом расходов.
  • Запрос состоит из model, messages, необязательного system и обязательного max_tokens.
  • API не хранит состояние, поэтому вы отправляете и оплачиваете историю в каждом вызове.
  • Самый сильный рычаг цены — выбор модели, затем max_tokens и короткая история.
  • Prompt caching удешевляет повторяющееся начало запроса, а Batch API меняет скорость на скидку.
  • Ошибки 429 и 5xx повторяют с backoff, остальные ошибки 4xx исправляют, а сбой должен быть заметен.
ТерминЗначение
Messages APIГлавный endpoint: разговор на входе, сообщение Claude на выходе
statelessAPI не помнит прошлые вызовы
streamingОтвет приходит частями
prompt cachingНеизменное начало запроса в кэше стоит дешевле
Batch APIПакет запросов в фоне со скидкой
лимит запросов (rate limit)Запросы и токены в минуту
повтор запроса (retry)Повтор после временной ошибки с паузой (backoff)
  • Разметку тысяч строк отдавайте Haiku через Batch API, а не циклу синхронных вызовов.
  • Ключ храните в секретах оркестратора (Airflow, CI), а не в коде DAG.
  • Задача с LLM по расписанию проверяет свой результат, а её перезапуск не дублирует строки.

Все примеры книги вызывают платный API, поэтому мы проверили их без ключа (ch17_api_mock.py). Работает настоящий SDK anthropic, но запросы ловит поддельный HTTP-транспорт, а ответы и токены (слово = токен) выдуманы.

def fake_api(request):
body = json.loads(request.content) # что SDK отправил в API
calls.append(body)
status = plan.pop(0) if plan else 200 # заранее заданные коды ошибок
...
client = anthropic.Anthropic(api_key="sk-ant-fake", max_retries=4,
http_client=httpx2.Client(transport=httpx2.MockTransport(fake_api)))
1. Что уходит в API
поля запроса: max_tokens, messages, model, system
текст ответа: ответ номер 1 | usage: 14 / 3
2. История хранится у вас
сообщений: 1, роли: u, input_tokens: 5
сообщений: 3, роли: u-a-u, input_tokens: 15
сообщений: 5, роли: u-a-u-a-u, input_tokens: 23
3. Ошибки и повторы
перегрузка 529, 529, потом успех: попыток 3, итог: успех
лимит 429 пять раз подряд: попыток 5, итог: RateLimitError: отложить задачу в очередь
плохой запрос 400: попыток 1, итог: BadRequestError 400: не повторять, записать в лог

Входных токенов с каждым ходом больше. Ошибку 529 SDK повторил сам, на 429 сдался после пяти попыток, а 400 повторять не стал.

  1. Почему самодельный чат-бот на API обычно не экономит деньги?
  2. Почему каждый ход разговора через API дороже прошлого, и что с этим делать?
  3. Когда streaming нужен, а когда мешает?
  4. Как сложить части запроса, чтобы prompt caching работал?
  5. Какие ошибки API повторять, а какие нет, и почему?

Предыдущая: Model Context Protocol (MCP). Следующая: Claude Agent SDK.