---
title: Migrating from fal.ai
description: 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

1. **Base URL:** `queue.fal.run/{model}` → `https://api.clipia.ai/v1/models/{model}`.
2. **Key:** `$FAL_KEY` → `clipia_live_…` (or `clipia_test_…` for the sandbox).
3. **Webhook:** instead of the `?fal_webhook=` query parameter, pass `webhook_url` in the request body.

```bash
# 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 |

<Callout type="warn" title="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.
</Callout>

<Callout type="info" title="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.
</Callout>