ключ api — единственный способ авторизации в шлюзе. одного ключа достаточно для всего текстового каталога: отдельные ключи для разных моделей не нужны.
создание ключа
ключи создаются в кабинете кнопкой «создать ключ». ключу можно задать имя — оно видно только в кабинете и помогает различать приложения.
готовый ключ выглядит как строка, начинающаяся с sk-.
увидеть ключ целиком можно только один раз, сразу после создания. в списке он показан частично, поэтому сохраните его сразу.
ключ не стоит хранить в коде приложения и тем более публиковать в открытых репозиториях. если ключ утёк — аннулируйте его и создайте новый.
основной способ
заголовок Authorization — работает на всех эндпоинтах и с любым клиентом. если пишете запросы сами, используйте его.
Authorization: Bearer <КЛЮЧ>дополнительные способы
существуют только для того, чтобы официальные библиотеки anthropic и google работали без правок: они передают ключ иначе и не умеют пользоваться заголовком Authorization. самостоятельно выбирать эти способы незачем.
| способ | как выглядит | для кого |
|---|---|---|
заголовок X-API-Key | X-API-Key: <КЛЮЧ> | клиенты anthropic |
заголовок x-goog-api-key | x-goog-api-key: <КЛЮЧ> | клиенты google |
параметр строки запроса key | ?key=<КЛЮЧ> | клиенты google |
достаточно одного способа. если ключ передан сразу несколькими, применяется заголовок Authorization.
ограничения ключа
ключ можно настроить в кабинете, открыв его на редактирование.
доступные модели. список моделей, разрешённых для этого ключа. если не выбрано ничего, доступны все текстовые модели каталога. запрос к модели вне списка вернёт ошибку.
бюджет. максимальная сумма, которую можно потратить по этому ключу. бюджет бывает одноразовым или ежемесячным — во втором случае расход обнуляется в начале каждого месяца. чтобы снять ограничение, поставьте сумму 0.
ежемесячный бюджет сравнивается с расходом всего аккаунта за календарный месяц, а не только с расходом этого ключа.
потребление по ключу начинает считаться только после того, как бюджет установлен.
белый список ip. ограничивает адреса, с которых принимаются запросы по ключу. поддерживаются ipv4-адреса и подсети в формате cidr, ipv6 — нет. ключ без списка принимает запросы с любого адреса. сами списки создаются на той же странице и привязываются к нескольким ключам сразу.
разрешения. открывают доступ к отдельным служебным методам — например, к запросу баланса.
аннулирование
ненужный или скомпрометированный ключ аннулируется в списке ключей. действие необратимо: запросы с этим ключом перестанут выполняться, а восстановить его нельзя — вместо этого создаётся новый.
ошибки доступа
| код | сообщение | причина |
|---|---|---|
| 401 | Invalid API Key | ключ не передан или не существует |
| 401 | User is banned | аккаунт заблокирован |
| 402 | Insufficient balance to run this request. | на балансе недостаточно средств |
| 402 | API Key budget exceeded. | исчерпан бюджет ключа |
| 402 | Monthly budget exceeded. | исчерпан ежемесячный бюджет |
| 403 | IP address not allowed | адрес не входит в белый список ключа |
| 403 | Model not allowed | модель не входит в список доступных для ключа |
| 429 | Too many requests | превышен лимит частоты запросов |
у ответа 429 несколько причин с одинаковым текстом: лимит запросов на эндпоинт, защита от подбора ключей, слишком много ошибочных запросов подряд и ограничение со стороны вендора. разбор — в статье лимиты.
что дальше
- модели — как устроены идентификаторы.
- быстрый старт — первый запрос с готовыми примерами.
частые вопросы
можно ли посмотреть ключ ещё раз?
нет. полностью ключ показывается только один раз, сразу после создания. в списке ключей он отображается частично. если ключ утерян, аннулируйте его и создайте новый.
сколько ключей можно создать?
по умолчанию — до 10. если нужно больше, напишите в поддержку, лимит поднимут. удобно завести отдельный ключ на каждое приложение или окружение: так можно ограничить каждый своим бюджетом и набором моделей, а при утечке аннулировать только один.