---
title: Migrating from another generation API
description: Move an integration from another generation API to Clipia — the submit, status, result flow, keys, webhooks, credits and a pre-launch checklist.
icon: ArrowRightLeft
---

If your service already uses another image, video or audio generation API built around a queue, moving to Clipia usually means changing the URL, the key and the shape of a few fields. This page explains how the Clipia queue works, what to check in your code, and where Clipia may differ from what you're used to.

## How the Clipia queue works [#flow]

Generation in Clipia is asynchronous and takes three steps:

1. `POST https://api.clipia.ai/v1/models/{model}` — submit a job. The response includes `request_id`, `status_url`, `response_url` and `cost`, the amount reserved in credits.
2. `GET /v1/requests/{request_id}/status` — the status: `IN_QUEUE`, `IN_PROGRESS`, `COMPLETED`, `FAILED` or `CANCELED`.
3. `GET /v1/requests/{request_id}` — the result with links to the finished media.

Instead of polling, you can pass a `webhook_url`, and Clipia sends a `POST` when the job finishes. See [API overview](/en/docs/api-reference/overview).

## What to change in your code [#changes]

| What | In Clipia |
| --- | --- |
| Base URL | `https://api.clipia.ai`, version `v1` |
| Submit endpoint | `POST /v1/models/{model}`, where `{model}` is a slug from the [catalog](/en/docs/api-reference/models) |
| Authorization | `Authorization: Bearer <key>`; `Authorization: Key <key>` and `X-Api-Key` also work |
| Model parameters | inside the `input` object of the request body |
| Webhook | the `webhook_url` field in the request body, `https://` only |
| Retries | the `Idempotency-Key` header, valid for 24 hours |
| Cost | in credits: the `cost` field and the `estimate` endpoint |

```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" }'
```

Model names and parameters differ between APIs. Check each model against its `input` schema in the [catalog](/en/docs/api-reference/models): `GET /v1/models/{model}` returns the full schema.

## Key [#key]

Create a key in the [developer console](/en/developer); it's shown only once. Keys prefixed `clipia_live_` work in production, keys prefixed `clipia_test_` work in the sandbox, which returns a canned result with no credits charged. Keep the key in the `CLIPIA_KEY` environment variable and never send it to the browser. See [Authentication](/en/docs/getting-started/authentication).

## Webhooks [#webhooks]

A webhook body contains `request_id`, `status` (`OK` or `ERROR`) and either a `payload` with the model, result links and the amount charged, or an `error` with a code and message. The signature is HMAC-SHA256 in the `X-Clipia-Signature` header, formatted as `t=<timestamp>,v1=<hex>`; the send time is in `X-Clipia-Timestamp`. Each API key has its own webhook secret, shown only once.

A handler written for a different signature format has to be rewritten. Test it with a `clipia_test_` key: in the sandbox, webhooks are signed the same way as in production. See [Webhooks](/en/docs/api-reference/webhooks).

## Where Clipia may differ [#differences]

- **Credits.** Costs are in credits, not currency. To get the price before running, call `POST /v1/models/{model}/estimate`. If a generation fails, the credits are returned.
- **Insufficient credits is `402`.** The code is `insufficient_credits`; if your code expected a different status, update that branch.
- **No cancellation.** The public API has no cancel endpoint. You can still receive `CANCELED` if a job was canceled outside the API, for example by support — treat it as final.
- **One error format.** An `error` object with `type`, `code` and `message` — see [Errors](/en/docs/api-reference/errors).
- **Limits.** 120 requests per minute per key and 600 across all keys of an account, with `RateLimit-*` headers — see [Rate limits](/en/docs/api-reference/rate-limits).

<Callout type="info" title="Pricing">
Prices are current as of October 2026. The exact cost is always shown on the run button before anything is charged.
</Callout>

## Pre-launch checklist [#checklist]

1. Every model has a slug from the catalog and its `input` schema is checked.
2. The key lives in `CLIPIA_KEY` on the server, and the integration is tested with a `clipia_test_` key.
3. Every submission sends its own `Idempotency-Key`.
4. The webhook handler verifies `X-Clipia-Signature` and deduplicates deliveries by `request_id`.
5. `FAILED` and `CANCELED` statuses and `402` and `429` codes are handled.

Ready-made queue clients: [TypeScript SDK](/en/docs/sdk/typescript) and [Python SDK](/en/docs/sdk/python). For general reliability advice, see [Best practices](/en/docs/guides/best-practices).