API Reference
Idempotency
The Idempotency-Key header makes retrying a generation submit safe — the same request returns the same request_id with no second job and no second charge.
Send an Idempotency-Key header when you submit a generation. If the connection drops and you retry with the same key and the same body, Clipia returns the same response with the same request_id: no second job is created and no credits are charged twice. The record is kept for 24 hours.
Header
Prop
Type
Usage
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, cinematic" } }'Create a new key for each logical request, not for each network attempt. When the SDK generates the key, each submit call gets its own; a retry in your code that makes a new call gets a new key.
Retry behavior
| Situation | Result |
|---|---|
| Same key, same model, same body | The same response in full (including warnings, if there were any) and the same request_id. No new job, no new charge |
| Same key, different model or body | 409 idempotency_key_reuse |
| Retry while the first request is still being processed | 409 request_in_progress — retry in a few seconds |
| The first request ended with an error | The key is released and the retry is processed from scratch |
| More than 24 hours have passed | The key counts as new and creates a new job |
Keys don't overlap across API keys: the same Idempotency-Key on two API keys means two separate requests.
Every replayed response — with an explicit key or merged without the header — carries the Idempotent-Replayed: true header; the response to a new job does not.
Without the header
Without the header, identical requests from one API key that arrive within 20 seconds are also merged into one job. This guards against an accidental double click or a quick network retry. If you deliberately want two identical generations in a row, send different Idempotency-Key values.
Where it applies
The header applies to POST /v1/models/{model} and to non-streaming POST /v1/chat/completions and POST /v1/completions; with stream: true it is ignored. Merging without the header happens only on generation submit. GET requests are safe to retry without it. Don't put an email or other personal data in the key — use a random UUID v4.
Account and balance
GET /v1/account — the account's available balance in credits, plus the request count and credits spent by this key over the last 30 days.
Webhooks
A POST notification to your server when a generation finishes — body format, HMAC-SHA256 signature check, response deadline and the redelivery schedule.