---
title: Идемпотентность
description: Заголовок Idempotency-Key позволяет безопасно повторять запросы генерации без двойного списания кредитов.
---

Передавайте заголовок `Idempotency-Key` с уникальным UUID v4 в каждом `POST`-запросе на постановку генерации. Если сеть оборвётся и вы повторите запрос с тем же ключом и теми же параметрами, Clipia вернёт **тот же** `request_id` — повторная генерация и повторное списание кредитов не произойдут. Ключ хранится 24 часа.

## Заголовок

<TypeTable
  type={{
    'Idempotency-Key': {
      type: 'string (UUID v4)',
      description: 'Уникальный ключ логического запроса. Тот же ключ + те же параметры → тот же request_id без повторного списания. Хранится 24 часа.',
      required: false,
    },
  }}
/>

## Как использовать

<Tabs items={['cURL', 'TypeScript', 'Python']}>

<Tab value="cURL">

```bash
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" } }'
```

</Tab>

<Tab value="TypeScript">

```ts
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',
});
```

</Tab>

<Tab value="Python">

```python
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",
)
```

</Tab>

</Tabs>

Генерируйте новый UUID v4 на каждый **логический** запрос (а не на каждую сетевую попытку).

## Поведение при повторе

| Сценарий | Результат |
|----------|-----------|
| Тот же ключ + те же параметры | Возвращается тот же `request_id`. Новой генерации и списания нет. |
| Тот же ключ + другие параметры | `409 idempotency_key_reuse` |
| Повторный запрос, пока первый ещё обрабатывается | `409 request_in_progress` |
| Ключ старше 24 часов | Считается новым логическим запросом |

<Callout type="info" title="Окно хранения">
Сопоставление «ключ → результат» хранится 24 часа. После этого тот же ключ будет воспринят как новый запрос и создаст новую генерацию.
</Callout>

<Callout type="warn" title="Только POST и без чувствительных данных">
Идемпотентность действует только для `POST` (постановка генерации) — на `GET` она не распространяется. Не помещайте в ключ email или иные чувствительные данные: используйте случайный UUID v4.
</Callout>