Миграция с fal.ai
Перенос интеграции с 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 ….
Что меняется в коде
- Базовый URL:
queue.fal.run/{model}→https://api.clipia.ai/v1/models/{model}. - Ключ:
$FAL_KEY→clipia_live_…(илиclipia_test_…для песочницы). - Вебхук: вместо query-параметра
?fal_webhook=передавайтеwebhook_urlв теле запроса.
# Было (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 |
Отмены нет
В публичном Clipia API нет cancel-эндпоинта и поля cancel_url. Генерация резервирует кредиты при старте и не прерывается. Статус CANCELED всё же может прийти, если генерацию отменили вне публичного API (из веб-кабинета) — обрабатывайте его как терминальный.
Проверьте обработчик вебхуков
Подпись вебхуков в Clipia — HMAC-SHA256 в заголовке X-Clipia-Signature (t=…,v1=…), с проверкой свежести по X-Clipia-Timestamp. Обновите верификацию подписи под этот формат и протестируйте её на тестовом ключе clipia_test_… — в песочнице вебхуки приходят тем же подписанным механизмом, что и в бою.
Рекомендации
Практики для надёжной интеграции с Clipia API — идемпотентность на ретраях, вебхуки вместо опроса, обработка ошибок и 429 с backoff, оценка стоимости и хранение request_id.
Changelog
История изменений публичного API Clipia v1, MCP-сервера и SDK — запуск, обновления контракта и новые возможности.