Что получится
консоль провайдера ──► ключ sk-ant-… (виден один раз)
│
read -rs ──► переменная ANTHROPIC_API_KEY в текущей оболочке, не в истории
│
curl ─ POST /v1/messages ─► JSON: content · stop_reason · usage
У OpenAI и Google путь тот же: ключ в консоли, переменная окружения, POST с JSON. Отличаются адрес, заголовки и форма ответа.
Делаем
Создаём ключ и ставим лимит трат
В консоли Claude Platform (
platform.claude.com) — раздел API keys, кнопка создания ключа. Ключ показывают один раз: копируем сразу в менеджер паролей. Там же, в биллинге, ставим месячный лимит трат — для экспериментов хватит $10: при нём ошибка в цикле не превратится в счёт на сотни.Ключ даёт доступ к деньгам на счёте. Один ключ — одна программа или один компьютер: утёк — отзываем только его («Каждый ключ и токен — на один доступ»).
Кладём ключ в окружение мимо истории
read -rs -p 'API key: ' ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY echo ${#ANTHROPIC_API_KEY} # длина ключа: не 0 — переменная заданаread -sне показывает ввод, и ключ не попадает в~/.bash_history: в истории остаётся только командаread.echo ${#…}печатает длину, а не ключ, — так проверяем, что переменная задана.export ANTHROPIC_API_KEY=sk-ant-…прямо в командной строке оставит ключ в истории («Пароль — не в аргументах команды»).Чтобы не вводить каждый раз — файл с правами только для себя:
install -m 600 /dev/null ~/.config/anthropic-key read -rs k && printf '%s' "$k" > ~/.config/anthropic-key && unset k export ANTHROPIC_API_KEY="$(cat ~/.config/anthropic-key)"В репозиторий ключ не попадает никогда: в
.envи в.gitignore(«Секреты в Docker-стеках», «Секрет в коммите»).Отправляем запрос
Самая дешёвая модель — Haiku 5.5, $0,10 за миллион токенов входа. Размышление у неё включено по умолчанию, для простого вопроса ставим
low:curl -s 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-5-5", "max_tokens": 1024, "output_config": {"effort": "low"}, "messages": [{"role": "user", "content": "Чем docker compose down отличается от stop? Две строки."}] }' > answer.jsonanthropic-version— версия формата API, а не модели;2023-06-01остаётся текущей. Ответ кладём в файл: разбираем его сколько угодно раз, а платим за запрос один.Разбираем ответ
jq -r '.content[] | select(.type == "text") | .text' answer.json # текст ответа jq -r '.stop_reason' answer.json # end_turn — закончила сама jq '.usage' answer.json # счёт в токенахЦена — по
usage(«Токены»):input_tokens × $0,10 + output_tokens × $0,50, делённое на миллион. Вопрос на 30 токенов и ответ на 80 — около $0,00004. Все запросы за день видны в консоли, в разделе использования.stop_reason: "max_tokens"— ответ оборван, поднимаемmax_tokens. Остальные значения — в «Запрос к модели по блокам».Длинный ответ — потоком
Для ответа больше нескольких тысяч токенов добавляем
"stream": true: текст приходит кусками по мере генерации, и соединение не рвётся по таймауту. Ответ — событияcontent_block_deltaс кусками текста; собирать их руками неудобно, поэтому дальше переходим на SDK.Дальше — SDK вместо curl
npm i @anthropic-ai/sdk # TypeScript и JavaScript pip install anthropic # PythonSDK берёт ключ из
ANTHROPIC_API_KEY, сам повторяет запрос при429и5xx(по умолчанию 2 раза с растущей паузой), собирает поток в готовый ответ и даёт типы для всех полей.
Коды ошибок
| Код | Тип | Что значит | Повторять? |
|---|---|---|---|
400 |
invalid_request_error |
ошибка в запросе: поле, модель, формат; или нет денег на балансе | нет, чиним запрос |
401 |
authentication_error |
ключ неверный или пустой | нет |
402 |
billing_error |
проблема с оплатой | нет |
403 |
permission_error |
у ключа нет доступа к модели или функции | нет |
413 |
request_too_large |
запрос больше лимита, например PDF больше 32 МБ | нет, делим |
429 |
rate_limit_error |
лимит аккаунта в минуту | да, после retry-after |
500 |
api_error |
ошибка на стороне сервиса | да |
529 |
overloaded_error |
сервис перегружен | да, с растущей паузой |
Как проверить
Отправляем тот же запрос через count_tokens («Токены», шаг 2): input_tokens оттуда должен совпасть
с usage.input_tokens из answer.json. Совпало — понимаем, за что платим. Сам запрос появляется в консоли,
в разделе использования.
Если не работает
401 и authentication_error — invalid x-api-key
- Причина
- Переменная пустая (ключ задан в другой оболочке), ключ скопирован с пробелом или отозван.
- Делаем
echo ${#ANTHROPIC_API_KEY}— длина без вывода ключа; 0 — переменной нет в этой оболочке. Отозван — создаём новый в консоли.
400 с текстом про низкий баланс кредитов
- Причина
- На счёте нет денег: API работает по предоплате или с картой, подписка claude.ai сюда не относится.
- Делаем
- Пополняем баланс в разделе биллинга консоли; там же ставим лимит трат и автопополнение по желанию.
429 и rate_limit_error
- Причина
- Превышен лимит запросов или токенов в минуту для уровня аккаунта; у нового аккаунта лимиты низкие.
- Делаем
- Ждём столько секунд, сколько в заголовке
retry-after, и повторяем; лимиты растут с суммой оплат.
529 и overloaded_error
- Причина
- Перегружен сам сервис, а не наш аккаунт.
- Делаем
- Повтор через несколько секунд с растущей паузой; SDK делает это сам, по умолчанию 2 повтора.
jq печатает null вместо текста ответа
- Причина
- Первый блок в
content—thinking, а у него нет поляtext. - Делаем
- Берём блоки по типу:
jq -r '.content[] | select(.type == "text") | .text'.