# Vidu Q3

> 通过 UniAI 调用 Vidu Q3 系列，创建文生、单图、首尾帧和多参考图视频。

Canonical URL: https://docs.uniai.tv/models/video/vidu
Locale: zh-CN

本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。

更新时间：2026-08-04

## 概览

Vidu Q3 系列只使用两个稳定公共模型名，通过请求体顶层的 `resolution` 参数选择输出分辨率，不再把分辨率写进模型名。

| 公共模型 | 系列 | 文生视频 | 单图生视频 | 首尾帧 | 多参考图 |
| --- | --- | --- | --- | --- | --- |
| `viduq3p` | Q3 Pro | 支持 | 支持 | 支持 | 支持 1 至 4 张 |
| `viduq3t` | Q3 Turbo | 支持 | 支持 | 支持 | 支持 1 至 4 张 |

两个模型均支持 `540p`、`720p` 和 `1080p`，这两个 ID 是 Vidu Q3 对外唯一保留的公共模型名。

## 适用场景

Vidu Q3 适合以下任务：

- 根据文字提示词生成视频；
- 让一张可公开访问的图片动起来；
- 根据首帧和尾帧生成连续视频；
- 使用 1 至 4 张参考图约束人物、主体或视觉风格。

客户端只需选择公共模型并传入请求参数。不要传入渠道名、上游模型名、上游任务字段或路由控制参数。

## 接口

新接入统一使用以下接口：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |

以下兼容接口仍可使用：

| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos/generations` |
| 查询视频任务 | `GET` | `/v1/videos/generations/{task_id}` |
| 创建视频任务 | `POST` | `/v1/video/generations` |
| 查询视频任务 | `GET` | `/v1/video/generations/{task_id}` |

新接入建议统一使用 `/v1/videos`。

## 鉴权

所有请求均使用 UniAI Bearer Token：

```http
Authorization: Bearer sk-***
```

创建任务时还需发送：

```http
Content-Type: application/json
```

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `viduq3p` 或 `viduq3t`。 |
| `prompt` | string | 是 | 视频生成提示词。 |
| `duration` | integer | 是 | 输出时长，范围为 `1` 至 `16` 秒。 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16`、`3:4`、`4:3` 或 `1:1`。 |
| `image` | string | 条件必填 | 单图模式的输入图或首尾帧模式的首帧，必须是公开可访问的 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL，必须与 `image` 一起传入。 |
| `reference_image_urls` | string[] | 条件必填 | 多参考图模式的 1 至 4 个公开 HTTP(S) 图片 URL。 |
| `resolution` | string | 是 | `540p`、`720p` 或 `1080p`。 |
| `audio` | boolean | 否 | 是否生成声音。 |
| `bgm` | boolean | 否 | 文生视频的背景音乐控制。 |
| `seed` | integer | 否 | 随机种子。 |

根据生成模式选择输入字段：

| 模式 | 输入字段 |
| --- | --- |
| 文生视频 | `prompt` |
| 单图生视频 | `prompt` + `image` |
| 首尾帧生视频 | `prompt` + `image` + `last_image` |
| 多参考图生视频 | `prompt` + `reference_image_urls` |

字段约束：

- 每次请求都必须传入顶层 `resolution`。
- `image` 与 `reference_image_urls` 不能同时传入。
- `last_image` 不能单独使用，必须与 `image` 组成首尾帧。
- 首尾帧和多参考图模式不要使用 `images` 或 `image_urls`。
- `resolution`、`audio`、`bgm` 和 `seed` 都直接放在请求体顶层，不要包在 `extra_body` 中。
- `size` 不是 `resolution` 的兼容别名。

## 请求示例

### 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "bgm": false,
    "seed": 42
  }'
```

### 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3t",
    "prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.",
    "image": "https://example.com/source.png",
    "duration": 5,
    "aspect_ratio": "9:16",
    "resolution": "540p",
    "audio": false,
    "seed": 42
  }'
```

### 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.",
    "image": "https://example.com/head.png",
    "last_image": "https://example.com/tail.png",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": false,
    "seed": 42
  }'
```

### 多参考图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3p",
    "prompt": "A @Image1 walking through a beach in the visual style of @Image2",
    "reference_image_urls": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png"
    ],
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": false,
    "seed": 42
  }'
```

两个公共模型都支持 `reference_image_urls`。参考图提示词可以按数组顺序使用 `@Image1`、`@Image2` 等标记。

## 响应示例

### 任务创建成功

请保存 `id` 或兼容字段 `task_id`，用于后续查询：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "viduq3p",
  "status": "queued",
  "progress": 0,
  "created_at": 1785772800
}
```

公共响应不会返回渠道标识、上游任务 ID、凭证信息或上游原始响应。

## 任务状态与结果

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。

## 计费说明

计费取决于公共模型、请求的 `resolution` 和实际输出视频秒数。模型名本身不承载分辨率或时段计费档位。

百度 VOD/BV 渠道当前正常时段的参考消耗如下，适用于文生视频、单图生视频和首尾帧视频：

| 公共模型 | `540p` | `720p` | `1080p` |
| --- | ---: | ---: | ---: |
| `viduq3p`（Q3 Pro） | 0.28125 元/秒 | 0.625 元/秒 | 0.75 元/秒 |
| `viduq3t`（Q3 Turbo） | 0.21875 元/秒 | 0.375 元/秒 | 0.40625 元/秒 |

渠道消耗 = 单价 × 实际输出时长。多参考图请求可能选择其他符合条件的渠道，不能直接套用这张百度 VOD 表。最终对外价格和结算以 UniAI 模型页及消费日志为准。

## 常见错误

以下情况会在任务创建前被拒绝：

- 使用 `viduq3p` 或 `viduq3t` 之外的模型名；
- 缺少 `resolution`，或传入 `540p`、`720p`、`1080p` 以外的值；
- 使用 `size` 代替 `resolution`；
- 缺少 `duration`，或传入 `1` 至 `16` 之外的值；
- 使用 `21:9`、`1920x1080` 等不支持的画幅比例；
- `reference_image_urls` 为空或超过 4 张；
- 同时传入 `image` 与 `reference_image_urls`，或单独传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 把支持的顶层参数放进 `extra_body`。

## 相关页面

- [视频生成概览](/models/video/overview)
- [模型列表](/models)