---
title: Постановка генерации
description: POST /v1/models/{model} — поставить генерацию изображения, видео или аудио в очередь, получить request_id и отправить запрос прямо со страницы.
icon: Send
---

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

## Песочница

<Callout type="info" title="Для проб — тестовый ключ">
В форму ниже вставляйте ключ `clipia_test_…`: он не списывает кредиты и не вызывает модели, а ответ приходит в том же формате. Форма запоминает ключ в этом браузере, поэтому боевой `clipia_live_…` — серверный секрет — в неё не вводите. Подробнее — [«Тестовый режим»](/ru/docs/getting-started/sandbox).
</Callout>

<ApiPlayground path="/v1/models/{model}" method="post" />

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

<Method name="POST" path="/v1/models/:model" />

## Запрос

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

<TypeTable
  type={{
    model: { type: 'string', description: 'Slug модели, например nano-banana-2 или seedance-2-fast-i2v. Строчные латинские буквы, цифры и дефис. Список — GET /v1/models.', required: true }
  }}
/>

**Заголовки**

<TypeTable
  type={{
    Authorization: { type: 'string', description: 'Bearer clipia_live_… (или схема Key, или заголовок X-Api-Key)', required: true },
    'Content-Type': { type: 'string', description: 'application/json', required: true },
    'Idempotency-Key': { type: 'string', description: 'До 255 символов, рекомендуется UUID v4. Делает повтор запроса безопасным в течение 24 часов.' }
  }}
/>

**Тело**

<TypeTable
  type={{
    input: { type: 'object', description: 'Параметры генерации. Состав зависит от модели — схема в GET /v1/models/:model (input_schema). До 100 000 байт и до 8 уровней вложенности.', required: true },
    webhook_url: { type: 'string', description: 'HTTPS-адрес, на который придёт POST по завершении задачи. Внутренние и приватные адреса не принимаются.' }
  }}
/>

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

## Пример

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
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"
  }'
```

</Tab>
<Tab value="TypeScript">

```ts
import { createClient } from 'clipia-ai';

const clipia = createClient({ apiKey: process.env.CLIPIA_KEY! });

// Idempotency-Key добавляется автоматически.
const job = await clipia.queue.submit('nano-banana-2', {
  input: { prompt: 'a sunset over mountains, cinematic', aspect_ratio: '16:9' },
  webhookUrl: 'https://your-server.com/clipia/webhook',
});

console.log(job.request_id, job.cost);
```

</Tab>
<Tab value="Python">

```python
import os
from clipia import Clipia

client = Clipia(api_key=os.environ["CLIPIA_KEY"])

# Idempotency-Key добавляется автоматически.
job = client.submit(
    "nano-banana-2",
    {"prompt": "a sunset over mountains, cinematic", "aspect_ratio": "16:9"},
    webhook_url="https://your-server.com/clipia/webhook",
)

print(job.request_id, job.cost)
```

</Tab>
</Tabs>

**Ответ `200`**

```json
{
  "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
}
```

**Поля ответа**

<TypeTable
  type={{
    request_id: { type: 'string', description: 'Идентификатор задачи (UUID)' },
    status: { type: 'string', description: 'IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED или CANCELED' },
    queue_position: { type: 'integer', description: 'Устарело: всегда 0, позиция в очереди не считается. Поле сохранено для совместимости, в логике не используйте — см. «Версии и совместимость»' },
    status_url: { type: 'string', description: 'Ссылка для проверки статуса' },
    response_url: { type: 'string', description: 'Ссылка для получения результата' },
    cost: { type: 'integer', description: 'Сколько кредитов зарезервировано под задачу' },
    warnings: { type: 'array', description: 'Параметры input, которые модель не применит. Поле есть, только когда такие параметры найдены — см. ниже.' }
  }}
/>

Кредиты из `cost` резервируются при отправке, списываются при успехе и возвращаются полностью, если генерация завершилась ошибкой. Чтобы узнать цену заранее, вызовите [оценку стоимости](/ru/docs/api-reference/estimate) с тем же `input`.

<Callout type="info" title="Повторная отправка">
С заголовком `Idempotency-Key` повтор с тем же телом в течение 24 часов вернёт ту же задачу без второго списания. Без заголовка одинаковые запросы, пришедшие в течение 20 секунд, тоже склеиваются в одну задачу. Повторный ответ в обоих случаях помечен заголовком `Idempotent-Replayed: true`. Подробнее — в разделе [«Идемпотентность»](/ru/docs/api-reference/idempotency).
</Callout>

## Проигнорированные параметры [#warnings]

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

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

<TypeTable
  type={{
    code: { type: 'string', description: 'unknown_parameter — имя серверу неизвестно (например, опечатка); unsupported_parameter — имя существует, но эта модель его не объявляет и не использует. Незнакомое значение читайте как «не применён».' },
    parameter: { type: 'string', description: 'Имя ключа из input' },
    message: { type: 'string', description: 'Пояснение на английском с перечнем параметров, которые модель объявляет' }
  }}
/>

- Когда все параметры приняты, поля `warnings` в ответе нет. В массиве не больше 20 элементов.
- Другое написание объявленного параметра, которое сервер сам приводит к нужному имени, предупреждением не считается.
- Предупреждение появляется только там, где сервер уверен, что параметр не будет применён. Его отсутствие не подтверждает, что каждый параметр подействовал: сверяйте `input` с `input_schema` модели.
- Те же `warnings` возвращают [оценка стоимости](/ru/docs/api-reference/estimate), тестовый ключ и повтор с тем же `Idempotency-Key`.
- В MCP тот же случай — отказ до запуска генерации: см. [«Инструменты MCP»](/ru/docs/mcp/tools#unsupported-parameters).

## Ошибки отправки [#submit-errors]

Ошибки приходят в общем формате `{"error": {"type", "code", "message"}}` — см. [«Ошибки»](/ru/docs/api-reference/errors). Для ошибок `400` конкретная причина передаётся в поле `message`.

| HTTP | `code` | `message` | Когда |
|------|--------|-----------|-------|
| 400 | `invalid_request` | `invalid_model` | slug не соответствует формату: строчные буквы, цифры, дефис |
| 400 | `invalid_request` | `prompt_required` | нет `prompt` и нет исходного изображения или видео |
| 400 | `invalid_request` | `input_too_large` / `input_too_deep` | `input` больше 100 000 байт или глубже 8 уровней |
| 400 | `invalid_request` | `idempotency_key_too_long` | `Idempotency-Key` длиннее 255 символов |
| 400 | `invalid_request` | `webhook_url_invalid` | `webhook_url` не HTTPS или ведёт на внутренний адрес |
| 400 | `invalid_request` | `Too many media URLs…` / `Too many items in <поле>…` | ссылок на исходные файлы больше 30 в одном списке или больше 60 разных в запросе — отказ до проверки адресов и резерва кредитов |
| 400 | `invalid_request` | `media_url_invalid` | ссылка на исходный файл ведёт на внутренний адрес или имеет схему, отличную от `http(s)`. У HeyGen Video сервер переносит файлы по внешним ссылкам в своё хранилище до резерва кредитов; если файл не удалось скачать или он не подходит по типу и размеру, сообщение называет поле и причину: `media_url_invalid: <поле>: <причина>` |
| 400 | `invalid_request` | `num_images greater than 1 is not supported: send one request per image.` | в `input` передан `num_images` больше 1 — одна задача даёт одно изображение |
| 400 | `invalid_request` | текст с лимитом модели | текст озвучки короче или длиннее границ `text_limits` модели; кредиты не резервируются |
| 402 | `insufficient_credits` | — | не хватает кредитов |
| 402 | `subscription_required` | — | нужна активная подписка: это и условие публичного API на боевом ключе, и заморозка кредитов до продления тарифа |
| 402 | `insufficient_quota` | — | с этим запуском расход ключа превысит его бюджет, см. [«Управление ключами»](/ru/docs/api-reference/keys) |
| 403 | `insufficient_scope` | — | у ключа нет права `generate` |
| 404 | `not_found` | `model_not_found` | модели с таким slug нет или она недоступна |
| 409 | `request_in_progress` / `idempotency_key_reuse` | — | см. [«Идемпотентность»](/ru/docs/api-reference/idempotency) |
| 429 | `rate_limit_exceeded` / `concurrency_limit_exceeded` | — | см. [«Лимиты»](/ru/docs/api-reference/rate-limits) |
| 503 | `service_unavailable` | — | у HeyGen Video сервер временно не может перенести файлы по внешним ссылкам; кредиты не резервируются, повторите с паузой |