文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯混元生视频>API 文档>第三方生视频相关接口>提交Vidu参考生视频任务

提交Vidu参考生视频任务

最近更新时间：2026-04-16 02:41:48

我的收藏

本页目录：

1. 接口描述

接口请求域名： vclm.tencentcloudapi.com 。

提交Vidu参考生视频任务接口

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：SubmitReferenceToVideoViduJob。
Version 是 String 公共参数，本接口取值：2024-05-23。
Region 是 String 公共参数，详见产品支持的 地域列表。
Prompt 是 String

文本提示词
生成视频的文本描述。
注1：字符长度不能超过 2000 个字符
注2：使用Subjects主体参数时，可以通过@主体id 来表示主体内容，例如："@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。"


示例值：圣诞老人与熊在湖边相拥。
Images.N 否 Array of String

图像参考
【非主体调用时传入】
支持上传1～7张图片，模型将以此参数中传入的图片中的主题为参考生成具备主体一致的视频。
支持传入图片 Base64 编码或图片URL（确保可访问）
图片支持 png、jpeg、jpg、webp格式
图片像素不能小于 128128，且比例需要小于1:4或者4:1，且大小不超过50M。


示例值：["https://**.jpg"]
Subjects.N 否 Array of ReferenceSubject

参考生图主体信息，支持1-7个主体，主体图片共1 ～ 7张
【主体调用时传入】
Videos.N 否 Array of String

视频参考支持上传1～2个视频，模型将以此参数中传入的视频作为参考，生成具备主体一致的视频。
注1： 仅viduq2-pro模型支持该参数
注2：使用视频参考功能时，最多支持上传 1个8秒 视频 或 2个5秒 视频
注3：视频支持 mp4、avi、mov格式
注4：视频像素不能小于 128128，且比例需要小于1:4或者4:1，且大小不超过100M。


示例值：["https://**.mp4"]
Model 否 String

模型名称，可选值，当前仅可并且默认viduq2

  • viduq2：最新模型

示例值：viduq2
Audio 否 Boolean

是否使用音视频直出能力，默认false，可选值 true、false

  • true：使用音视频直出能力。
  • false：不使用音视频直出能力。
    仅上传主体时支持此功能

示例值：false
AudioType 否 String

音频类型，audio为true时必填，默认为all

枚举值：

  • all： 音效+人声
  • speech_only： 仅人声
  • sound_effect_only： 仅音效

示例值：all
Bgm 否 Boolean

是否为生成的视频添加背景音乐。
默认：false，可选值 true 、false
【仅支持非主体调用时生效】

  • 传 true 时系统将从预设 BGM 库中自动挑选合适的音乐并添加；不传或为 false 则不添加 BGM。
  • BGM不限制时长，系统根据视频时长自动适配
  • BGM参数在q2系列模型的duration为 9秒 或 10秒 时不生效

示例值：true
Duration 否 Integer

视频时长参数：
默认5秒，可选：1-10（整数）


示例值：5
AspectRatio 否 String

比例
默认值：16:9
【非主体调用时】
可选值如下：16:9、9:16、4:3、3:4、1:1

【主体调用时】
可选值如下：16:9、9:16、1:1
注：q2模型 支持任意宽高比


示例值：16:9
Resolution 否 String

分辨率参数
默认 720p, 可选：540p、720p、1080p


示例值：720p
MovementAmplitude 否 String

运动幅度默认 auto，可选值：auto、small、medium、large
注：使用q2系列模型时该参数不生效


示例值：auto
MetaData 否 String

元数据标识，json格式字符串，透传字段，您可以 自定义格式 或使用 示例格式 ，示例如下：
{
"Label": "your_label","ContentProducer": "yourcontentproducer","ContentPropagator": "your_content_propagator","ProduceID": "yourproductid", "PropagateID": "your_propagate_id","ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2"
}
该参数为空时，默认使用vidu生成的元数据标识


示例值：string
CallbackUrl 否 String

Callback 协议
需要您在创建任务时主动设置 callback_url，请求方法为 POST，当视频生成完成时，将向此地址发送包含任务最新状态的回调请求。回调请求内容结构与查询任务API的返回体一致
回调返回的"status"包括以下状态：

  • success 任务完成（如发送失败，回调三次）
  • failed 任务失败（如发送失败，回调三次）

示例值：string
Payload 否 String

透传参数不做任何处理，仅数据传输注：最多 1048576个字符


示例值：string
OffPeak 否 Boolean

错峰模式，默认为：false，可选值：

  • true：错峰生成视频；
  • false：即时生成视频；
    注1：错峰模式消耗的积分更低
    注2：错峰模式下提交的任务，会在48小时内生成，未能完成的任务会被自动取消，并返还该任务的积分

示例值：true
LogoAdd 否 Integer

为生成结果图添加显式水印标识的开关，默认为1。
1：添加。
0：不添加。
其他数值：默认按1处理。
建议您使用显著标识来提示结果图使用了 AI 绘画技术，是 AI 生成的图片。
示例值：1


示例值：1
LogoParam 否 LogoParam

标识内容设置。
默认在生成结果图右下角添加“图片由 AI 生成”字样，您可根据自身需要替换为其他的标识图片。

3. 输出参数

参数名称 类型 描述
JobId String

任务ID。


示例值：1305546906952867840
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 调用示例

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitReferenceToVideoViduJob
<公共请求参数>

{
    "Images": [
        "https://cos.ap-guangzhou.myqcloud.com/xxx.png"
    ],
    "Prompt": "圣诞老人与熊在湖边相拥。"
}

输出示例

{
    "Response": {
        "JobId": "1384475658808836096",
        "RequestId": "3ca4a3d1-28c7-4be5-a394-5902c97dcca4"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

该接口暂无业务逻辑相关的错误码，其他错误码详见 公共错误码。

中国站