Аутентификация
Как авторизовать запросы к Clipia API — API-ключи, три схемы заголовка, боевые и тестовые ключи, scopes и безопасное хранение.
Все запросы к /v1/* авторизуются API-ключом, который вы передаёте в заголовке. Рекомендуемая схема — Authorization: Bearer clipia_live_…; поддерживаются также Authorization: Key … и X-Api-Key: …. Ключ создаётся в личном кабинете, показывается один раз, привязан к вашему аккаунту и списывает кредиты с его баланса.
Схемы заголовка
Поддерживаются три равнозначные формы — выберите одну.
curl https://api.clipia.ai/v1/account \
-H "Authorization: Bearer $CLIPIA_KEY"curl https://api.clipia.ai/v1/account \
-H "Authorization: Key $CLIPIA_KEY"curl https://api.clipia.ai/v1/account \
-H "X-Api-Key: $CLIPIA_KEY"| Схема | Заголовок | Примечание |
|---|---|---|
| Bearer | Authorization: Bearer … | рекомендуется, стандарт OAuth-style |
| Key | Authorization: Key … | совместимость с очередями вида fal.ai |
| X-Api-Key | X-Api-Key: … | если вам удобнее отдельный заголовок |
Боевые и тестовые ключи
Префикс ключа определяет среду.
| Префикс | Среда | Поведение |
|---|---|---|
clipia_live_… | боевая | реальная генерация, кредиты списываются |
clipia_test_… | песочница | mock-результат мгновенно, кредиты не списываются |
Боевой и тестовый ключи независимы. Чтобы перейти с песочницы на боевой режим, просто замените ключ — код менять не нужно. Подробнее — на странице «Тестовый режим».
Получение и хранение ключа
Ключ создаётся в личном кабинете: Консоль разработчика (/developer) → вкладка API-ключи. Полный ключ показывается один раз.
Ключ — это серверный секрет
Не размещайте ключ в браузере, мобильных приложениях, фронтенд-бандлах или публичных репозиториях. Храните его в секрет-менеджере или переменных окружения сервера. Если ключ скомпрометирован — отзовите его в кабинете (отзыв моментальный) и создайте новый.
Scopes (области доступа)
У каждого ключа есть scope-ограничения. Допустимые значения — generate, read и chat; по умолчанию ключ получает ["generate", "read"].
| Scope | Что разрешает |
|---|---|
generate | создание генерации фото/видео (POST /v1/models/{model}) |
chat | LLM-чат — AI Gateway (POST /v1/chat/completions) |
read | резерв на будущее (read-only ключи) |
Один ключ — и генерация, и LLM
Отдельный ключ для AI Gateway не нужен. Scope generate автоматически разрешает и chat, поэтому любой ваш ключ генерации (дефолтный ["generate", "read"]) сразу работает и для LLM-чата POST /v1/chat/completions, и для генерации фото/видео — с одного баланса кредитов. Отдельный scope chat нужен лишь когда вы намеренно выпускаете ключ только под LLM (без права на генерацию).
- Создание генераций требует scope
generate. - LLM-чат (
POST /v1/chat/completions) требует scopechat— его удовлетворяет иgenerate(см. выше), поэтому существующие ключи работают без перевыпуска. - Чтение статуса/результата своей генерации доступно любому валидному ключу — scope не требуется.
- Каталог моделей (
GET /v1/models) и баланс (GET /v1/account) — без scope. - Запрос без нужного scope →
403 insufficient_scope.
Невалидный ключ
Отсутствующий, неверный или отозванный ключ → 401 invalid_api_key. Проверьте префикс среды и то, что ключ передан в одном из трёх поддерживаемых заголовков.