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

* Асинхронный режим обработки, возвращает ID задачи для последующих запросов
* Поддерживаемые модели: `viduq3-pro`, `viduq3-turbo`, `viduq3`
* `viduq3-pro`: Высокое качество, синхронизация аудио-видео, генерация раскадровки
* `viduq3-turbo`: Быстрая генерация, интеллектуальное переключение сцен, лучшая экономичность
* `viduq3`: Лучшая мультиракурсная согласованность, мульти-референс генерация

> [!WARNING]
>
> Используйте общедоступные URL изображений. Не передавайте base64 данные в `image_urls`; загрузите локальные изображения через [API загрузки изображений](https://docs.toapis.com/docs/ru/api-reference/uploads/images.md).

## Авторизация

**Authorization** `string` *required*

Все конечные точки API требуют аутентификации с помощью Bearer Token.

```
Authorization: Bearer YOUR_API_KEY
```

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

**model** `string` *required*

Название модели Vidu Q3.

Варианты:

* `viduq3-pro` - высокое качество, синхронизация аудио-видео
* `viduq3-turbo` - самая быстрая генерация, интеллектуальное переключение сцен
* `viduq3` - лучшая мультиракурсная согласованность, мульти-референс/субъекты

**prompt** `string` *required*

Текстовый промпт, максимум **5000 символов**.

Описывает субъект, действие, сцену, камеру и стиль. В режиме subjects используйте `@name` для ссылки на субъекты.

Пример: `"Кот играет на пианино, камера медленно приближается, кинематографическое качество"`

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

Длительность видео (секунды).

* `viduq3-pro` / `viduq3-turbo`: `1` до `16`
* `viduq3`: `3` до `16`

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

Разрешение видео.

Варианты:

* `540p`
* `720p`
* `1080p`

**aspect\_ratio** `string`

Соотношение сторон видео.

Распространённые значения: `16:9`, `9:16`, `1:1`

Модели Q3 поддерживают произвольное соотношение сторон. При предоставлении `image_urls` соотношение обычно определяется по референсному изображению.

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

Массив URL референсных изображений.

* `viduq3-pro` / `viduq3-turbo`
  * Не предоставлено: текст-в-видео
  * 1 изображение: изображение-в-видео, используется как начальный кадр
  * 2 изображения: первый-последний кадр
* `viduq3`
  * Обязательно, до 7 референсных изображений

Пример: `["https://example.com/reference.jpg"]`

**audio** `boolean`

Включить аудио-видео выход.

* Все модели Q3: по умолчанию `true`

При `true` система генерирует речь и звуковые эффекты на основе промпта.

**seed** `integer`

Случайное зерно для воспроизводимых результатов.

**metadata** `object`

Расширенные параметры для полей upstream API, не представленных как основные.

**Показать поля metadata**

**subjects** `array`

Список субъектов (режим Subjects, только `viduq3`). Каждый содержит `name` и `images`.

* До 7 субъектов
* До 3 изображений на субъект
* Ссылка через `@name` в промпте

Пример:

```json theme={null}
[
  {"name": "cat", "images": ["https://example.com/cat.jpg"]},
  {"name": "dog", "images": ["https://example.com/dog.jpg"]}
]
```

**auto\_subjects** `boolean`

Использовать интеллектуальную библиотеку сущностей, по умолчанию `false`.

**voice\_id** `string`

ID голоса для указания голосового персонажа в видео.

**audio\_type** `string`

Тип аудио, действует при `audio=true`.

Варианты:

* `all` - звуковые эффекты + речь (по умолчанию)
* `speech_only` - только речь
* `sound-effect_only` - только звуковые эффекты

**off\_peak** `boolean`

Режим пониженной нагрузки, по умолчанию `false`.

* `true`: генерация в непиковое время, меньше кредитов
* Задачи будут выполнены в течение 48 часов; незавершённые автоматически отменяются с возвратом кредитов
* Модели Q3 поддерживают при `audio=true`

**payload** `string`

Прозрачный параметр передачи, максимум 1048576 символов.

**callback\_url** `string`

Финальный Task Webhook ToAPIs. Сначала настройте URL и secret Token; см. [Webhook](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md).

## Выбор модели

| Модель | Сценарий | Изображения | Разрешение | Длительность |
| - | - | - | - | - |
| `viduq3-pro` | Высокое качество текст/изображение/первый-последний кадр | Опционально, до 2 | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3-turbo` | Быстрая генерация текст/изображение/первый-последний кадр | Опционально, до 2 | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3` | Мульти-референс/субъекты генерация | Обязательно, до 7 | `540p` / `720p` / `1080p` | 3-16s |

## Тарификация

Vidu Q3 тарифицируется по модели, разрешению и типу генерации:

* `viduq3-pro`: высокое качество, примерно 2x цены turbo
* `viduq3-turbo`: быстрый, лучшая экономичность
* `viduq3`: мульти-референс генерация

## Ответ

**id** `string`

Уникальный идентификатор задачи.

**object** `string`

Тип объекта, фиксированное значение `generation.task`.

**model** `string`

Название использованной модели.

**status** `string`

Статус задачи: `queued`, `in_progress`, `completed` или `failed`.

**created\_at** `integer`

Unix-временная метка создания задачи.

## Примеры использования

### Текст-в-видео

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "Кот играет на пианино, камера медленно приближается, кинематографическое качество",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}
```

### Изображение-в-видео

```json theme={null}
{
  "model": "viduq3-turbo",
  "prompt": "Человек медленно поворачивается и улыбается",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "720p"
}
```

### Первый-последний кадр

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "Человек постепенно садится из положения стоя",
  "image_urls": [
    "https://example.com/first.jpg",
    "https://example.com/last.jpg"
  ],
  "duration": 8,
  "resolution": "720p"
}
```

### Мульти-референс видео

```json theme={null}
{
  "model": "viduq3",
  "prompt": "Сохраняя персонажа из референсов, прогулка по футуристической улице города",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 6,
  "resolution": "1080p"
}
```

### Режим Subjects

```json theme={null}
{
  "model": "viduq3",
  "prompt": "@cat и @dog бегают в парке, солнечный день",
  "image_urls": ["https://example.com/park-bg.jpg"],
  "duration": 8,
  "resolution": "720p",
  "audio": true,
  "metadata": {
    "subjects": [
      {"name": "cat", "images": ["https://example.com/cat.jpg"]},
      {"name": "dog", "images": ["https://example.com/dog.jpg"]}
    ],
    "audio_type": "all"
  }
}
```

> [!NOTE]
>
> Генерация видео является асинхронной задачей. Используйте [Получить статус видео](https://docs.toapis.com/docs/ru/api-reference/tasks/video-status.md) для запроса прогресса и результатов.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-pro",
    "prompt": "Кот играет на пианино, камера медленно приближается",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio": true
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
    },
    json={
        "model": "viduq3-pro",
        "prompt": "Кот играет на пианино, камера медленно приближается",
        "duration": 8,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "audio": True,
    }
)

task = response.json()
print(f"ID задачи: {task['id']}")
print(f"Статус: {task['status']}")
```

```javascript JavaScript theme={null}
const response = await fetch('https://toapis.com/v1/videos/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'viduq3-pro',
    prompt: 'Кот играет на пианино, камера медленно приближается',
    duration: 8,
    resolution: '1080p',
    aspect_ratio: '16:9',
    audio: true
  })
});

const task = await response.json();
console.log(`ID задачи: ${task.id}`);
console.log(`Статус: ${task.status}`);
```

```json 200 theme={null}
{
  "id": "video_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ",
  "object": "generation.task",
  "model": "viduq3-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380224,
  "metadata": {}
}
```


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