Начало работы
Аутентификация
Как авторизовать запросы к Clipia API — API-ключ, три формы заголовка, боевые и тестовые ключи, права доступа и безопасное хранение ключа.
Все запросы к /v1/* авторизуются API-ключом. Ключ создаётся в консоли разработчика, показывается один раз, привязан к вашему аккаунту и списывает кредиты с его баланса. Рекомендуемый заголовок — Authorization: Bearer clipia_live_….
Формы заголовка
Ключ можно передать одним из трёх способов. Сервер принимает любой, выберите удобный.
curl https://api.clipia.ai/v1/account \
-H "Authorization: Bearer $CLIPIA_KEY"| Форма | Заголовок | Примечание |
|---|---|---|
| Bearer | Authorization: Bearer … | рекомендуется; принимает только ключи с префиксом clipia_ |
| Key | Authorization: Key … | альтернативная схема, слово Key можно писать в любом регистре |
| X-Api-Key | X-Api-Key: … | если удобнее отдельный заголовок |
Боевые и тестовые ключи
Префикс ключа определяет среду. Среду вы выбираете при создании ключа.
| Префикс | Среда | Поведение |
|---|---|---|
clipia_live_… | боевая | реальная генерация, кредиты списываются |
clipia_test_… | песочница | готовый образец сразу, стоимость считается, но не списывается |
Чтобы перейти из песочницы в боевой режим, замените ключ — код менять не нужно. Подробнее — на странице «Тестовый режим».
Боевому ключу нужна активная подписка
Генерация через API на ключе clipia_live_ доступна, пока у аккаунта активна подписка. Без неё запрос вернёт 402 с кодом subscription_required: покупка пакета кредитов доступ не открывает. Тестовые ключи clipia_test_ работают без оплаты.
Как получить ключ
- Откройте консоль разработчика, вкладка API-ключи.
- Нажмите Создать ключ, задайте имя (до 100 символов) и выберите среду: боевую или тестовую.
- Скопируйте ключ и секрет для подписи вебхуков. Оба показываются один раз.
На одном аккаунте может быть до 20 активных ключей. Если лимит исчерпан, создание вернёт 400 с сообщением api_key_limit_reached — отзовите ненужный ключ и создайте новый.
Ключ — серверный секрет
Не размещайте ключ в браузере, мобильном приложении, фронтенд-бандле или публичном репозитории. Храните его в секрет-менеджере или переменных окружения сервера. Если ключ скомпрометирован, отзовите его в консоли и создайте новый.
Пароль аккаунта и ключи. Смена пароля в настройках аккаунта API-ключи не затрагивает, а OAuth-подключения MCP перестают работать до вашего следующего входа в аккаунт Clipia. Сброс пароля по ссылке из письма «Забыли пароль» отзывает все активные ключи и OAuth-подключения: это сценарий восстановления доступа, после него создайте ключи заново и переподключите MCP-клиенты. Если подозреваете утечку ключа, не ждите смены пароля — отзовите ключ в консоли.
Права ключа
Каждый ключ создаётся с правами generate и read. Выбирать права при создании не нужно.
| Право | Что разрешает |
|---|---|
generate | создание генераций (POST /v1/models/{model}) и LLM-чат AI Gateway (POST /v1/chat/completions) |
read | зарезервировано, сейчас ничего дополнительно не открывает |
- Отдельный ключ для LLM не нужен: право
generateвключает чат. Генерация медиа и LLM списывают кредиты с одного баланса. - Статус и результат своей генерации может читать любой действующий ключ.
- Каталог моделей (
GET /v1/models), оценка стоимости и баланс (GET /v1/account) доступны без дополнительных прав. - Запрос без нужного права вернёт
403 insufficient_scope.
Ключ не принят
Если ключа нет, он неверный или отозван, сервер ответит 401 invalid_api_key. Проверьте префикс среды и то, что ключ передан в одном из трёх заголовков. Схема Bearer принимает только ключи, которые начинаются с clipia_.
Быстрый старт
Первая генерация изображения через Clipia API за четыре шага — от создания ключа до готового результата, с примерами на cURL, TypeScript и Python.
Тестовый режим
Песочница Clipia API — ключ clipia_test_ проходит весь цикл submit, status, result и вебхук без списания кредитов и возвращает готовый образец.