> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Генерация видео Vidu Q3

> Создание асинхронных задач генерации видео с моделями Vidu Q3.

<Note>
  **Для пользователей из материкового Китая:** используйте `https://toapis.cn` в качестве эндпоинта (Base URL). Замените `https://toapis.com` на `https://toapis.cn` во всех примерах этого документа.
</Note>

* Асинхронный API задач: после отправки возвращает унифицированный `generation.task`
* Доступные модели: `viduq3-pro-fast`, `viduq3-ad`, `viduq3-drama`, `viduq3-mix`

<Warning>
  `viduq3-ad`, `viduq3-drama` и `viduq3-mix` — не чистые модели text-to-video. Не передавайте только `prompt`; требуется хотя бы референс-материал. Иначе апстрим обычно возвращает `InvalidParameter`, например `Missing required field 'subjects' in request body`.
</Warning>

## Аутентификация

<ParamField header="Authorization" type="string" required>
  Все эндпоинты требуют Bearer Token аутентификацию.

  ```http theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Поддерживаемые модели

| Модель | Тип генерации | Рекомендуемый ввод | Рекомендуемое разрешение |
| - | - | - | - |
| `viduq3-pro-fast` | Image-to-video по первому кадру | 1 референсное изображение | `720P` / `1080P` |
| `viduq3-ad` | Генерация по референс-видео | Референс-видео + референсное изображение | `720P` / `1080P` |
| `viduq3-drama` | Нарративная генерация по референсу | Референс-видео + референсное изображение | `1080P` |
| `viduq3-mix` | Смешанная генерация по референсам | Референс-видео + референсное изображение | `720P` / `1080P` |

## Параметры запроса

<ParamField body="model" type="string" required>
  Поддерживаются только следующие 4 публичных имени моделей:

  * `viduq3-pro-fast`
  * `viduq3-ad`
  * `viduq3-drama`
  * `viduq3-mix`
</ParamField>

<ParamField body="prompt" type="string" required>
  Промпт.

  Даже для моделей референс-генерации рекомендуется всегда заполнять `prompt`, описывая ракурсы, движение, темп и стиль.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Список URL референсных изображений.

  * `viduq3-pro-fast`: используется только первое изображение в качестве первого кадра
  * `viduq3-ad` / `viduq3-drama` / `viduq3-mix`: рекомендуется одно или несколько референсных изображений субъекта/стиля

  Совместимые поля:

  * `input_reference`
  * `reference_images`
  * `images`
  * `image`
</ParamField>

<ParamField body="url" type="string">
  URL референсного видео.

  Рекомендуется только для `viduq3-ad` / `viduq3-drama` / `viduq3-mix`. Эквивалентно передаче одного основного референс-видео.
</ParamField>

<ParamField body="video_list" type="array">
  Список референсных видео.

  Используется только `viduq3-ad` / `viduq3-drama` / `viduq3-mix`. Каждый элемент поддерживает:

  * `video_url`
  * `refer_type` (опционально)
  * `keep_original_sound` (опционально)
</ParamField>

<ParamField body="duration" type="integer" default={5}>
  Длительность видео в секундах. По умолчанию `5`.
</ParamField>

<ParamField body="resolution" type="string" default="720P">
  Разрешение, поддерживаются `720P` и `1080P`.

  Рекомендации:

  * Для `viduq3-drama` предпочтительно `1080P`
</ParamField>

<ParamField body="audio" type="boolean">
  Генерировать ли аудио.

  Текущее поведение сервера по умолчанию:

  * `viduq3-pro-fast`: по умолчанию `true`
  * `viduq3-ad`: по умолчанию `true`
  * `viduq3-mix`: по умолчанию `true`
  * `viduq3-drama`: передавайте значение явно, не полагайтесь на значение по умолчанию
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  Добавлять ли водяной знак.
</ParamField>

<ParamField body="seed" type="integer">
  Зерно генерации.
</ParamField>

<ParamField body="metadata" type="object">
  Расширенные параметры, передаются по структуре видео-запроса апстрима.

  Типичные варианты:

  * `metadata.input.first_frame_url`
  * `metadata.input.last_frame_url`
  * `metadata.input.audio_url`
  * `metadata.parameters.audio`
  * `metadata.parameters.watermark`

  <Warning>
    `viduq3-ad` / `viduq3-drama` / `viduq3-mix` на стороне апстрима могут требовать структурированный ввод субъектов (например, `subjects`). Запрос только с текстовым prompt обычно сразу завершается ошибкой.
  </Warning>
</ParamField>

## Правила ввода

### 1. `viduq3-pro-fast`

* Модель image-to-video по первому кадру
* Требуется минимум 1 изображение
* При передаче нескольких изображений используется только первое
* Подходит для сценариев «оживить статичное изображение»

### 2. `viduq3-ad` / `viduq3-drama` / `viduq3-mix`

* Модели генерации по референс-видео; вызов только с prompt не рекомендуется
* Рекомендуется передавать минимум:
  * 1 референс-видео: `url` или `video_list`
  * 1 референсное изображение: `image_urls` или совместимое поле изображения
* При отсутствии субъекта/референсов апстрим может вернуть:
  * `InvalidParameter`
  * `Missing required field 'subjects' in request body`

## Примеры запросов

### `viduq3-pro-fast` image-to-video по первому кадру

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-pro-fast",
    "prompt": "让角色自然抬头微笑，镜头轻微推进，保留原画风格。",
    "image_urls": [
      "https://example.com/first-frame.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true,
    "watermark": false
  }'
```

### `viduq3-ad` генерация по референс-видео

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-ad",
    "prompt": "延续参考视频中的节奏与镜头语言，让主角走入商场中庭并面向镜头挥手。",
    "url": "https://example.com/reference-video.mp4",
    "image_urls": [
      "https://example.com/subject-reference.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "audio": true
  }'
```

### `viduq3-drama` нарративная генерация по референсу

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-drama",
    "prompt": "保持角色一致性，情绪逐步递进，镜头由中景切到近景。",
    "video_list": [
      {
        "video_url": "https://example.com/reference-scene.mp4"
      }
    ],
    "image_urls": [
      "https://example.com/character.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "watermark": false
  }'
```

### `viduq3-mix` смешанная генерация по референсам

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-mix",
    "prompt": "融合参考视频动作与参考图角色设定，生成一个更具广告感的过场镜头。",
    "url": "https://example.com/reference-action.mp4",
    "image_urls": [
      "https://example.com/brand-character.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true
  }'
```

## Ответ при успешной отправке

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1784169600
}
```

## Запрос задачи

`GET /v1/videos/generations/{task_id}`

В обработке:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "in_progress",
  "progress": 60,
  "created_at": 1784169600
}
```

Успех:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169660,
  "expires_at": 1784256060,
  "result": {
    "type": "video",
    "data": [
      {
        "url": "https://files.toapis.com/videos/vid_01KABCDEF1234567890.mp4",
        "format": "mp4"
      }
    ]
  }
}
```

Ошибка:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-ad",
  "status": "failed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169620,
  "error": {
    "code": "InvalidParameter",
    "message": "Missing required field 'subjects' in request body"
  }
}
```

## Примечания

* После отправки ToAPIs централизованно опрашивает статус апстрим-задачи и возвращает стандартный результат видео-задачи.
* `viduq3-pro-fast` — наиболее стабильная форма интеграции на сегодня, подходит для image-to-video по первому кадру.
* `viduq3-ad`, `viduq3-drama` и `viduq3-mix` предъявляют более строгие требования к референс-материалам. Перед интеграцией подготовьте полный набор материалов по примерам выше и не передавайте только prompt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.