---
title: Миграция с fal.ai
description: Перенос интеграции с fal.ai на Clipia API — соответствие эндпоинтов, заголовков, статусов и вебхуков, а также ключевые различия.
---

Clipia API совместим по форме с очередью fal.ai: тот же поток `submit → status → result` плюс вебхуки, те же поля `request_id`, `status_url`, `response_url` и те же значения статусов. Чтобы перейти, в большинстве случаев достаточно сменить базовый URL и ключ. Главные различия: тарификация в **кредитах** (не в USD), отсутствие отмены и собственная HMAC-подпись вебхуков.

## Соответствие эндпоинтов и понятий

| fal.ai | Clipia |
|--------|--------|
| `Authorization: Key $FAL_KEY` | `Authorization: Bearer clipia_live_…` (или `Key …`) |
| `POST queue.fal.run/{model}` | `POST https://api.clipia.ai/v1/models/{model}` |
| `request_id`, `status_url`, `response_url` | те же поля (но **без** `cancel_url`) |
| `IN_QUEUE` / `IN_PROGRESS` / `COMPLETED` | те же значения |
| `?fal_webhook=` / `webhook_url` | `webhook_url` в теле запроса |
| вебхук `{ request_id, status, payload }` | тот же формат |

Базовый URL — `https://api.clipia.ai`, версия `v1`. Заголовок авторизации совместим со схемой `Key`, поэтому существующий код, использующий `Authorization: Key …`, продолжит работать; рекомендуемая схема для нового кода — `Authorization: Bearer …`.

## Что меняется в коде

1. **Базовый URL:** `queue.fal.run/{model}` → `https://api.clipia.ai/v1/models/{model}`.
2. **Ключ:** `$FAL_KEY` → `clipia_live_…` (или `clipia_test_…` для песочницы).
3. **Вебхук:** вместо query-параметра `?fal_webhook=` передавайте `webhook_url` в теле запроса.

```bash
# Было (fal.ai)
curl -X POST "https://queue.fal.run/{model}?fal_webhook=https://you/wh" \
  -H "Authorization: Key $FAL_KEY" \
  -d '{ "prompt": "..." }'

# Стало (Clipia)
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer clipia_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "prompt": "..." }, "webhook_url": "https://you/wh" }'
```

## Ключевые различия

| Аспект | fal.ai | Clipia |
|--------|--------|--------|
| Тарификация | USD | фиксированная цена в **кредитах** (поле `cost`) |
| Нехватка средств | `403` | `402 insufficient_credits` |
| Отмена | `cancel_url` | отмены нет (см. ниже) |
| Подпись вебхука | формат fal | HMAC-SHA256, заголовок `X-Clipia-Signature` |

<Callout type="warn" title="Отмены нет">
В публичном Clipia API нет cancel-эндпоинта и поля `cancel_url`. Генерация резервирует кредиты при старте и не прерывается. Статус `CANCELED` всё же может прийти, если генерацию отменили вне публичного API (из веб-кабинета) — обрабатывайте его как терминальный.
</Callout>

<Callout type="info" title="Проверьте обработчик вебхуков">
Подпись вебхуков в Clipia — HMAC-SHA256 в заголовке `X-Clipia-Signature` (`t=…,v1=…`), с проверкой свежести по `X-Clipia-Timestamp`. Обновите верификацию подписи под этот формат и протестируйте её на тестовом ключе `clipia_test_…` — в песочнице вебхуки приходят тем же подписанным механизмом, что и в бою.
</Callout>