Постановка генерации

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

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

Authorization: Bearer <CLIPIA_API_KEY>

curl -X POST "https://example.com/v1/models/nano-banana-2" \  -H "Content-Type: application/json" \  -d '{    "input": {      "prompt": "a sunset over mountains, cinematic",      "aspect_ratio": "16:9"    },    "webhook_url": "https://your-server.com/clipia/webhook"  }'

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

POST /v1/models/:model ставит генерацию в очередь и сразу возвращает request_id, ссылки на статус и результат и зарезервированную стоимость в кредитах. Нужен ключ с правом generate.

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

Параметр пути

Заголовки

Тело

Частые ключи внутри input: prompt, image_url, image_urls, aspect_ratio, duration, resolution — но набор у каждой модели свой: передавайте то, что модель объявляет в input_schema (что будет с лишним ключом — ниже). Если модель работает с исходным изображением или видео, prompt можно не передавать; иначе он обязателен.

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

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-2b4d-4e6f-9a01-23456789abcd" \
  -d '{
    "input": {
      "prompt": "a sunset over mountains, cinematic",
      "aspect_ratio": "16:9"
    },
    "webhook_url": "https://your-server.com/clipia/webhook"
  }'

Ответ 200

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

Поля ответа

Кредиты из cost резервируются при отправке, списываются при успехе и возвращаются полностью, если генерация завершилась ошибкой. Чтобы узнать цену заранее, вызовите оценку стоимости с тем же input.

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

Набор параметров у каждой модели свой. Если в input попал ключ, который модель не применит, — опечатка, параметр другой модели, ключ из старого примера — запрос принимается как раньше, отказа нет. Но ответ дополнительно содержит массив warnings, по элементу на каждый такой ключ:

{
  "request_id": "5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11",
  "status": "IN_QUEUE",
  "queue_position": 0,
  "status_url": "https://api.clipia.ai/v1/requests/5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11/status",
  "response_url": "https://api.clipia.ai/v1/requests/5b0c1f7e-2a53-4a0e-9d0b-6f1f4d0f2c11",
  "cost": 12,
  "warnings": [
    {
      "code": "unsupported_parameter",
      "parameter": "duration",
      "message": "Parameter \"duration\" is not supported by model \"nano-banana-2\" and was ignored. Parameters declared by this model: aspect_ratio, prompt, resolution. Full schema: GET /v1/models/nano-banana-2."
    }
  ]
}

• Когда все параметры приняты, поля warnings в ответе нет. В массиве не больше 20 элементов.
• Другое написание объявленного параметра, которое сервер сам приводит к нужному имени, предупреждением не считается.
• Предупреждение появляется только там, где сервер уверен, что параметр не будет применён. Его отсутствие не подтверждает, что каждый параметр подействовал: сверяйте input с input_schema модели.
• Те же warnings возвращают оценка стоимости, тестовый ключ и повтор с тем же Idempotency-Key.
• В MCP тот же случай — отказ до запуска генерации: см. «Инструменты MCP».

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

Ошибки приходят в общем формате {"error": {"type", "code", "message"}} — см. «Ошибки». Для ошибок 400 конкретная причина передаётся в поле message.