Idempotency
The Idempotency-Key header lets you safely retry generation requests without double-charging credits.
Send an Idempotency-Key header with a unique UUID v4 on every POST request that submits a generation. If the network drops and you retry with the same key and the same parameters, Clipia returns the same request_id — no duplicate generation and no second charge. The key is stored for 24 hours.
Header
Prop
Type
How to use it
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: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
-d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'import { createClient } from 'clipia-ai';
const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });
// The SDK sets an Idempotency-Key (UUID v4) on every submit automatically.
// To reuse one key for a logical request, pass it explicitly:
await clipia.queue.submit('nano-banana-2', {
input: { prompt: 'a sunset over mountains, cinematic' },
idempotencyKey: '8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b',
});import os
from clipia import Clipia
client = Clipia(api_key=os.environ["CLIPIA_KEY"])
# The SDK sets an Idempotency-Key on every submit; pass your own when needed:
client.submit(
"nano-banana-2",
input={"prompt": "a sunset over mountains, cinematic"},
idempotency_key="8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b",
)Generate a fresh UUID v4 for each logical request (not for each network retry).
Behaviour on retry
| Scenario | Result |
|---|---|
| Same key + same parameters | The same request_id is returned. No new generation, no charge. |
| Same key + different parameters | 409 idempotency_key_reuse |
| Retry while the first request is still processing | 409 request_in_progress |
| Key older than 24 hours | Treated as a new logical request |
Retention window
The key-to-result mapping is kept for 24 hours. After that, the same key is treated as a new request and creates a new generation.
POST only, no sensitive data
Idempotency applies only to POST (submitting a generation) — it has no effect on GET. Never put an email or other sensitive data in the key: use a random UUID v4.