API for developers
Generate images and video over the API: an async queue, signed webhooks, TypeScript and Python SDKs, a CLI, and credit-based billing. The same models as the app.
- Queue API
- submit → poll / webhook
- TS · Python · CLI
- official SDKs
- Images and video
- one entry point
What the API gives you
A production-ready integration in five minutes — no surprises in prod.
Queue API
An async queue: submit enqueues a job and returns a request_id right away. Collect the result by polling status_url or instantly via a webhook.
SDKs and CLI
Official clients for TypeScript and Python with a high-level subscribe, plus a CLI for scripts and quick checks.
Sandbox
A clipia_test_ key returns a fixed result instantly — debug response parsing, polling, and webhooks with no credits spent.
Signed webhooks
On completion Clipia sends a POST signed with HMAC-SHA256. Verify the signature against the raw body — the SDKs ship a ready helper.
Idempotency
The Idempotency-Key header makes retries safe: the same key returns the same request_id — no duplicate jobs, no double charge.
Transparent limits
Per-key limits: requests per minute and concurrent generations. The current state is in the RateLimit-* headers on every response.
Quickstart in 5 minutes
One text-to-image job — three ways. First put your key in an environment variable.
export CLIPIA_KEY="clipia_live_xxxxxxxxxxxxxxxxxxxxxx"# Submit a text-to-image job
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
-H "Authorization: Key $CLIPIA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'
# Poll the request until status == COMPLETED, then read the result
curl https://api.clipia.ai/v1/requests/<request_id> \
-H "Authorization: Key $CLIPIA_KEY"The SDKs generate an Idempotency-Key (UUID v4) per submit by default, so retries are safe out of the box.
Install the SDK
The high-level subscribe enqueues the job and polls until the result is ready.
npm i clipia-aipip install clipianpx clipia accountPackage names are final; publishing to npm and PyPI is part of launch.
Authentication
Send your API key in the Authorization header with the Key scheme.
Authorization: Key clipia_live_xxxxxxxxxxxxxxxxxxxxxxIt is the equivalent of a password to your credit balance. Make calls only from your own server and keep the key in an environment variable or a secrets manager. Never put it in a browser, mobile app, or public repository.
A live key is shown once on creation. Afterwards the list shows only the prefix.
Error handling
Every error arrives in a single JSON shape. The SDKs throw a typed error with .status and .code.
| HTTP | Code | When | Retry |
|---|---|---|---|
| 400 | invalid_request | Invalid body or parameters | Do not retry |
| 401 | invalid_api_key | Key missing, invalid, or revoked | Do not retry |
| 402 | insufficient_credits | Not enough credits on the balance | Do not retry |
| 402 | subscription_required | You have credits, but they are locked — an active subscription is required | Do not retry |
| 403 | insufficient_scope | The key lacks the required scope | Do not retry |
| 404 | not_found | Unknown request_id or model | Do not retry |
| 409 | idempotency_key_reuse | Idempotency conflict | Do not retry |
| 422 | model_input_invalid | Parameters do not match the model | Do not retry |
| 429 | rate_limit_exceeded | Rate limit exceeded | With backoff |
| 5xx | internal_error | Internal error or temporary unavailability | With backoff |
Webhooks instead of polling
For production, pass webhook_url on submit — Clipia delivers the result as soon as it is ready.
Signature verification
Each delivery is signed with HMAC-SHA256 in the X-Clipia-Signature header. Verify the signature against the raw request body before JSON parsing — the SDKs ship a verify helper.
Delivery and retries
Respond with 2xx within 10 seconds. On failure, deliveries retry with exponential backoff. The same event may arrive again, so handle webhooks idempotently by request_id.
MCP for Claude Code & AI agents
Clipia MCP lets you generate images and video right from Claude Code, Cursor, and any other MCP client. Endpoint: https://mcp.clipia.ai/mcp, authorized with an API key. Full guide for every agent: claude.ai, ChatGPT, Cursor and more
https://mcp.clipia.ai/mcpclaude mcp add --transport http clipia https://mcp.clipia.ai/mcp --header "Authorization: Bearer YOUR_KEY"{
"mcpServers": {
"clipia": {
"url": "https://mcp.clipia.ai/mcp",
"headers": { "Authorization": "Bearer YOUR_KEY" }
}
}
}| Tool | What it does |
|---|---|
generate_image | Submit an image generation job |
generate_video | Submit a video generation job |
wait_generation | Wait until a generation finishes |
get_generation | Status and result of a generation by ID |
list_models | List available models and their credit prices |
get_model | Parameters and price of a specific model |
get_balance | Current credit balance |
search_templates | Search the prompt template library |
Keys with the clipia_test_ prefix run in the sandbox — instant mock responses with no credits charged.
Create your key in Settings → API keys.
Next steps
Ready to integrate — get a key. Need contract details — download the full specification.
Full reference
The OpenAPI 3.1 specification with every endpoint, schema, and webhook — import it into your own tooling.
Download OpenAPIGet an API key
Create a key in your account on the API / Developers tab — live or test.
Get a keyFor business
Teams, volume discounts, bank transfer and closing documents for legal entities.
Open the section