Сложность подключения Claude API не в том, «умеете ли вы отправлять HTTP-запросы», а в нескольких деталях, на которых легко споткнуться: в каком заголовке передаётся ключ, обязателен ли anthropic-version, почему нельзя опустить max_tokens и почему content — это массив, а не строка. Если сделать это правильно, минимальный вызов заработает за десять минут.
Ниже порядок действий: аккаунт и ключ, заголовки запроса, curl, Python, потоковый вывод и параметры, разбор ошибок, безопасность ключа. В конце — как использовать совместимый шлюз как альтернативную точку входа. ID моделей, контекст и биллинг сверяйте с официальной документацией Anthropic и страницей тарифов.
Примечание: Anthropic и Claude — товарные знаки их правообладателей, OpenAI — товарный знак своего правообладателя. Статья носит технический характер. Модели, цены и квоты меняются; перед подключением проверяйте официальную документацию.
1. Подготовка: аккаунт, рабочее пространство и ключ
Claude API использует Anthropic Console для управления аккаунтом, рабочими пространствами, API-ключами и счетами. Перед началом проверьте три вещи:
| Что подготовить | Что уточнить | Пояснение |
|---|---|---|
| Аккаунт | Почта подтверждена, вход в Console работает | Для команды лучше корпоративная почта |
| Рабочее пространство | К какому workspace относится ключ | Workspace определяет участников, ключи и учёт расхода |
| Биллинг | Способ оплаты, платёжные данные, доступный лимит | Ориентируйтесь на то, что показывает Console |
Если команда ещё не решила, кто отвечает за счета, не спешите создавать производственный ключ. После выдачи ключа расход и права привязываются к рабочему пространству, и разделять их задним числом сложнее.
2. Создание API-ключа: шесть шагов
- Откройте Anthropic Console (console.anthropic.com), зарегистрируйтесь или войдите и подтвердите почту.
- Создайте или выберите рабочее пространство. Разделяйте production, тест и личные эксперименты, чтобы не использовать один ключ везде.
- Перейдите на страницу API Keys, создайте новый ключ и укажите назначение в имени, например
prod-backend-2026-10. - Скопируйте ключ и сразу сохраните его в менеджере секретов или переменной окружения. Большинство консолей показывают полное значение только один раз.
- На странице биллинга проверьте способ оплаты, платёжные данные и лимиты. Возможность предоплаты, счёт-фактуры и лимита расходов зависит от фактических опций консоли.
- Задайте переменную окружения локально и отправьте минимальный запрос, чтобы проверить ключ.
export ANTHROPIC_API_KEY="sk-ant-ваш-ключ"
Не записывайте ключ в код, Git-репозиторий, фронтенд или переписку. На этапе тестирования тоже заведите отдельный ключ, чтобы его можно было быстро отозвать.
3. Заголовки запроса и минимальный вызов curl
Эндпоинт Messages API — POST https://api.anthropic.com/v1/messages. Ключевые три заголовка:
| Заголовок | Значение | Назначение |
|---|---|---|
x-api-key |
Ваш API-ключ | Аутентификация ключа Anthropic |
anthropic-version |
2023-06-01 |
Версия API; без неё возможна ошибка |
content-type |
application/json |
Указывает JSON в теле запроса |
Важно: ключ передаётся в x-api-key, а не в Authorization: Bearer. Смешение этих схем — частая причина 401.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "Ты технический ассистент, отвечай кратко.",
"messages": [
{"role": "user", "content": "Объясни в трёх предложениях, что такое API-шлюз."}
]
}'
ID модели в примере — лишь один из доступных вариантов. Актуальные модели, контекст и цены смотрите в официальном Models API и на странице тарифов. В ответе content — массив блоков; текст обычно лежит в content[0].text, но надёжнее перебирать блоки и проверять type == "text".
4. Вызов Messages API из Python
Установите официальный SDK:
pip install anthropic
Минимальный вызов:
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="Ты технический ассистент, отвечай кратко.",
messages=[
{"role": "user", "content": "Объясни в трёх предложениях, что такое API-шлюз."}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
Несколько важных моментов:
system— параметр верхнего уровня, не сообщение с{"role": "system"}. В Messages API роли сообщений в основномuserиassistant.max_tokensобязателен: это максимальная длина ответа. Слишком малое значение обрежет вывод, иstop_reasonпокажетmax_tokens; слишком большое влияет на стоимость и тайм-ауты.resp.content— массив блоков, где могут быть текст, блоки размышления или вызовы инструментов. Не считайте, что там всегда только текст.- Сохраняйте
usageиstop_reason: они нужны для сверки счетов и диагностики.
5. system, max_tokens и потоковый вывод
system задаёт роль, формат вывода и ограничения. Стабильное содержимое ставьте в начало, изменяемый ввод пользователя — в messages: так выше шанс попадания в кэш.
max_tokens — не «чем больше, тем лучше». Это лимит одного ответа, он не меняет стоимость входа. Длинным отчётам и коду нужно больше места, классификации и извлечению — меньше. В production настраивайте значение по типу задачи, а не одно на всё.
Потоковый вывод подходит для длинных ответов и интерактивных интерфейсов:
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="Ты технический ассистент.",
messages=[{"role": "user", "content": "Напиши описание продукта на 200 слов."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Потоковый запрос тоже возвращает usage и stop_reason — не потеряйте их при записи в базу. При работе с нативным HTTP добавьте в тело "stream": true; ответ придёт потоком событий SSE, который разбирают по событиям вроде content_block_delta.
6. Имена моделей и выбор версии
Модели Claude делятся на семейства Opus, Sonnet и Haiku; у них разные позиционирование, контекст и цены. ID модели встречается в двух видах: стабильный псевдоним и снимок с датой. В production заранее решите, какой вариант использовать, и не переносите отображаемое имя из консоли прямо в код.
Рекомендуемый порядок выбора:
- Сначала отберите семейство, которое проходит ваш набор оценки качества.
- Затем сравните задержку, контекст и стоимость.
- В конце убедитесь, что модель доступна в целевом регионе и через выбранный способ подключения.
Модели появляются и снимаются с поддержки, старые ID могут переходить в статус legacy. Храните имя модели в конфигурации или таблице соответствий, чтобы при миграции менять его в одном месте. Актуальный список — в официальном Models API, консоли и на странице тарифов.
7. Как разбирать 401, 429 и 400
| Код | Частая причина | Порядок действий |
|---|---|---|
| 401 | Ключ отсутствует, неверный заголовок, ключ отозван, несовпадение workspace | Проверьте x-api-key, пробелы и переводы строк, статус ключа, base URL |
| 429 | Превышена частота запросов или скорость токенов, резкий рост параллелизма, лимиты | Прочитайте retry-after, используйте экспоненциальную задержку с джиттером, разделите ключи, снизьте параллелизм |
| 400 | Некорректный JSON, нет max_tokens, ошибка в ID модели, превышены параметры |
Сохраните тело ошибки и request id, проверьте тело запроса по полям |
| 404 | Путь или имя модели не существует | Проверьте /v1/messages и ID модели |
| 5xx | Временный сбой на стороне сервиса | Ограниченное число повторов, затем переключение на резервный вход |
При разборе сначала сохраните заголовок request-id. При 401 не думайте сразу о балансе — проверьте заголовок аутентификации и сам ключ. 429 не всегда означает «кончились деньги», это может быть ограничение скорости. 400 чаще всего связано с телом запроса, и сообщение об ошибке обычно указывает конкретное поле.
8. Безопасность ключа и совместимый шлюз
Минимум четыре правила: хранить ключ только в переменных окружения или менеджере секретов; разделять ключи по проектам; настроить оповещения о расходе; регулярно ротировать ключи и отзывать их у уволившихся сотрудников. Долгоживущие ключи не должны попадать во фронтенд, мобильные приложения и публичные репозитории.
Если у команды в Китае есть проблемы с сетью, оплатой или счёт-фактурами, можно использовать шлюз с Anthropic-совместимым эндпоинтом вместо официального адреса. Официальному SDK обычно достаточно изменить base_url и ключ:
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="смотрите список моделей на сайте",
max_tokens=256,
messages=[{"role": "user", "content": "Ответь только OK"}],
)
print(resp.content)
Если шлюз предоставляет только OpenAI-совместимый интерфейс, придётся менять структуру запроса или добавлять слой адаптации — одного изменения base URL недостаточно. При выборе шлюза уточните три вещи: поддерживается ли нативный протокол Anthropic, как сопоставляются имена моделей, прозрачны ли политики лимитов и журналирования.
9. Частые вопросы
Claude API и подписка на веб-версию Claude — это одно и то же?
Нет. Веб-версия — продукт по подписке для пользователей, API тарифицируется по расходу. У них разные системы аккаунтов, квоты и точки управления. Ключи, счета и расход API ведутся в Anthropic Console.
Можно ли увидеть полное значение ключа после создания?
Обычно оно показывается только один раз. Дальше видны лишь префикс или имя, поэтому сразу сохраните ключ в менеджере секретов. Если ключ потерян, отзовите старый и создайте новый.
Почему max_tokens обязателен?
Messages API требует явно указать лимит одного ответа, чтобы контролировать длину генерации и ресурсы. Без него вернётся 400. Ставьте разумное значение под задачу, а не максимум вслепую.
429 — это закончилась квота или слишком высокий параллелизм?
Возможно и то, и другое. Сначала посмотрите тело ответа и retry-after: кратковременные всплески чаще связаны со скоростью или параллелизмом; постоянные ошибки при странном расходе — с тарифом и квотой. Помогают задержка с повтором, снижение параллелизма и разделение ключей.
Обязательно ли команде из Китая использовать шлюз?
Нет. Если прямой доступ стабилен, оплата и оценка соответствия решаются, официальное подключение проще. Шлюз стоит рассматривать, когда нужны расчёты в юанях, счёт-фактуры, единый вход к нескольким моделям или оптимизация сети; при этом проверьте политику данных и обработки сбоев.
Что дальше
Сначала зарегистрируйтесь в ZSQH AI Gateway, пройдите минимальный запрос к /v1/messages тестовым ключом, а затем подключайте бизнес-логику. Модели, контекст и биллинг смотрите на странице тарифов.
Читайте также:
