Migrating from fal.ai
Move a fal.ai integration to the Clipia API — mapping for endpoints, headers, statuses, and webhooks, plus the key differences.
The Clipia API is shape-compatible with the fal.ai queue: the same submit → status → result flow plus webhooks, the same request_id, status_url, and response_url fields, and the same status values. In most cases, migrating means swapping the base URL and the key. The main differences: pricing in credits (not USD), no cancellation, and Clipia's own HMAC webhook signature.
Endpoint and concept mapping
| fal.ai | Clipia |
|---|---|
Authorization: Key $FAL_KEY | Authorization: Bearer clipia_live_… (or Key …) |
POST queue.fal.run/{model} | POST https://api.clipia.ai/v1/models/{model} |
request_id, status_url, response_url | same fields (but no cancel_url) |
IN_QUEUE / IN_PROGRESS / COMPLETED | same values |
?fal_webhook= / webhook_url | webhook_url in the request body |
webhook { request_id, status, payload } | same format |
The base URL is https://api.clipia.ai, version v1. The auth header is compatible with the Key scheme, so existing code using Authorization: Key … keeps working; the recommended scheme for new code is Authorization: Bearer ….
What changes in code
- Base URL:
queue.fal.run/{model}→https://api.clipia.ai/v1/models/{model}. - Key:
$FAL_KEY→clipia_live_…(orclipia_test_…for the sandbox). - Webhook: instead of the
?fal_webhook=query parameter, passwebhook_urlin the request body.
# Before (fal.ai)
curl -X POST "https://queue.fal.run/{model}?fal_webhook=https://you/wh" \
-H "Authorization: Key $FAL_KEY" \
-d '{ "prompt": "..." }'
# After (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" }'Key differences
| Aspect | fal.ai | Clipia |
|---|---|---|
| Pricing | USD | fixed price in credits (cost field) |
| Insufficient funds | 403 | 402 insufficient_credits |
| Cancellation | cancel_url | none (see below) |
| Webhook signature | fal format | HMAC-SHA256, X-Clipia-Signature header |
No cancellation
The public Clipia API has no cancel endpoint and no cancel_url. A generation reserves credits when it starts and cannot be interrupted. The CANCELED status can still arrive if a generation is canceled outside the public API (from the web dashboard) — treat it as terminal.
Check your webhook handler
Clipia signs webhooks with HMAC-SHA256 in the X-Clipia-Signature header (t=…,v1=…), with freshness checked against X-Clipia-Timestamp. Update your signature verification to this format and test it with a clipia_test_… key — in the sandbox, webhooks are delivered through the same signed mechanism as production.
Best practices
Practices for a reliable Clipia API integration — idempotent retries, webhooks over polling, error and 429 handling with backoff, cost estimation, and storing request_id.
Changelog
Change history for the Clipia public API v1, the MCP server and the SDKs — launch, contract updates and new capabilities.