API-ключи: как использовать

Для любого запроса к API нужен ключ формата sk-aiagg-.... Он создаётся в разделе API-ключи личного кабинета и передаётся в заголовке Authorization: Bearer <ключ>. Один ключ открывает все эндпоинты: текст, картинки, видео, озвучка. Показывается ключ ровно один раз — дальше в базе хранится только его sha256-хеш. Неверный или отозванный ключ вернёт 401 с кодом invalid_api_key.

Как выглядит ключ и где его взять?

Ключ начинается с префикса sk-aiagg-, дальше — случайная строка. Создание занимает минуту: раздел API-ключи → «Создать ключ» → скопировать значение из окна подтверждения. Восстановить ключ позже нельзя (мы не храним оригинал), но можно создать новый.

Ключей может быть несколько — по одному на приложение или окружение. Так проще и отзывать доступ точечно, и смотреть расход: статистика в кабинете считается по каждому ключу отдельно.

Все ключи аккаунта тратят один общий баланс в рублях, отдельных лимитов на ключ нет.

Как передавать ключ в запросе?

Только через HTTP-заголовок Authorization со схемой Bearer. В query-строке и в теле запроса ключ не принимается. OpenAI SDK ставит заголовок сам — ключ отдаётся параметром api_key.

GET /v1/models — удобный «пинг» для проверки связки ключ + base_url: он бесплатный и не трогает баланс. Полное описание ответа — в референсе /v1/models.

Что придёт, если ключ неверный?

401 в OpenAI-формате ошибки:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Тот же ответ приходит для отозванного ключа и для запроса вообще без заголовка Authorization. Все коды ошибок собраны в гайде «Ошибки API».

Как хранить ключ безопасно?

• Держите ключ в переменной окружения или секрет-хранилище, не в коде.
• Не коммитьте в git, не вставляйте в URL, не пишите в логи.
• Для фронтенда ключ не подходит в принципе: запросы к API должны идти через ваш бэкенд.

Что дальше?

Первый запрос по шагам — в Quick start. Дальше — гайды по модальностям: текст, изображения, видео, озвучка.