Первый вызов Claude API: ключ, модель, ответ

Ты уже знаешь, что у Claude есть «провод» для программ — API. Но стоит дойти до дела, и со всех сторон сыплются незнакомые слова: «ключ», «модель», «токены», «JSON в ответе». Кажется, что без диплома по информатике тут не разобраться.

На самом деле первый вызов API собирается из четырёх кубиков. Если понять, что значит каждый, остальное складывается само. Давай разберём их по очереди — на примере, который ты сможешь повторить руками.

Четыре кубика собираются в один запрос к Claude API

Четыре кубика любого запроса

Представь, что ты отправляешь посылку. Тебе нужны: твоя подпись (чтобы на почте знали, кто ты), адрес получателя, само содержимое посылки и обратный конверт для ответа. Запрос к API устроен ровно так же.

Ключ доступа — твоя подпись. Длинная строка вида sk-ant-..., которую выдаёт твой аккаунт. По ней сервис понимает, кто прислал запрос и с чьего баланса списать оплату.
Модель — кто именно будет отвечать. У Claude несколько моделей: одни умнее и дороже, другие быстрее и дешевле. Ты указываешь имя модели строкой, например что-то из семейства Haiku для простых задач.
Сообщение — то, что ты хочешь спросить. Твой текст, завёрнутый в простую структуру «роль: пользователь, текст: вот мой вопрос».
Ответ — то, что вернётся. Не просто строка, а аккуратная коробочка с полями, из которой ты достаёшь нужное.

Эти четыре вещи есть в любом запросе — хоть из терминала, хоть из кода на Python или JavaScript. Меняется только обёртка.

Как это выглядит вживую

Вот тот самый запрос целиком. Не пугайся длины — сейчас разберём каждую строчку:

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",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Привет! Объясни, что такое API, одним предложением."}
    ]
  }'

Разложим по полкам:

Первая строка — адрес, куда стучимся. У Claude это всегда /v1/messages.
x-api-key — твой ключ. Тут он подставляется из переменной $ANTHROPIC_API_KEY, чтобы не светить его прямо в команде (про это ниже).
anthropic-version — какой версией API ты пользуешься. Просто фиксированная строчка, можно не вникать.
В блоке -d лежит сама посылка: какую model зовём, сколько максимум токенов разрешаем в ответе (max_tokens) и массив messages с твоим текстом.

Запустил — и через секунду в терминал прилетит ответ.

Совет

Не вставляй ключ прямо в команду. Сохрани его в переменную окружения один раз: export ANTHROPIC_API_KEY="sk-ant-..." — и дальше обращайся через $ANTHROPIC_API_KEY. Так ключ не попадёт ни в историю команд на видном месте, ни в код, который ты случайно выложишь на GitHub.

Что лежит в ответе

Самое непривычное для новичка — что ответ приходит не голым текстом, а структурой. Выглядит он примерно так:

{
  "id": "msg_...",
  "model": "claude-haiku-4-5",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "API — это способ программам обмениваться данными по заранее оговорённым правилам."}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 18, "output_tokens": 21}
}

Кажется, что много лишнего, но на деле всё по делу:

content — то, ради чего всё затевалось. Внутри лежит текст ответа Claude. Именно его ты достаёшь в своей программе.
stop_reason — почему модель остановилась. end_turn значит «договорила сама». Если бы тут было max_tokens, это сигнал, что ответ обрезался по лимиту — повод поднять max_tokens в запросе.
usage — сколько токенов ушло на запрос и на ответ. По этим числам считается оплата, так что это твой счётчик расхода.

Когда поймёшь, что текст всегда лежит в content, а usage — это касса, ответ перестаёт выглядеть страшно. Это просто опись посылки рядом с её содержимым.

Где спотыкаются на первом вызове

Почти все промахи в первый раз сводятся к двум-трём типовым. Если запрос не сработал, начни с них — это сэкономит тебе полчаса гугления.

Важно

Ошибка 401 почти всегда значит, что ключ не подхватился. Проверь, что переменную ANTHROPIC_API_KEY ты задал в том же окне терминала, откуда запускаешь команду: export действует только в текущей сессии. Открыл новую вкладку — задай заново.

Второй частый камень — имя модели. Сервис не угадывает, что ты имел в виду: строка должна совпадать буква в букву. Опечатка в model вернёт ошибку, а не «ближайшую похожую» модель. Если не уверен в точном имени — посмотри список в документации, не пиши по памяти.

Третье — формат тела запроса. В блоке -d лежит JSON, и он придирчив: лишняя запятая после последнего поля, одинарные кавычки вместо двойных внутри JSON или забытая закрывающая скобка — и сервер ответит, что не понял посылку. Когда собираешь запрос руками, проще скопировать рабочий пример целиком и менять в нём только текст вопроса, а не печатать всю структуру с нуля.

И помни про деньги: каждый удачный вызов списывает копейки с баланса по числам из usage. Для первых экспериментов это незаметно, но max_tokens всё равно стоит держать скромным — он ограничивает не только длину, но и потолок расхода на один ответ.

С чего начать на практике

Не пытайся выучить все поля сразу. Запомни логику: ключ — подпись, модель — кто отвечает, сообщение — твой вопрос, ответ — структура, из которой берёшь content. Дальше всё наращивается поверх этого: история диалога — это просто несколько сообщений в messages, инструменты и форматы ответа — дополнительные поля в той же посылке.

Самый честный способ это прочувствовать — отправить запрос своими руками, увидеть прилетевший JSON и поковыряться в нём. После одного удачного вызова мистика заканчивается, и API становится обычным инструментом в наборе.

Если хочешь пройти этот путь по шагам — от первого ключа до рабочего мини-приложения на Claude — загляни сюда: