Быстрый старт

Создайте API-ключСкопировать ссылку на раздел

Откройте консоль разработчика, вкладка API-ключи → Создать ключ. Полный ключ показывается один раз — сохраните его сразу. Во всех примерах документации ключ лежит в переменной окружения CLIPIA_KEY.

export CLIPIA_KEY=clipia_live_xxxxxxxxxxxxxxxxxxxxxxxx

Поставьте генерациюСкопировать ссылку на раздел

Отправьте POST /v1/models/{model} с телом input. Slug модели берите из GET /v1/models или из каталога моделей. Заголовок Idempotency-Key делает повторную отправку после сетевого сбоя безопасной: вторая задача не создастся.

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" },
    "webhook_url": "https://your-server.com/clipia/webhook"
  }'

SDK сами добавляют Idempotency-Key к каждой отправке. Ответ содержит request_id и ссылки для опроса:

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "status_url":   "https://api.clipia.ai/v1/requests/764cabcf-.../status",
  "response_url": "https://api.clipia.ai/v1/requests/764cabcf-...",
  "cost": 12
}

Поле cost — сколько кредитов зарезервировано под задачу. При успехе они списываются, при ошибке генерации возвращаются полностью. Узнать цену до отправки можно через оценку стоимости.

Дождитесь завершенияСкопировать ссылку на раздел

Есть два способа узнать, что генерация готова.

Вебхук (рекомендуется). Если при отправке передан webhook_url, Clipia пришлёт POST на ваш сервер, когда задача завершится. Доставка подписана HMAC-SHA256 — см. «Вебхуки».

Опрос статуса. Запрашивайте status_url раз в 1–2 секунды, пока статус не станет терминальным:

curl https://api.clipia.ai/v1/requests/764cabcf-.../status \
  -H "Authorization: Bearer $CLIPIA_KEY"

{ "request_id": "764cabcf-...", "status": "IN_PROGRESS", "queue_position": 0, "progress": 45 }

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

Когда статус COMPLETED, запросите результат по response_url:

curl https://api.clipia.ai/v1/requests/764cabcf-... \
  -H "Authorization: Bearer $CLIPIA_KEY"

{
  "request_id": "764cabcf-...",
  "status": "COMPLETED",
  "model": "nano-banana-2",
  "output": {
    "images": [
      {
        "url": "https://media.clipia.ai/....webp",
        "original_url": "https://media.clipia.ai/....png"
      }
    ]
  },
  "cost": 12,
  "created_at": "2026-10-09T12:00:00Z",
  "completed_at": "2026-10-09T12:00:18Z"
}

url — оптимизированная копия для показа, original_url — исходный файл. Для видео output содержит video: { url, original_url, thumbnail_url }, для аудио — audio: { url }. Подробности — на странице «Результат».