Vega Video HOT
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Vega Video 是 WAND 自研的视频生成模型,支持文生视频、首帧 / 尾帧 / 首尾帧生成,以及图片、视频、音频混合输入的多模态参考生成,并可同时生成音频。Pro 系列另支持基于参考视频的编辑与延长,输出最高 4K、单条最长 30 秒。1.5-pro 另支持两步式 Draft 样片:先出 480P 样片校验效果,再基于样片任务生成成片。
选择版本
接口文档按版本拆分,点击卡片查看对应版本的输入规格、请求参数、请求示例与特殊设置。
1.5-pro- 720P~4K,单条 4~30 秒
- 参考图最多 30 张,视频 / 音频各 10 个
- 支持参考视频编辑与延长
- 两步式 Draft 样片(480P → 成片)
1.5-lite- 480P~4K,单条 2~30 秒或智能时长
- 参考图最多 10 张,视频 / 音频各 5 段
- 支持音画同生与多模态参考
1.0-pro · 1.0-pro-fast · 1.0-pro-mini- 480P~4K,单条 4~15 秒
- 参考图最多 9 张,视频 / 音频各 3 个
- 标准、快速与 Mini 三种版本
1.0-lite- 480P~4K,单条 4~15 秒
- 图片 / 视频 / 音频合计最多 12 个
- 快速模式与电影质感模式
基本信息
| 项目 | 值 |
|---|---|
| ModelName | wand-vega-video |
| ModelVersion | 1.5-pro / 1.5-lite / 1.0-pro / 1.0-pro-fast / 1.0-pro-mini / 1.0-lite |
| 输入模式 | 文本 / 首帧/尾帧 / 图片 / 视频 / 音频参考 |
| 输出声音 | 支持(AudioGeneration: Enabled) |
| 真人素材参考 | 仅 Pro 版本,需先注册为素材(asset://),见真人素材接入 |
| 护栏解除支持 | 支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
1.5-pro | 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~30 秒 |
1.5-lite | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 2~30 秒 / -1 智能时长 |
1.0-pro / 1.0-pro-fast / 1.0-pro-mini | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~15 秒 |
1.0-lite | 480P / 768P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~15 秒 |
六个 ModelVersion 值共用 CreateAigcVideoTask 接口与 ModelName: wand-vega-video;三个 1.0 Pro 变体共用同一规格页。
接入准备
使用前须知
Vega Video Pro 系列需开通白名单后才能调用。请联系 WAND 团队,提供您的 APPID 与 UIN。
| 步骤 | 国内站 | 国际站 |
|---|---|---|
| 开通云点播(VOD) | VOD 控制台 | VOD 控制台 |
| 获取 SecretId / SecretKey | API 密钥管理 | API 密钥管理 |
获取 SubAppId | 开通 VOD 后会自动创建默认应用,也可另建应用,见应用体系 | 同左,见应用体系 |
| API 域名 | vod.tencentcloudapi.com | vod.intl.tencentcloudapi.com |
本页示例中的请求体在两个站点通用,切换站点时只需更换域名。
接入场景
参考图中出现真人人脸时,受肖像权与版权约束,平台通过**素材(asset)**机制处理:先用 CreateAigcMaterial 把文件 URL 注册为素材,拿到 AssetId 后,在生视频请求的 FileInfos.N.Url 中以 asset://<AssetId> 引用,不能直接传原始 URL。直接传入含真人人脸的 URL 会被拒绝,报错见常见报错。
| 场景 | 适用范围 | 调用链 | 参考章节 |
|---|---|---|---|
| ① 现实真人素材 | 国内站的现实真人 | 发起活体认证 → 查询认证结果 → 创建真人素材 → 查询素材结果 → 创建生视频任务 → 查询任务结果 | 真人素材接入 |
| ② 非现实真人素材 | 国内站的非真人 / 虚拟人;国内站已开白免活体认证的真人;国际站的全部素材(真人与非真人) | 创建素材 → 查询素材结果 → 创建生视频任务 → 查询任务结果 | 非真人与国际站素材接入 |
| ③ 通用生视频 | 不含人脸的素材,国内站与国际站均适用 | 创建生视频任务 → 查询任务结果 | 各版本接口文档(见上方版本卡片) |
国际站不需要活体认证
国际站没有活体认证接口。无论素材是现实真人、非真人还是虚拟人,国际站都按场景 ② 接入:GroupId 自定义,IsRealPerson 传 "False"。
GroupId 规则
素材必须归属于一个素材组(GroupId)。素材组有两种来源,规则不同:
| 来源 | 适用 | 约束 |
|---|---|---|
活体认证返回的 GroupId | 场景 ①(国内站现实真人) | 与通过认证的人脸一一对应,只接受该人脸的素材。传入其他人脸会报 Face consistency verification failed. |
自定义 GroupId | 场景 ② | 创建素材时 IsRealPerson 传 "False"。首次使用的 GroupId 会自动建组,也可先调用 CreateAigcMaterialGroup 建组 |
版本支持
asset:// 素材引用仅 Pro 版本支持:1.5-pro、1.0-pro、1.0-pro-fast、1.0-pro-mini。Lite 版本(1.5-lite、1.0-lite)不支持。
批量与短剧场景建议
- 素材是否含人脸往往难以可靠判断,建议每个素材都先注册再引用,不要逐张判断后再决定走哪条路径。
- 同一人物会在多个任务中反复出现,建议缓存
AssetId并复用,无需每次重新注册。
主要接口
| 接口 | 用途 | 国内站文档 | 国际站文档 |
|---|---|---|---|
CreateAigcVideoTask | 创建生视频任务,返回 TaskId | 创建 AIGC 生视频任务 | CreateAigcVideoTask |
CreateAigcLivenessValidate | 发起活体认证 | 见真人素材接入 | 国际站无需调用 |
DescribeAigcLivenessValidateResult | 查询活体认证结果 | 见真人素材接入 | 国际站无需调用 |
CreateAigcMaterial | 创建素材(真人 / 非真人) | 见真人素材接入 | 见非真人与国际站素材接入 |
DescribeTaskDetail | 查询素材创建、生视频等任务的结果 | 查询任务详情 | DescribeTaskDetail |
| 普通回调 | 任务完成后主动推送结果,推荐 | 回调设置 · AigcVideoTask 结构 | Callback Settings |
| 可靠回调 | 主动拉取事件通知,推荐 | 拉取事件通知 | PullEvents |
生视频任务耗时较长,建议优先用回调获取结果,DescribeTaskDetail 轮询作为补充。素材的查询、修改、删除等接口见素材管理接口。
真人素材接入
本节对应场景 ①,仅适用于国内站(域名 vod.tencentcloudapi.com)。下文请求体均为 JSON,公共请求参数(X-TC-Action 等签名头)由 SDK 自动处理。
第一步:发起活体认证
调用 CreateAigcLivenessValidate。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID。2023 年 12 月 25 日起开通点播的客户,访问应用内资源(无论默认应用还是新建应用)时都必须填写。示例值:251007502 |
CallbackUrl | 否 | String | 认证完成后的回调地址,例如 https://example.com/callback |
{
"SubAppId": 123456789,
"CallbackUrl": "https://example.com/callback"
}响应返回 H5Link(活体认证页面)与 LivenessToken(查询凭证):
{
"Response": {
"H5Link": "https://**************",
"LivenessToken": "2*******************************6B",
"RequestId": "76002966-e3f7-4156-a234-8a005046e6b7"
}
}第二步:查询活体认证结果
- 让被认证本人在手机浏览器中打开
H5Link,完成活体认证。 - 认证完成后,用
LivenessToken调用DescribeAigcLivenessValidateResult。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
LivenessToken | 是 | String | 第一步返回的 LivenessToken |
{
"SubAppId": 123456789,
"LivenessToken": "2*******************************6B"
}{
"Response": {
"GroupId": "group-*************",
"LivenessToken": "2*******************************6B",
"Message": "ok",
"Status": "DONE",
"RequestId": "a82*************b38"
}
}Status 为 DONE 表示认证通过。返回的 GroupId 与这张人脸一一对应,下一步创建真人素材时必须使用它。
第三步:创建真人素材
用第二步的 GroupId 调用 CreateAigcMaterial,IsRealPerson 传 "True"。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
FileInfo.Type | 是 | String | 输入类型,取值 Url |
FileInfo.Url | 是 | String | 素材文件的 URL |
AssetType | 是 | String | 素材类型:Image / Video / Audio |
GroupId | 是 | String | 素材组 ID。真人素材必须使用活体认证返回的 GroupId |
AssetName | 否 | String | 素材名称,自定义 |
IsRealPerson | 否 | String | "True":现实真人素材;"False":非现实真人素材(含虚拟人)。注意是字符串,不是布尔值 |
GroupName | 否 | String | 素材组名称,自定义 |
GroupDescription | 否 | String | 素材组描述,自定义 |
SessionId | 否 | String | 会话 ID,用于去重,必须唯一,重复会报错 |
SessionContext | 否 | String | 会话上下文,自定义,回调与任务查询时原样返回 |
TasksPriority | 否 | Integer | 任务优先级,数值越大优先级越高。示例值:10 |
ExtInfo | 否 | String | 拓展参数,保留字段 |
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/person.jpg"
},
"AssetType": "Image",
"GroupId": "group-*************",
"AssetName": "主播A",
"IsRealPerson": "True",
"GroupName": "真人素材组",
"GroupDescription": "主播A 的真人素材",
"SessionId": "session-001",
"SessionContext": "用户A提交的素材",
"TasksPriority": 10
}{
"Response": {
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft",
"RequestId": "5f3537a2-b069-4b07-ab0d-9861f877ee12"
}
}素材创建是异步任务,响应只返回 TaskId,还拿不到 AssetId。
第四步:查询素材创建结果
用第三步的 TaskId 调用 DescribeTaskDetail。
{
"SubAppId": 123456789,
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft"
}结果位于 Response.CreateAigcMaterialTask。Status 为 FINISH 且 ErrCode 为 0 时,Output.AssetId 就是生视频要引用的素材 ID(以下响应已省略为 null 的其他任务字段):
{
"Response": {
"CreateAigcMaterialTask": {
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft",
"Status": "FINISH",
"ErrCode": 0,
"Message": "",
"Progress": 100,
"Input": {
"AssetName": "主播A",
"AssetType": "Image",
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/person.jpg"
},
"GroupId": "group-*************",
"GroupName": "真人素材组",
"IsRealPerson": "True"
},
"Output": {
"AssetId": "asset-********",
"AssetUrl": "https://...",
"GroupId": "group-*************"
}
},
"RequestId": "0e3c78d4-dbd6-4519-a1c6-0adfa06a67ef"
}
}第五步:用真人素材生视频
调用 CreateAigcVideoTask,把 AssetId 写成 asset://<AssetId> 传入 FileInfos.N.Url,Type 仍为 Url。其余参数与普通生视频一致,取值范围以所选版本为准。
| 参数 | 取值 |
|---|---|
ModelName | wand-vega-video |
ModelVersion | 1.5-pro / 1.0-pro / 1.0-pro-fast / 1.0-pro-mini |
FileInfos.N.Url | asset://asset-******** |
FileInfos.N.Category | Image / Video / Audio,与素材的 AssetType 一致 |
FileInfos.N.Usage | Reference / FirstFrame / LastFrame |
OutputConfig.Resolution | 1.5-pro:720P / 1080P / 2K / 4K;1.0-pro 系列:480P / 720P / 1080P / 2K / 4K |
OutputConfig.Duration | 1.5-pro:4~30;1.0-pro 系列:4~15;-1 表示由模型决定 |
OutputConfig.AspectRatio | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive |
OutputConfig.AudioGeneration | Enabled / Disabled |
{
"SubAppId": 123456789,
"ModelName": "wand-vega-video",
"ModelVersion": "1.5-pro",
"Prompt": "主播A 在直播间介绍新品,镜头缓慢推进",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "asset://asset-********"
}
],
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"AudioGeneration": "Enabled"
}
}{
"Response": {
"TaskId": "123456-AigcVideoTask-********45f4ee25t",
"RequestId": "aaa51**********d66c74f1a"
}
}第六步:查询生视频结果
用第五步的 TaskId 调用 DescribeTaskDetail,结果位于 Response.AigcVideoTask.Output.FileInfos;也可以通过回调接收结果,见主要接口。
非真人与国际站素材接入
本节对应场景 ②,适用于:
- 国内站的非真人、虚拟人素材;
- 国内站已开白、免活体认证的真人素材;
- 国际站的全部素材(真人、非真人、虚拟人),国际站域名为
vod.intl.tencentcloudapi.com。
与真人素材接入相比,本场景不需要活体认证,GroupId 自定义,IsRealPerson 一律传 "False"。
第一步:创建素材
调用 CreateAigcMaterial,参数说明同第三步:创建真人素材。
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/character.png"
},
"AssetType": "Image",
"GroupId": "my-character-group",
"AssetName": "角色B",
"IsRealPerson": "False",
"GroupName": "角色素材组",
"GroupDescription": "短剧角色素材"
}响应返回 TaskId。
第二步:查询素材创建结果
用 TaskId 调用 DescribeTaskDetail,从 Response.CreateAigcMaterialTask.Output.AssetId 取得素材 ID,方法同第四步。
第三步:用素材生视频
{
"SubAppId": 123456789,
"ModelName": "wand-vega-video",
"ModelVersion": "1.0-pro",
"Prompt": "角色B 在霓虹街道上回头挥手",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "asset://asset-********"
}
],
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9"
}
}第四步:查询生视频结果
素材组直接参考(asset_group_id)
如果不想先注册素材,也可以在生视频请求中直接传图片 URL,同时在 ExtInfo.AdditionalParameters 中指定一个自定义的 asset_group_id,由平台代为上传入组。首次使用的组 ID 会自动创建。
{
"SubAppId": 123456789,
"ModelName": "wand-vega-video",
"ModelVersion": "1.5-pro",
"Prompt": "natural motion, soft light",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "https://example.com/character.jpg"
}
],
"OutputConfig": {
"Resolution": "720P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"asset_group_id\\\":\\\"my-character-group\\\"}\"}"
}这种方式只需调用一次 CreateAigcVideoTask,适合偶尔使用的场景。如果同一个角色要在多个任务中反复出现,还是建议先注册素材、缓存 AssetId 再复用。国内站的现实真人素材仍按场景 ① 走真人素材接入。
素材管理接口
以下接口用于查询、修改、删除素材与素材组,国内站与国际站通用。
| 接口 | 用途 |
|---|---|
DescribeAigcMaterial | 查询单个素材 |
DescribeAigcMaterialList | 分页查询素材列表,可按素材组、素材类型过滤 |
ModifyAigcMaterial | 修改素材名称 |
DeleteAigcMaterial | 删除单个素材,或删除整个素材组 |
CreateAigcMaterialGroup | 创建素材组 |
DescribeAigcMaterialGroup | 查询素材组信息 |
DescribeAigcMaterialGroupList | 分页查询素材组列表 |
ModifyAigcMaterialGroup | 修改素材组名称与描述 |
DescribeAigcMaterial
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
AssetId | 是 | String | 要查询的素材 ID |
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}DescribeAigcMaterialList
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 素材组 ID,仅返回该组下的素材 |
AssetType | 否 | String | 按类型过滤:Image / Video / Audio |
Limit | 否 | Integer | 每页条数,取值 [0, 300],为 0 时取默认值 10 |
Offset | 否 | Integer | 起始偏移量,默认 0,必须是 Limit 的整数倍 |
返回 TotalCount(符合条件的素材总数)与 AssetInfoList。AssetInfoList 中每一项的字段:
| 字段 | 类型 | 说明 |
|---|---|---|
AssetId | String | 素材 ID |
AssetName | String | 素材名称 |
AssetType | String | Image / Video / Audio |
AssetUrl | String | 素材访问地址 |
GroupId | String | 所属素材组 ID |
Status | String | 素材状态 |
CreateTime | String | 创建时间,ISO 8601(UTC) |
{
"SubAppId": 123456789,
"GroupId": "my-character-group",
"AssetType": "Image",
"Limit": 10,
"Offset": 0
}ModifyAigcMaterial
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
AssetId | 是 | String | 要修改的素材 ID |
AssetName | 是 | String | 修改后的素材名称 |
返回 AssetId。
{
"SubAppId": 123456789,
"AssetId": "asset-********",
"AssetName": "主播A-正面"
}DeleteAigcMaterial
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
AssetId | 否 | String | 要删除的素材 ID |
GroupId | 否 | String | 要删除的素材组 ID |
传 GroupId 会删除整组素材
传入 GroupId 时,该组内所有素材都会被删除。只想删单个素材时,只传 AssetId。
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}CreateAigcMaterialGroup
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
GroupName | 否 | String | 素材组名称 |
GroupDescription | 否 | String | 素材组描述 |
返回 GroupId。
{
"GroupName": "角色素材组",
"GroupDescription": "短剧角色素材"
}DescribeAigcMaterialGroup
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 要查询的素材组 ID |
返回 GroupId、GroupName、GroupDescription、GroupType(素材组类型)、CreateTime、UpdateTime(时间均为 ISO 8601,UTC)。
{
"SubAppId": 123456789,
"GroupId": "my-character-group"
}DescribeAigcMaterialGroupList
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
Limit | 否 | Integer | 每页条数,取值 [0, 300],为 0 时取默认值 10 |
Offset | 否 | Integer | 起始偏移量,默认 0,必须是 Limit 的整数倍;Limit 为 0 时须是 10 的整数倍。例如 Offset=20、Limit=10 表示第 3 页 |
返回 TotalCount 与 GroupInfoList。GroupInfoList 中每一项的字段:
| 字段 | 类型 | 说明 |
|---|---|---|
GroupId | String | 素材组 ID |
GroupName | String | 素材组名称 |
GroupDescription | String | 素材组描述 |
IsRealPerson | String | 是否为真人素材组:True / False |
CreateTime | String | 创建时间,ISO 8601(UTC) |
UpdateTime | String | 更新时间,ISO 8601(UTC) |
{
"SubAppId": 123456789,
"Limit": 10,
"Offset": 0
}ModifyAigcMaterialGroup
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 要修改的素材组 ID |
GroupName | 否 | String | 修改后的素材组名称 |
GroupDescription | 否 | String | 修改后的素材组描述 |
返回 GroupId。
{
"SubAppId": 123456789,
"GroupId": "my-character-group",
"GroupName": "角色素材组",
"GroupDescription": "短剧角色素材,统一管理"
}常见报错
| 报错信息 | 原因 | 处理方法 |
|---|---|---|
The request failed because the input image may contain real person. | 生视频请求直接引用了含真人人脸的 URL | 先注册为素材,再以 asset://<AssetId> 引用。国内站现实真人走真人素材接入,其余走非真人与国际站素材接入 |
Face consistency verification failed. | 创建真人素材时,图片中的人脸与该 GroupId 活体认证时的人脸不一致 | 每个活体认证 GroupId 只接受对应的那张人脸。换人需要重新发起活体认证,获取新的 GroupId |
OutputAudioSensitiveContentDetected | 生成的音频疑似包含版权音乐,被输出审核拦截 | ① 关闭音频(AudioGeneration: Disabled),只生成视频;② 使用自有或已获授权的参考音频;③ 在提示词中强调不要使用版权音乐(有一定效果,但不保证) |