Переход с другого API генерации

Если ваш сервис уже работает с другим API генерации изображений, видео или аудио по схеме очереди, перенос на Clipia обычно сводится к смене адреса, ключа и формата нескольких полей. Ниже — как устроена очередь Clipia, что проверить в коде и чем Clipia может отличаться от привычной вам схемы.

Как устроена очередь Clipia

Генерация в Clipia асинхронная и проходит три шага:

POST https://api.clipia.ai/v1/models/{model} — отправка задачи. В ответе request_id, status_url, response_url и зарезервированная сумма cost в кредитах.
GET /v1/requests/{request_id}/status — статус: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED или CANCELED.
GET /v1/requests/{request_id} — результат со ссылками на готовые медиа.

Вместо опроса можно передать webhook_url — Clipia пришлёт POST, когда задача завершится. Подробнее — в разделе «Обзор API».

Что поменять в коде

Что	В Clipia
Базовый URL	`https://api.clipia.ai`, версия `v1`
Адрес отправки	`POST /v1/models/{model}`, где `{model}` — slug из каталога
Авторизация	`Authorization: Bearer <ключ>`; также принимаются `Authorization: Key <ключ>` и `X-Api-Key`
Параметры модели	внутри объекта `input` в теле запроса
Вебхук	поле `webhook_url` в теле запроса, только `https://`
Повторы	заголовок `Idempotency-Key`, ключ действует 24 часа
Стоимость	в кредитах: поле `cost` и эндпоинт `estimate`

curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
  -d '{ "input": { "prompt": "a sunset over mountains" }, "webhook_url": "https://example.com/clipia-webhook" }'

Названия моделей и их параметры у разных API отличаются. Сверьте каждую модель со схемой input в каталоге: GET /v1/models/{model} возвращает её целиком.

Ключ

Ключ создаётся в консоли разработчика и показывается один раз. Ключи с префиксом clipia_live_ работают в бою, с префиксом clipia_test_ — в песочнице: она возвращает заготовленный результат без списания кредитов. Храните ключ в переменной окружения CLIPIA_KEY и не передавайте его в браузер. Подробнее — в разделе «Аутентификация».

Вебхуки

Тело вебхука содержит request_id, status (OK или ERROR) и payload с моделью, ссылками на результат и списанной суммой либо error с кодом и сообщением. Подпись — HMAC-SHA256 в заголовке X-Clipia-Signature вида t=<timestamp>,v1=<hex>, время отправки — в X-Clipia-Timestamp. Секрет вебхуков свой у каждого API-ключа и показывается один раз.

Обработчик, написанный под другой формат подписи, нужно переписать. Проверьте его на ключе clipia_test_: в песочнице вебхуки подписываются так же, как в бою. Подробнее — в разделе «Вебхуки».

Чем Clipia может отличаться

Оплата в кредитах. Стоимость считается в кредитах, а не в валюте. Узнать цену до запуска можно через POST /v1/models/{model}/estimate. При ошибке генерации кредиты возвращаются.
Нехватка кредитов — 402. Код insufficient_credits; если ваш код ждал другой статус, поправьте ветку обработки.
Отмены нет. В публичном API нет эндпоинта отмены. Статус CANCELED всё же может прийти, если задачу отменили вне API, например службой поддержки, — обрабатывайте его как финальный.
Единый формат ошибок. Объект error с полями type, code и message — см. «Ошибки».
Лимиты. 120 запросов в минуту на ключ и 600 на все ключи аккаунта, заголовки RateLimit-* — см. «Лимиты».

Цены

Цены актуальны на октябрь 2026 года. Точная стоимость всегда видна на кнопке запуска до списания.

Чек-лист перед запуском

Для каждой модели найден slug в каталоге и сверена схема input.
Ключ хранится в CLIPIA_KEY на сервере, интеграция проверена на ключе clipia_test_.
Каждая отправка идёт с собственным Idempotency-Key.
Обработчик вебхуков проверяет X-Clipia-Signature и дедуплицирует доставки по request_id.
Обработаны статусы FAILED и CANCELED и коды 402 и 429.

Готовые клиенты для очереди — TypeScript SDK и Python SDK. Общие советы по надёжности — в разделе «Рекомендации».