> ## 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 Q4 Preview 视频生成

> 使用 Vidu Q4 Preview 模型生成视频，支持图生视频和多参考图生成，参考模式可挂参考音频

> [!NOTE]
>
> **国内用户请注意：** 中国大陆用户请使用 `https://toapis.cn` 作为接口地址（Base URL）。文档示例中的 `https://toapis.com` 请替换为 `https://toapis.cn`。

* 异步任务接口，提交后返回任务 ID
* 支持模型：`viduq4-preview`
* 两种生成模式：
  * **首帧图生视频**：单张图片作为首帧
  * **参考生视频**：多张参考图，可附加参考音频

> [!WARNING]
>
> 请传入公网可访问的图片和音频 URL。不要在 `image_urls`、`reference_images` 或 `sounds` 中直接传 base64 数据；本地文件请先使用 [上传图片接口](https://docs.toapis.com/docs/cn/api-reference/uploads/images.md) 获取 URL。

## 认证

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 认证。

```
Authorization: Bearer YOUR_API_KEY
```

## 请求参数

**model** `string` *required*

模型名称，固定为 `viduq4-preview`。

**prompt** `string` *required*

视频提示词，描述主体、动作、场景、镜头和风格。

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

图片 URL 数组。生成模式由 `video_generation_mode` 和图片数量决定：

* **首帧模式**（默认）：在 `image_urls` 中传入恰好 1 张图片 URL，图片作为首帧。
* **参考模式**：将 `video_generation_mode` 设为 `reference_images_to_video`，在 `image_urls`（或 `reference_images`）中传入参考图。

示例：`["https://example.com/first-frame.jpg"]`

**video\_generation\_mode** `string`

生成模式选择器。

可选值：

* `reference_images_to_video` - 多参考图生成，`image_urls` 中的多张图片按参考图处理

省略时为首帧图生视频。传入多张图片、`reference_images` 或 `sounds` 的请求会自动路由到参考生视频。

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

视频时长（秒），`3` 到 `16`。

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

视频分辨率。

可选值：

* `540p`
* `720p`
* `1080p`
* `2K`
* `4K`

**aspect\_ratio** `string`

视频宽高比，用于参考模式。

可选值：`16:9`、`9:16`、`4:3`、`3:4`、`1:1`

**audio** `boolean` (default: true)

是否为视频生成音频。

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

是否在生成的视频上添加水印。

**seed** `integer`

随机种子，相同参数下可获得更可复现的结果。

**metadata** `object`

扩展参数，用于传递上游 API 支持但未暴露为顶层字段的参数。

**展开 metadata 字段**

**is\_rec** `boolean`

是否自动扩写优化提示词。省略时上游默认为 `true`。

**sounds** `string[]`

参考音频 URL 数组（仅参考生视频模式），最多 3 个音频文件。

示例：`["https://example.com/voice.mp3"]`

**wm\_position** `integer`

水印位置，`1` 到 `4`。当 `watermark` 为 `true` 时生效。

**wm\_url** `string`

自定义水印图片 URL。当 `watermark` 为 `true` 时生效。

**meta\_data** `string`

自定义元数据标识，JSON 格式字符串，原样透传到结果中。

**callback\_url** `string`

ToAPIs 任务最终 Webhook。需先配置 Token URL 和签名密钥，详见 [任务 Webhooks](https://docs.toapis.com/docs/cn/api-reference/webhooks/task-webhooks.md)。

## 模式选择

| 模式 | 触发方式 | 图片输入 | 音频输入 |
| - | - | - | - |
| 首帧图生视频 | `image_urls` 传 1 张图（默认） | 恰好 1 张 | 仅 `audio` 开关 |
| 参考生视频 | `video_generation_mode: "reference_images_to_video"`，或多图 / `reference_images` / `sounds` | 最多 15 张参考图 | 最多 3 条 `sounds` + `audio` 开关 |

## 计费维度

Vidu Q4 Preview 按生成视频秒数计费，按分辨率分档定价：

* `540p` / `720p` / `1080p` / `2K` / `4K` - 分辨率越高单价越高

## 响应

**id** `string`

任务 ID，用于查询任务状态。

**object** `string`

对象类型，通常为 `generation.task`。

**model** `string`

请求使用的模型。

**status** `string`

任务状态：`queued`、`in_progress`、`completed` 或 `failed`。

**created\_at** `integer`

任务创建时间戳。

## 示例

### 首帧图生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "1080p",
  "audio": true
}
```

### 参考生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "保持参考图中的人物一致，夜晚霓虹城市街道上行走",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "3:4",
  "audio": true
}
```

### 带参考音频的参考生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "人物说出台词，口型与声音同步",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": ["https://example.com/character.jpg"],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "metadata": {
    "sounds": ["https://example.com/voice.mp3"]
  }
}
```

### 提示词扩写与水印

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "一只猫在夕阳下的沙滩上行走",
  "image_urls": ["https://example.com/cat.jpg"],
  "duration": 8,
  "resolution": "2K",
  "watermark": true,
  "metadata": {
    "is_rec": true
  }
}
```

> [!NOTE]
>
> 视频生成为异步任务。使用 [获取视频任务状态](https://docs.toapis.com/docs/cn/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": "viduq4-preview",
    "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
    "image_urls": ["https://example.com/portrait.jpg"],
    "duration": 5,
    "resolution": "1080p",
    "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": "viduq4-preview",
        "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
        "image_urls": ["https://example.com/portrait.jpg"],
        "duration": 5,
        "resolution": "1080p",
        "audio": True,
    },
)

print(response.json())
```

```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: "viduq4-preview",
    prompt: "图片中的人物缓缓转身微笑，电影质感打光",
    image_urls: ["https://example.com/portrait.jpg"],
    duration: 5,
    resolution: "1080p",
    audio: true
  })
});

console.log(await response.json());
```


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