> ## 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` во всех примерах этого документа.

* Асинхронный 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`.

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

**Authorization** `string` *required*

Все эндпоинты требуют Bearer Token аутентификацию.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

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

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

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

**model** `string` *required*

Поддерживаются только следующие 4 публичных имени моделей:

* `viduq3-pro-fast`
* `viduq3-ad`
* `viduq3-drama`
* `viduq3-mix`

**prompt** `string` *required*

Промпт.

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

**image\_urls** `string[]`

Список URL референсных изображений.

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

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

* `input_reference`
* `reference_images`
* `images`
* `image`

**url** `string`

URL референсного видео.

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

**video\_list** `array`

Список референсных видео.

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

* `video_url`
* `refer_type` (опционально)
* `keep_original_sound` (опционально)

**duration** `integer` (default: 5)

Длительность видео в секундах. По умолчанию `5`.

**resolution** `string` (default: 720P)

Разрешение, поддерживаются `720P` и `1080P`.

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

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

**audio** `boolean`

Генерировать ли аудио.

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

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

**watermark** `boolean` (default: false)

Добавлять ли водяной знак.

**seed** `integer`

Зерно генерации.

**metadata** `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 обычно сразу завершается ошибкой.

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

### 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.