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

# Vidu Q4 参考生视频

> Vidu Q4 参考生视频 API 根据 1–12 张参考图和最多 3 段参考音频生成 3–16 秒的视频，可选原生音频，分辨率最高 4K。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

Vidu Q4 参考生视频根据最多 12 张参考图（角色、产品、服装、场景）和最多 3 段人声片段生成 3–16 秒的视频，可选原生音频，输出最高 4K。适合短剧中反复出现的角色、组合产品、模特与场景的广告，以及配音角色短片。

Vidu Q4 是生数科技（ShengShu Technology）的视频模型，上游于 2026 年 10 月以 Vidu Q4 Preview 发布。它没有文生视频模式，每个请求都从图片开始。Vidgo 提供两个 model ID：[图生视频](https://docs.vidgo.ai/zh/api-manual/video-series/vidu-q4-image-to-video.md)和[参考生视频](https://docs.vidgo.ai/zh/api-manual/video-series/vidu-q4-reference-to-video.md)。

## 模型

* **vidu/q4/reference-to-video** — Vidu Q4 参考生视频，使用 1–12 张参考图和最多 3 段音色参考，3–16 秒，540p 到 4K。

## 功能

* 一次请求支持 1–12 张参考图的参考生视频。
* 通过 `reference_audio_urls` 提供最多 3 段音色参考。
* 用提示词标签 `[@reference_image_N]` 和 `[@reference_audio_N]` 指明每个参考素材的用途。
* 通过 `generate_audio` 可选生成原生音频。
* 五种宽高比，五种分辨率（`540p` 到 `4k`）。
* 时长为 3 到 16 秒的整数。

## 必填参数

* `prompt`（string）：场景以及每个参考素材的用法。不能为空白，最多 5,000 个字符。
* `reference_image_urls`（string\[]）：1–12 个公开 HTTP(S) 图片 URL。

## 可选参数

* `reference_audio_urls`（string\[]）：最多 3 个公开 HTTP(S) 音频 URL，作为音色参考。简短、干净的 MP3 人声片段效果最好。
* `aspect_ratio`（string）：`16:9`、`9:16`、`4:3`、`3:4` 或 `1:1`。省略时使用上游默认值（16:9）。
* `generate_audio`（boolean）：随视频生成原生音频。省略时不生成音频。
* `duration`（integer）：输出时长，`3`–`16` 秒。默认 `5`。
* `resolution`（string）：`540p`、`720p`、`1080p`、`2k` 或 `4k`（不区分大小写）。默认 `720p`。
* `enable_safety_checker`（boolean）：开启或关闭上游安全检查。

## 分辨率

| `resolution` | 适用场景 |
| - | - |
| `540p` | 快速、低成本的草稿 |
| `720p` | 默认；社交平台和网页短片 |
| `1080p` | 全高清交付 |
| `2k` | 高分辨率母版 |
| `4k` | 主视觉镜头和大屏 |

分辨率决定每秒的计费档位。

## 输出

任务完成后，[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)和回调内容的 `files` 数组中会返回一个 MP4 视频。

## 示例

* **两张参考图，720p**：模特和运动鞋分别以 `[@reference_image_1]`、`[@reference_image_2]` 引用，竖屏 `9:16`。
* **角色加音色参考与音频，1080p**：一个角色和一个场景，一段人声以 `[@reference_audio_1]` 引用，带引号的对白，`generate_audio: true`，并提供 `callback_url`。

## 注意事项

* 参考素材按数组顺序编号：`reference_image_urls` 的第一个 URL 是 `[@reference_image_1]`，`reference_audio_urls` 的第一个 URL 是 `[@reference_audio_1]`。
* 本 ID 不接受 `image_urls`，传入会返回 400。要让单张起始帧动起来，请用 [Vidu Q4 图生视频](https://docs.vidgo.ai/zh/api-manual/video-series/vidu-q4-image-to-video.md)。Vidu Q4 没有文生视频模式。
* 参考图超过 12 张或参考音频超过 3 段会返回 400。
* `model` 和 `callback_url` 放在请求根级，不要放进 `input`。
* 积分在提交时预扣，按 `resolution` 和 `duration`（每输出秒）计算。参考图、参考音频和 `generate_audio` 不影响费率。任务失败会全额退还。当前费率见[定价页](https://vidgo.ai/apis/api-pricing)。


## OpenAPI

````yaml zh/api-manual/video-series/vidu-q4-reference-to-video.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Vidu Q4 参考生视频
  description: Vidu Q4 参考生视频 API 根据 1–12 张参考图和最多 3 段参考音频生成 3–16 秒的视频，可选原生音频，分辨率最高 4K。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Video Series
      summary: Vidu Q4 参考生视频
      description: >-
        只传本模型列出的 `input` 字段。其他字段（包括 `image_urls`）都会返回 400。参考素材 URL 必须是公开的
        HTTP(S) 地址，且不能内嵌凭证。
      operationId: submit_vidu_q4_reference_to_video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: 模型 ID，填 `vidu/q4/reference-to-video`。
                  example: vidu/q4/reference-to-video
                callback_url:
                  type: string
                  format: uri
                  nullable: true
                  description: >-
                    可选的公开 HTTP(S) 地址，任务变为 `finished` 或 `failed` 时会收到 POST
                    请求。建议使用 HTTPS。省略、传 `null` 或空字符串即不发送回调。
                  example: https://your-domain.com/callback
                input:
                  type: object
                  required:
                    - prompt
                    - reference_image_urls
                  properties:
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 5000
                      example: >-
                        [@reference_image_1] walks into the cafe from
                        [@reference_image_2] and greets the barista, speaking in
                        the voice of [@reference_audio_1]
                      description: >-
                        描述场景以及如何使用参考素材。按数组顺序用
                        `[@reference_image_1]`、`[@reference_audio_1]`
                        等引用。不能为空白，最多 5,000 个字符。
                    reference_image_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      minItems: 1
                      maxItems: 12
                      example:
                        - https://example.com/character.png
                        - https://example.com/cafe.png
                      description: 1–12 个公开 HTTP(S) 参考图 URL：角色、产品、服装或场景。
                    reference_audio_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      maxItems: 3
                      example:
                        - https://example.com/voice.mp3
                      description: 最多 3 个公开 HTTP(S) 音频 URL，作为音色参考。简短、干净的 MP3 人声片段效果最好。
                    duration:
                      type: integer
                      minimum: 3
                      maximum: 16
                      default: 5
                      description: 输出时长，单位秒（整数，也接受 `"5"` 这样的整数字符串）。
                    resolution:
                      type: string
                      enum:
                        - 540p
                        - 720p
                        - 1080p
                        - 2k
                        - 4k
                      default: 720p
                      description: 输出分辨率（不区分大小写），决定计费档位。
                    aspect_ratio:
                      type: string
                      enum:
                        - '16:9'
                        - '9:16'
                        - '4:3'
                        - '3:4'
                        - '1:1'
                      description: 输出宽高比。省略时使用上游默认值（16:9）。
                    generate_audio:
                      type: boolean
                      description: 随视频生成原生音频。省略时使用上游默认值（不生成音频）。不影响价格。
                    enable_safety_checker:
                      type: boolean
                      description: 开启或关闭上游安全检查。省略时使用上游默认值。
                  additionalProperties: false
                  description: 生成参数。
            examples:
              images_only:
                summary: 两张参考图，720p
                value:
                  model: vidu/q4/reference-to-video
                  input:
                    prompt: >-
                      [@reference_image_1] holds up the sneaker from
                      [@reference_image_2] and spins it slowly under studio
                      light
                    reference_image_urls:
                      - https://example.com/model.png
                      - https://example.com/sneaker.png
                    duration: 5
                    resolution: 720p
                    aspect_ratio: '9:16'
              voice_reference:
                summary: 角色加音色参考与音频，1080p
                value:
                  model: vidu/q4/reference-to-video
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      [@reference_image_1] walks into the cafe from
                      [@reference_image_2] and greets the barista, speaking in
                      the voice of [@reference_audio_1]: "Morning! The usual,
                      please."
                    reference_image_urls:
                      - https://example.com/character.png
                      - https://example.com/cafe.png
                    reference_audio_urls:
                      - https://example.com/voice.mp3
                    duration: 8
                    resolution: 1080p
                    aspect_ratio: '16:9'
                    generate_audio: true
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                    description: HTTP 状态码。
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                        description: >-
                          任务
                          ID，用于[查询任务状态](/zh/api-manual/task-management/status)。
                      status:
                        type: string
                        enum:
                          - not_started
                        description: 任务的初始状态。
                      created_time:
                        type: string
                        format: date-time
                        description: 任务创建时间（ISO 8601）。
              example:
                code: 200
                data:
                  task_id: task-unified-1762160000-abc123
                  status: not_started
                  created_time: '2026-11-03T10:30:00'
        '400':
          description: 输入无效、字段不受支持、媒体无法访问或积分不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '401':
          description: 凭证无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '408':
          description: 请求超时
          content:
            text/plain:
              schema:
                type: string
              example: Request timeout
        '422':
          description: JSON 无效或请求体不是对象
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '429':
          description: 超出速率限制或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '502':
          description: 无法创建上游生成任务
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '503':
          description: 所请求的模型暂时不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取你的 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

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