Queue

Поставить генерацию в очередь (submit)

Ставит генерацию в очередь и сразу возвращает request_id со ссылками на статус и результат. Требует scope generate.

Sandbox. При вызове с тестовым ключом (clipia_test_…) запрос не списывает кредиты и не запускает реальную генерацию: ответ сразу содержит status: COMPLETED и queue_position: 0, а GET /v1/requests/{request_id} вернёт детерминированный mock-output (фиксированный sample-ассет на media.clipia.ai). cost показывает расчётную стоимость, но не списывается.

Проигнорированные параметры. Запрос с ключом input, который модель не применит (опечатка, параметр другой модели), принимается как обычно, а ответ дополнительно содержит массив warnings: по элементу на каждый такой ключ. Предупреждение только сообщает о параметре: запрос обрабатывается так же, как раньше, отказа за лишний ключ нет. Когда все параметры приняты, поля warnings в ответе нет. Тестовый ключ и повтор с тем же Idempotency-Key возвращают те же warnings.

post/v1/models/{model}

Request

  • Base URL: https://api.clipia.ai
  • URL: https://api.clipia.ai/v1/models/{model}
  • Auth: API key in header Authorization

Path parameters

modelstring required
Example:nano-banana-2

Slug модели, напр. nano-banana-2, seedance-2-fast-i2v. Список — GET /v1/models. Слаги с пространством имён (google/imagen4, grok-imagine/text-to-video) передаются как есть (/v1/models/google/imagen4) либо с %2F.

Headers

Idempotency-Keystring uuid
Example:8f3a1c7e-2b4d-4e6f-9a01-23456789abcd

UUID v4 для безопасных ретраев POST. Тот же ключ с теми же параметрами вернёт тот же request_id (без повторного списания). Срок хранения — 24 часа. Тот же ключ с другими параметрами → 409.

Request body

inputobject required

Параметры генерации. Состав зависит от модели — точную схему смотрите в GET /v1/models/{model} (input_schema). Распространённые ключи: prompt, image_url, image_urls, aspect_ratio, duration, resolution — но у каждой модели свой набор: ключ, которого модель не объявляет и не читает, не применяется и возвращается в warnings ответа.

webhook_urlstring uri

URL для POST-уведомления о завершении генерации (опционально).

Example request

{
  "input": {
    "prompt": "a sunset over mountains, cinematic",
    "aspect_ratio": "16:9"
  },
  "webhook_url": "https://your-server.com/clipia/webhook"
}

Response

Генерация принята и поставлена в очередь.

request_idstring uuid required

Идентификатор запроса генерации.

status'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELED' required

Статус генерации в очереди. CANCELED — терминальный: генерацию можно отменить вне публичного API (например, из веб-интерфейса Clipia); cancel-эндпоинта в публичном API нет, но status может вернуть CANCELED, поэтому клиент обязан считать его финальным.

queue_positioninteger nullable

Позиция в очереди (если запрос в очереди).

status_urlstring uri required

Ссылка для проверки статуса.

response_urlstring uri required

Ссылка для получения результата.

costnumber required

Фиксированная стоимость операции в кредитах (резервируется при submit).

Example response

{
  "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."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.