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

# Vidu Q3 系列

> 生数科技 Vidu Q3 — 参考生 / 文生 / 图生,智能镜头切换,1-16 秒任意整数

生数科技 Vidu Q3 系列视频生成模型,**参考生视频(R2V)** 是看家本事 — 接受公网图作为主体 / 风格参考,prompt 负责描述动作与镜头,人物外观由参考图决定,适合 **角色一致性 / 风格延续 / 多机位切换** 三类场景。

**两档可选:**

* **`vidu-q3`** — 标准档,日常默认首选,镜头切换更聪明,540p / 720p / 1080p,1-16 秒。比例由参考图决定,**不接受 `aspect_ratio` 参数**
* **`vidu-q3-mix`** — 混剪档,支持多图混剪生成连贯视频,540p / 720p / 1080p,1-16 秒,支持 `aspect_ratio`,适合短剧分镜重组、广告素材二创

按 **分辨率 × 时长** 计费,**每秒单价**,1-16 秒任意整数。

## 定价

| 模型            | 540p          | 720p          | 1080p         |
| ------------- | ------------- | ------------- | ------------- |
| `vidu-q3`     | `$0.045` / 秒  | `$0.09` / 秒   | `$0.1125` / 秒 |
| `vidu-q3-mix` | `$0.1125` / 秒 | `$0.1125` / 秒 | `$0.135` / 秒  |

实际费用 = 单价 / 秒 × `duration`。例:`vidu-q3` 1080p 5 秒 = `$0.1125 × 5 = $0.5625`。

## 调用示例

<CodeGroup>
  ```bash 文生视频(标准档) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "vidu-q3",
      "prompt": "黄昏的海滩,女孩迎着夕阳奔跑,长发飞扬,电影感光影",
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

  ```bash 图生视频(标准档单图) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "vidu-q3",
      "prompt": "人物缓缓转身,镜头推近",
      "image_urls": ["https://cdn.example.com/portrait.jpg"],
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

  ```bash 多图参考(标准档 R2V) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "vidu-q3",
      "prompt": "保持角色形象,在森林中奔跑,镜头跟随",
      "image_urls": [
        "https://cdn.example.com/char-1.jpg",
        "https://cdn.example.com/style-ref.jpg"
      ],
      "duration": 6,
      "resolution": "1080p"
    }'
  ```

  ```bash 多图混剪(Mix 档) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "vidu-q3-mix",
      "prompt": "镜头在多个场景间平滑切换,氛围连贯",
      "image_urls": [
        "https://cdn.example.com/scene-1.jpg",
        "https://cdn.example.com/scene-2.jpg",
        "https://cdn.example.com/scene-3.jpg"
      ],
      "duration": 8,
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 提交成功 theme={"system"}
  {
    "task_id": "task-wave1775285160b950328499",
    "model": "vidu-q3",
    "action": "generate",
    "status": "queued",
    "created_at": 1775285160040,
    "progress": 0
  }
  ```
</ResponseExample>

提交后用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 轮询状态,详见 [任务系统](/cn/docs/task-system)。

## 可用模型

| 模型 ID         | 分辨率                 | 时长(秒) | Actions  | aspect\_ratio | 备注                |
| ------------- | ------------------- | ----- | -------- | ------------- | ----------------- |
| `vidu-q3`     | 540p / 720p / 1080p | 1-16  | generate | 不支持           | 标准档,日常首选,比例由参考图决定 |
| `vidu-q3-mix` | 540p / 720p / 1080p | 1-16  | generate | 支持            | 混剪档,多素材连贯生成       |

## 通用参数

<ParamField body="model" type="string" required>
  模型 ID,可选值:

  * `vidu-q3`
  * `vidu-q3-mix`
</ParamField>

<ParamField body="action" type="string" default="generate">
  操作类型,固定为 `generate`。传入 `image_urls` 即自动走 **参考生 / 图生视频**,否则为文生视频
</ParamField>

<ParamField body="prompt" type="string" required>
  视频描述文本,建议描述 **动作 / 镜头 / 氛围**,人物外观由 `image_urls` 决定
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  输出分辨率,可选值:

  * `540p`
  * `720p`
  * `1080p`
</ParamField>

<ParamField body="duration" type="integer" default="5">
  视频时长(秒),范围 **1-16** 任意整数
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL 数组,作为主体 / 风格参考(R2V),或作为首帧 / 混剪素材
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook 回调地址,任务终态时调用。详见 [回调机制](/cn/docs/sync-async#异步任务-webhook)
</ParamField>

<ParamField body="callback_events" type="string[]">
  订阅的回调事件,默认订阅终态(`succeeded` / `failed` / `cancelled`)
</ParamField>

## 模型特定参数

<Tabs>
  <Tab title="vidu-q3">
    标准档无特定参数,所有可选项在 [通用参数](#通用参数) 中。

    <Note>
      `vidu-q3` **不接受 `aspect_ratio` 参数**,输出比例由参考图 / 模型决定。若需指定比例请用 `vidu-q3-mix`。
    </Note>
  </Tab>

  <Tab title="vidu-q3-mix">
    <ParamField body="aspect_ratio" type="string" default="16:9">
      画面宽高比(仅 Mix 档支持),可选值:

      * `16:9` — 横版宽屏
      * `9:16` — 竖版长屏
      * `1:1` — 正方形
    </ParamField>

    Mix 档支持多张参考图混剪,系统会智能转场,适合短剧分镜重组、广告素材二创。
  </Tab>
</Tabs>

## 资源限制

| 项目                 | 限制                        |
| ------------------ | ------------------------- |
| 参考图片(`image_urls`) | JPG / PNG / WEBP,需公网可下载链接 |
| Prompt 长度          | 建议 ≤ 2000 字符              |
| 视频时长               | 1-16 秒任意整数                |
| 输出                 | MP4,链接 24 小时有效            |

## 相关文档

* [任务系统详解](/cn/docs/task-system) — 任务状态机 / 轮询节奏 / 异步推送
* [请求响应格式](/cn/docs/request-response) — 通用错误码 / Headers / 限流
* [认证](/cn/docs/authentication) — API Key 申请与使用