Рекомендации — Документация Clipia

Чтобы интеграция с Clipia API была надёжной и предсказуемой по стоимости, придерживайтесь пяти практик: делайте отправки идемпотентными, предпочитайте вебхуки опросу, обрабатывайте ошибки и 429 с растущей паузой, оценивайте стоимость до отправки и сохраняйте request_id у себя.

Идемпотентность при повторах

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

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

Ситуация	Результат
Тот же ключ и то же тело	Тот же `request_id`, без повторного списания
Тот же ключ, другая модель или другое тело	`409 idempotency_key_reuse`
Повтор, пока первый запрос ещё обрабатывается	`409 request_in_progress` — повторите через несколько секунд

Один ключ на логический запрос

Создавайте новый UUID на каждую новую генерацию, а не на каждую сетевую попытку. SDK подставляют случайный ключ сами, но для безопасного повтора передайте свой и используйте его снова. Не кладите в ключ персональные данные. Подробнее — в разделе «Идемпотентность».

Вебхуки вместо опроса

Передайте webhook_url (только https://) при отправке — Clipia сам пришлёт POST, когда задача завершится, и опрашивать статус не придётся. Опрос держите запасным вариантом и делайте его не чаще раза в 1–3 секунды.

Отвечайте 2xx в течение 10 секунд, иначе доставка повторится — всего до 15 попыток с растущей паузой, около 24 часов.
Проверяйте подпись X-Clipia-Signature (HMAC-SHA256) на каждой доставке. Секрет вебхуков свой у каждого API-ключа.
Обрабатывайте доставки идемпотентно по request_id: одна и та же доставка может прийти повторно.

Подробнее — в разделе «Вебхуки».

Ошибки и 429

Ошибки приходят в едином формате: объект error с полями type, code и message. Решение принимайте по HTTP-статусу и code.

HTTP	`code`	Что делать
`400` / `422`	`invalid_request` / `model_input_invalid`	Исправить тело или параметры, не повторять как есть
`401` / `403`	`invalid_api_key` / `insufficient_scope`	Проверить ключ и его права
`402`	`insufficient_credits`	Пополнить баланс
`409`	`request_in_progress`	Повторить через несколько секунд с тем же ключом идемпотентности
`429`	`rate_limit_exceeded`	Подождать `Retry-After` секунд и повторить
`429`	`concurrency_limit_exceeded`	Дождаться завершения одной из задач
`500` / `503`	`internal_error` / `service_unavailable`	Повторить с растущей паузой

При 429 ориентируйтесь на Retry-After и заголовки RateLimit-*. RateLimit-Reset — момент сброса окна в Unix-секундах, а не число секунд до него:

RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 1760011260
Retry-After: 37

Растущая пауза со случайной добавкой

Для 429, 500 и 503 повторяйте с растущей паузой и случайной добавкой — например 1, 2, 4, 8 секунд, не больше пяти попыток, — чтобы повторы разных клиентов не совпадали. Лимиты по умолчанию: 120 запросов в минуту на ключ и 600 на все ключи аккаунта. Лимит одновременных генераций действует, только если он задан для ключа или аккаунта. Подробнее — в разделе «Лимиты».

Оценка стоимости до отправки

Чтобы узнать цену конкретного набора параметров без постановки в очередь, вызовите POST /v1/models/{model}/estimate — он вернёт credits. Так можно показать стоимость пользователю или заранее отсечь дорогие запросы. При отправке в поле cost приходит сумма, зарезервированная под задачу; при нехватке кредитов отправка вернёт 402. Подробнее — в разделе «Оценка стоимости».

Цены

Цены моделей меняются вместе с каталогом: точную сумму в кредитах под ваши параметры возвращает estimate, а при отправке она приходит в поле cost до списания.

Хранение request_id

Сохраняйте request_id каждой отправки в своей базе сразу после ответа. Он нужен, чтобы:

сопоставить пришедший вебхук с вашей сущностью;
при необходимости опросить status_url или response_url;
не обработать одну доставку дважды.

Связка Idempotency-Key и request_id

Храните пару Idempotency-Key → request_id. Если ответ на отправку потерялся, повтор с тем же ключом вернёт тот же request_id, и дубль генерации не появится.

Идемпотентность при повторахСкопировать ссылку на раздел

Вебхуки вместо опросаСкопировать ссылку на раздел

Ошибки и 429Скопировать ссылку на раздел

Оценка стоимости до отправкиСкопировать ссылку на раздел

Хранение request_idСкопировать ссылку на раздел

На этой странице

Идемпотентность при повторах

Вебхуки вместо опроса

Ошибки и 429

Оценка стоимости до отправки

Хранение request_id