---
title: "Поставить генерацию в очередь (submit)"
method: POST
path: "/v1/models/{model}"
tags: ["Queue"]
---

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

`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`

Ставит генерацию в очередь и сразу возвращает `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`.

## Path parameters

- `model` string, required

## Headers

- `Idempotency-Key` string, uuid

## Request body

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

## Response `200`

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

- SubmitResponse
  - `request_id` string, uuid, required: Идентификатор запроса генерации.
  - `status` 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELED', required: Статус генерации в очереди. `CANCELED` — терминальный: генерацию можно отменить вне публичного API (например, из веб-интерфейса Clipia); cancel-эндпоинта в публичном API нет, но `status` может вернуть `CANCELED`, поэтому клиент обязан считать его финальным.
  - `queue_position` integer, nullable: Позиция в очереди (если запрос в очереди).
  - `status_url` string, uri, required: Ссылка для проверки статуса.
  - `response_url` string, uri, required: Ссылка для получения результата.
  - `cost` number, required: Фиксированная стоимость операции в кредитах (резервируется при submit).
  - `warnings` InputWarning[]: Параметры `input`, которые модель не применит: по элементу на ключ, не больше 20 элементов. Поле присутствует, только когда такие параметры есть.
    - `code` string, required: Машинная причина: - `unknown_parameter` — ключ серверу неизвестен (например, опечатка) и отбрасывается у любой модели; - `unsupported_parameter` — ключ существует, но эта модель его не объявляет и не использует; - `audio_dropped` — звук был включён, но звуковая дорожка не прошла проверку безопасности модели: ролик создаётся без звука, стоимость запроса не меняется. Приходит только в ответах о состоянии запроса (`RequestWarnings`), `parameter` равен `generate_audio`. Список причин может пополняться: незнакомое значение обрабатывайте как «параметр не применён».
    - `parameter` string, required: Имя ключа из `input` (длинное имя обрезается до 64 символов).
    - `message` string, required: Пояснение на английском: называет параметр и перечисляет параметры, которые модель объявляет в `input_schema`. Для `audio_dropped` — сообщает, что ролик создаётся без звука.

## Other responses

- `401`: Ключ отсутствует, неверный или отозван.
- `402`: Не хватает кредитов на балансе (`insufficient_credits` — помогает пополнение) ЛИБО кредиты есть, но заморожены до активной подписки (`subscription_required` — пополнение НЕ поможет, нужно оформить/продлить тариф). Различайте по `error.code`. Язык `message` — по заголовку `Accept-Language` (`ru` → русский, иначе английский).
- `403`: У ключа нет нужного scope.
- `422`: Параметры `input` не подходят выбранной модели.
- `429`: Превышен лимит. `error.type` всегда `rate_limit_error`; различайте по `error.code`: - `rate_limit_exceeded` — запросов в минуту (RPM) или токенов в минуту (TPM) по ключу; - `concurrency_limit_exceeded` — слишком много генераций одновременно (по ключу или по аккаунту). Дождитесь завершения одной и повторите. В обоих случаях сервер отдаёт заголовок `Retry-After` и дублирует подсказку в `error.retry_after_seconds`.

---

[API](https://skmtc.dev/clipia/apis/clipia-api.md) · [All operations](https://skmtc.dev/clipia/apis/clipia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clipia/apis/clipia-api/revisions/cc55924a3381?raw)