---
title: Переход с другого API генерации
description: Как перенести интеграцию с другого API генерации на Clipia — схема submit, status, result, ключи, вебхуки, кредиты и чек-лист перед запуском.
icon: ArrowRightLeft
---

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

## Как устроена очередь Clipia [#flow]

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

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

Вместо опроса можно передать `webhook_url` — Clipia пришлёт `POST`, когда задача завершится. Подробнее — в разделе [«Обзор API»](/ru/docs/api-reference/overview).

## Что поменять в коде [#changes]

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

```bash
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` в [каталоге](/ru/docs/api-reference/models): `GET /v1/models/{model}` возвращает её целиком.

## Ключ [#key]

Ключ создаётся в [консоли разработчика](/ru/developer) и показывается один раз. Ключи с префиксом `clipia_live_` работают в бою, с префиксом `clipia_test_` — в песочнице: она возвращает заготовленный результат без списания кредитов. Храните ключ в переменной окружения `CLIPIA_KEY` и не передавайте его в браузер. Подробнее — в разделе [«Аутентификация»](/ru/docs/getting-started/authentication).

## Вебхуки [#webhooks]

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

Обработчик, написанный под другой формат подписи, нужно переписать. Проверьте его на ключе `clipia_test_`: в песочнице вебхуки подписываются так же, как в бою. Подробнее — в разделе [«Вебхуки»](/ru/docs/api-reference/webhooks).

## Чем Clipia может отличаться [#differences]

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

<Callout type="info" title="Цены">
Цены актуальны на октябрь 2026 года. Точная стоимость всегда видна на кнопке запуска до списания.
</Callout>

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

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

Готовые клиенты для очереди — [TypeScript SDK](/ru/docs/sdk/typescript) и [Python SDK](/ru/docs/sdk/python). Общие советы по надёжности — в разделе [«Рекомендации»](/ru/docs/guides/best-practices).