Аутентификация и API-ключи
Создайте ключ в личном кабинете. Для запроса используйте один из двух заголовков.
Вариант 1
Authorization: Bearer YOUR_API_KEYВариант 2
x-api-key: YOUR_API_KEYВ inference заголовок Authorization с префиксом Bearer имеет приоритет, если переданы оба. Отправляйте только один вариант, чтобы исключить конфликт ключей.
Причины отказа
При проверке аутентификации отсутствие ключа даёт 401. Проверка тела может завершиться раньше проверки ключа: например, отсутствие обязательного model даёт 422.
| HTTP | Тело ответа | Причина |
|---|---|---|
| 401 | {"detail":"missing_api_key"} | Ключ не передан. |
| 401 | {"detail":"invalid_api_key"} | Некорректный формат ключа. |
| 401 | {"detail":"unauthorized"} | Ключ корректного формата не найден, отозван или не разрешён для IP. |
| 401 | {"detail":"key_expired"} | Истёк срок действия ключа. |
| 401 | {"detail":"key_suspended"} | Ключ приостановлен. |
Не-ASCII символы в заголовке ключа могут дать другой ответ: 401 с кодом INVALID_API_KEY в оболочке шлюза. Регистр кода имеет значение.
Пример структуры; request_id условный
{"error":{"code":"INVALID_API_KEY","message":"invalid_api_key","request_id":"example-request-id"}}Лимит расходов ключа
Превышение лимита расходов ключа возвращает 429 spend_limit_exceeded. Это отличается от ограничения частоты запросов. Проверьте настройки ключа и расход.
В ответе лимита расходов используется объект detail с полем error: "spend_limit_exceeded". Недостаточный баланс аккаунта возвращает 402 insufficient_balance.
Храните ключ на сервере
- Передавайте ключ из переменной окружения или хранилища секретов.
- Не помещайте ключ в браузерный код, публичный репозиторий или сообщения поддержки.
- При утечке отзовите ключ в кабинете и замените его в приложении.
Частые вопросы
Можно ли определить, что ключ истёк?
При проверке истёкшего ключа предусмотрен отдельный код key_expired. Успешная проверка может кешироваться, поэтому изменение состояния ключа не обязательно проявится сразу.
Почему пополнение не устраняет 429?
spend_limit_exceeded относится к лимиту ключа. Баланс аккаунта и этот лимит проверяются отдельно.
Что отправить в поддержку?
Сохраните HTTP-статус, код ошибки и X-Request-Id, если он есть. Не отправляйте сам ключ. См. форматы ошибок.
Обновлено