Migrating from another generation API

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

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.

What to change in your code

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: GET /v1/models/{model} returns the full schema.

Key

Create a key in the developer console; 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.

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.

Where Clipia may differ

• 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.
• Limits. 120 requests per minute per key and 600 across all keys of an account, with RateLimit-* headers — see Rate limits.

Pre-launch 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 and Python SDK. For general reliability advice, see Best practices.