basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Первый запрос к API: ключ мимо истории, curl, ответ и расход

    Получаем ключ API, кладём его в переменную окружения так, чтобы он не попал в историю оболочки, отправляем запрос curl к самой дешёвой модели и разбираем ответ: текст, причину остановки и счёт в токенах. Понадобятся curl, jq и аккаунт с привязанной картой или пополненным балансом.

    Что получится

    консоль провайдера ──► ключ sk-ant-… (виден один раз)
                              │
                 read -rs ──► переменная ANTHROPIC_API_KEY в текущей оболочке, не в истории
                              │
    curl ─ POST /v1/messages ─► JSON: content · stop_reason · usage

    У OpenAI и Google путь тот же: ключ в консоли, переменная окружения, POST с JSON. Отличаются адрес, заголовки и форма ответа.

    Делаем

    1. Создаём ключ и ставим лимит трат

      В консоли Claude Platform (platform.claude.com) — раздел API keys, кнопка создания ключа. Ключ показывают один раз: копируем сразу в менеджер паролей. Там же, в биллинге, ставим месячный лимит трат — для экспериментов хватит $10: при нём ошибка в цикле не превратится в счёт на сотни.

      Ключ даёт доступ к деньгам на счёте. Один ключ — одна программа или один компьютер: утёк — отзываем только его («Каждый ключ и токен — на один доступ»).

    2. Кладём ключ в окружение мимо истории

      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-стеках», «Секрет в коммите»).

    3. Отправляем запрос

      Самая дешёвая модель — 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.json

      anthropic-version — версия формата API, а не модели; 2023-06-01 остаётся текущей. Ответ кладём в файл: разбираем его сколько угодно раз, а платим за запрос один.

    4. Разбираем ответ

      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. Остальные значения — в «Запрос к модели по блокам».

    5. Длинный ответ — потоком

      Для ответа больше нескольких тысяч токенов добавляем "stream": true: текст приходит кусками по мере генерации, и соединение не рвётся по таймауту. Ответ — события content_block_delta с кусками текста; собирать их руками неудобно, поэтому дальше переходим на SDK.

    6. Дальше — SDK вместо curl

      npm i @anthropic-ai/sdk        # TypeScript и JavaScript
      pip install anthropic          # Python

      SDK берёт ключ из 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'.