---
title: Аутентификация
description: Как авторизовать запросы к Clipia API — API-ключи, три схемы заголовка, боевые и тестовые ключи, scopes и безопасное хранение.
---

Все запросы к `/v1/*` авторизуются API-ключом, который вы передаёте в заголовке. Рекомендуемая схема — `Authorization: Bearer clipia_live_…`; поддерживаются также `Authorization: Key …` и `X-Api-Key: …`. Ключ создаётся в личном кабинете, показывается один раз, привязан к вашему аккаунту и списывает кредиты с его баланса.

## Схемы заголовка

Поддерживаются три равнозначные формы — выберите одну.

<Tabs items={['Bearer', 'Key', 'X-Api-Key']}>
<Tab value="Bearer">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Key $CLIPIA_KEY"
```

</Tab>
<Tab value="X-Api-Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "X-Api-Key: $CLIPIA_KEY"
```

</Tab>
</Tabs>

| Схема | Заголовок | Примечание |
|-------|-----------|------------|
| Bearer | `Authorization: Bearer …` | рекомендуется, стандарт OAuth-style |
| Key | `Authorization: Key …` | совместимость с очередями вида fal.ai |
| X-Api-Key | `X-Api-Key: …` | если вам удобнее отдельный заголовок |

## Боевые и тестовые ключи

Префикс ключа определяет среду.

| Префикс | Среда | Поведение |
|---------|-------|-----------|
| `clipia_live_…` | боевая | реальная генерация, кредиты списываются |
| `clipia_test_…` | песочница | mock-результат мгновенно, кредиты не списываются |

Боевой и тестовый ключи независимы. Чтобы перейти с песочницы на боевой режим, просто замените ключ — код менять не нужно. Подробнее — на странице «Тестовый режим».

## Получение и хранение ключа

Ключ создаётся в личном кабинете: **Консоль разработчика** (`/developer`) → вкладка **API-ключи**. Полный ключ показывается **один раз**.

<Callout type="warn" title="Ключ — это серверный секрет">
Не размещайте ключ в браузере, мобильных приложениях, фронтенд-бандлах или публичных репозиториях. Храните его в секрет-менеджере или переменных окружения сервера. Если ключ скомпрометирован — отзовите его в кабинете (отзыв моментальный) и создайте новый.
</Callout>

## Scopes (области доступа)

У каждого ключа есть scope-ограничения. Допустимые значения — `generate`, `read` и `chat`; по умолчанию ключ получает `["generate", "read"]`.

| Scope | Что разрешает |
|-------|---------------|
| `generate` | создание генерации фото/видео (`POST /v1/models/{model}`) |
| `chat` | LLM-чат — AI Gateway (`POST /v1/chat/completions`) |
| `read` | резерв на будущее (read-only ключи) |

<Callout type="info" title="Один ключ — и генерация, и LLM">
Отдельный ключ для [AI Gateway](/docs/llm-gateway) не нужен. Scope `generate` автоматически разрешает и `chat`, поэтому **любой ваш ключ генерации (дефолтный `["generate", "read"]`) сразу работает и для LLM-чата `POST /v1/chat/completions`, и для генерации фото/видео — с одного баланса кредитов**. Отдельный scope `chat` нужен лишь когда вы намеренно выпускаете ключ **только** под LLM (без права на генерацию).
</Callout>

- **Создание генераций** требует scope `generate`.
- **LLM-чат** (`POST /v1/chat/completions`) требует scope `chat` — его удовлетворяет и `generate` (см. выше), поэтому существующие ключи работают без перевыпуска.
- **Чтение статуса/результата** своей генерации доступно любому валидному ключу — scope не требуется.
- Каталог моделей (`GET /v1/models`) и баланс (`GET /v1/account`) — без scope.
- Запрос без нужного scope → `403 insufficient_scope`.

<Callout type="error" title="Невалидный ключ">
Отсутствующий, неверный или отозванный ключ → `401 invalid_api_key`. Проверьте префикс среды и то, что ключ передан в одном из трёх поддерживаемых заголовков.
</Callout>