Рекомендации
Практики для надёжной интеграции с Clipia API — идемпотентность на ретраях, вебхуки вместо опроса, обработка ошибок и 429 с backoff, оценка стоимости и хранение request_id.
Чтобы интеграция с Clipia API была надёжной и предсказуемой по стоимости, придерживайтесь пяти практик: делайте отправки идемпотентными, предпочитайте вебхуки опросу, обрабатывайте ошибки и 429 с экспоненциальной задержкой, оценивайте стоимость до отправки и сохраняйте request_id на своей стороне. Ниже — каждая практика отдельно.
Идемпотентность на ретраях
Передавайте Idempotency-Key (уникальный UUID v4 на каждый логический запрос) при каждой отправке. При сетевом сбое повторите запрос с тем же ключом и теми же параметрами — вернётся тот же request_id, без повторной генерации и повторного списания. Ключ хранится 24 часа.
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
-H "Authorization: Bearer clipia_live_xxx" \
-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 v4 на каждую новую генерацию, а не на каждую сетевую попытку. Не кладите в ключ чувствительные данные (email и т.п.).
Вебхуки вместо опроса
Передавайте webhook_url при отправке — Clipia сам пришлёт POST по завершении, и опрашивать статус не придётся. Опрос (polling) держите как запасной вариант. Если опрашиваете — делайте это разумно (например, раз в 1–3 секунды), а не в плотном цикле.
- Отвечайте
2xxв течение 10 секунд, иначе будет ретрай (до 6 попыток с экспоненциальной задержкой). - Проверяйте подпись
X-Clipia-Signature(HMAC-SHA256) на каждой доставке. - Обрабатывайте доставки идемпотентно по
request_id— возможна повторная доставка.
Обработка ошибок и 429 с backoff
Ошибки приходят в едином JSON-формате с полями error.type, error.code, error.message. Реагируйте по HTTP-коду.
| HTTP | code | Что делать |
|---|---|---|
400 / 422 | invalid_request / model_input_invalid | исправить тело/параметры, не ретраить как есть |
401 / 403 | invalid_api_key / insufficient_scope | проверить ключ и scope |
402 | insufficient_credits | пополнить баланс |
429 | rate_limit_exceeded | подождать Retry-After секунд, затем повторить |
500 / 503 | internal_error / service_unavailable | ретрай с экспоненциальной задержкой |
При 429 ориентируйтесь на заголовок Retry-After и метрики RateLimit-*:
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37Экспоненциальная задержка с джиттером
Для 429, 500 и 503 повторяйте с растущей паузой и случайным джиттером (например 1с, 2с, 4с, 8с… плюс случайная добавка), чтобы не создавать всплесков. По умолчанию лимиты — 120 RPM и 10 параллельных генераций на ключ.
Оценка стоимости до отправки
Цена операции фиксирована и известна заранее. Чтобы узнать стоимость конкретного набора параметров без постановки в очередь, используйте POST /v1/models/{model}/estimate — он вернёт credits. Так можно показать стоимость пользователю или отсечь дорогие запросы заранее. При отправке цена дублируется в поле cost; при нехватке кредитов отправка вернёт 402.
Хранение request_id
Сохраняйте request_id каждой отправки в своей БД сразу после ответа submit. Он нужен, чтобы:
- сопоставить пришедший вебхук с вашей сущностью;
- опросить
status_url/response_urlпри необходимости; - обеспечить идемпотентность на своей стороне (не обрабатывать одну доставку дважды).
Связка request_id ↔ Idempotency-Key
Храните пару Idempotency-Key → request_id: при потере ответа на submit повторный запрос с тем же ключом вернёт тот же request_id, и вы не создадите дубль генерации.