Идемпотентность
Заголовок Idempotency-Key позволяет безопасно повторять запросы генерации без двойного списания кредитов.
Передавайте заголовок Idempotency-Key с уникальным UUID v4 в каждом POST-запросе на постановку генерации. Если сеть оборвётся и вы повторите запрос с тем же ключом и теми же параметрами, Clipia вернёт тот же request_id — повторная генерация и повторное списание кредитов не произойдут. Ключ хранится 24 часа.
Заголовок
Prop
Type
Как использовать
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! });
// SDK генерирует Idempotency-Key (UUID v4) на каждый submit автоматически.
// Чтобы переиспользовать один ключ для логического запроса — задайте его явно:
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"])
# SDK сам ставит Idempotency-Key на каждый submit; передайте свой при необходимости:
client.submit(
"nano-banana-2",
input={"prompt": "a sunset over mountains, cinematic"},
idempotency_key="8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b",
)Генерируйте новый UUID v4 на каждый логический запрос (а не на каждую сетевую попытку).
Поведение при повторе
| Сценарий | Результат |
|---|---|
| Тот же ключ + те же параметры | Возвращается тот же request_id. Новой генерации и списания нет. |
| Тот же ключ + другие параметры | 409 idempotency_key_reuse |
| Повторный запрос, пока первый ещё обрабатывается | 409 request_in_progress |
| Ключ старше 24 часов | Считается новым логическим запросом |
Окно хранения
Сопоставление «ключ → результат» хранится 24 часа. После этого тот же ключ будет воспринят как новый запрос и создаст новую генерацию.
Только POST и без чувствительных данных
Идемпотентность действует только для POST (постановка генерации) — на GET она не распространяется. Не помещайте в ключ email или иные чувствительные данные: используйте случайный UUID v4.