跳到内容

Vega Video HOT ​

更新时间

Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask

Vega Video 是 WAND 自研的视频生成模型,支持文生视频、首帧 / 尾帧 / 首尾帧生成,以及图片、视频、音频混合输入的多模态参考生成,并可同时生成音频。Pro 系列另支持基于参考视频的编辑与延长,输出最高 4K、单条最长 30 秒。1.5-pro 另支持两步式 Draft 样片:先出 480P 样片校验效果,再基于样片任务生成成片。

选择版本 ​

接口文档按版本拆分,点击卡片查看对应版本的输入规格、请求参数、请求示例与特殊设置。

基本信息 ​

项目值
ModelNamewand-vega-video
ModelVersion1.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-pro720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 秒
1.5-lite480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive2~30 秒 / -1 智能时长
1.0-pro / 1.0-pro-fast / 1.0-pro-mini480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~15 秒
1.0-lite480P / 768P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~15 秒

六个 ModelVersion 值共用 CreateAigcVideoTask 接口与 ModelName: wand-vega-video;三个 1.0 Pro 变体共用同一规格页。

接入准备 ​

使用前须知

Vega Video Pro 系列需开通白名单后才能调用。请联系 WAND 团队,提供您的 APPID 与 UIN。

步骤国内站国际站
开通云点播(VOD)VOD 控制台VOD 控制台
获取 SecretId / SecretKeyAPI 密钥管理API 密钥管理
获取 SubAppId开通 VOD 后会自动创建默认应用,也可另建应用,见应用体系同左,见应用体系
API 域名vod.tencentcloudapi.comvod.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
json
{
  "SubAppId": 123456789,
  "CallbackUrl": "https://example.com/callback"
}

响应返回 H5Link(活体认证页面)与 LivenessToken(查询凭证):

json
{
  "Response": {
    "H5Link": "https://**************",
    "LivenessToken": "2*******************************6B",
    "RequestId": "76002966-e3f7-4156-a234-8a005046e6b7"
  }
}

第二步:查询活体认证结果 ​

  1. 让被认证本人在手机浏览器中打开 H5Link,完成活体认证。
  2. 认证完成后,用 LivenessToken 调用 DescribeAigcLivenessValidateResult。
参数必选类型说明
SubAppId是Integer点播应用 ID
LivenessToken是String第一步返回的 LivenessToken
json
{
  "SubAppId": 123456789,
  "LivenessToken": "2*******************************6B"
}
json
{
  "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拓展参数,保留字段
json
{
  "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
}
json
{
  "Response": {
    "TaskId": "123456-CreateAigcMaterial-6ae386*************************ft",
    "RequestId": "5f3537a2-b069-4b07-ab0d-9861f877ee12"
  }
}

素材创建是异步任务,响应只返回 TaskId,还拿不到 AssetId。

第四步:查询素材创建结果 ​

用第三步的 TaskId 调用 DescribeTaskDetail。

json
{
  "SubAppId": 123456789,
  "TaskId": "123456-CreateAigcMaterial-6ae386*************************ft"
}

结果位于 Response.CreateAigcMaterialTask。Status 为 FINISH 且 ErrCode 为 0 时,Output.AssetId 就是生视频要引用的素材 ID(以下响应已省略为 null 的其他任务字段):

json
{
  "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。其余参数与普通生视频一致,取值范围以所选版本为准。

参数取值
ModelNamewand-vega-video
ModelVersion1.5-pro / 1.0-pro / 1.0-pro-fast / 1.0-pro-mini
FileInfos.N.Urlasset://asset-********
FileInfos.N.CategoryImage / Video / Audio,与素材的 AssetType 一致
FileInfos.N.UsageReference / FirstFrame / LastFrame
OutputConfig.Resolution1.5-pro:720P / 1080P / 2K / 4K;1.0-pro 系列:480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration1.5-pro:4~30;1.0-pro 系列:4~15;-1 表示由模型决定
OutputConfig.AspectRatio21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive
OutputConfig.AudioGenerationEnabled / Disabled
json
{
  "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"
  }
}
json
{
  "Response": {
    "TaskId": "123456-AigcVideoTask-********45f4ee25t",
    "RequestId": "aaa51**********d66c74f1a"
  }
}

第六步:查询生视频结果 ​

用第五步的 TaskId 调用 DescribeTaskDetail,结果位于 Response.AigcVideoTask.Output.FileInfos;也可以通过回调接收结果,见主要接口。

非真人与国际站素材接入 ​

本节对应场景 ②,适用于:

  • 国内站的非真人、虚拟人素材;
  • 国内站已开白、免活体认证的真人素材;
  • 国际站的全部素材(真人、非真人、虚拟人),国际站域名为 vod.intl.tencentcloudapi.com。

与真人素材接入相比,本场景不需要活体认证,GroupId 自定义,IsRealPerson 一律传 "False"。

第一步:创建素材 ​

调用 CreateAigcMaterial,参数说明同第三步:创建真人素材。

json
{
  "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,方法同第四步。

第三步:用素材生视频 ​

json
{
  "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 会自动创建。

json
{
  "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
json
{
  "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 中每一项的字段:

字段类型说明
AssetIdString素材 ID
AssetNameString素材名称
AssetTypeStringImage / Video / Audio
AssetUrlString素材访问地址
GroupIdString所属素材组 ID
StatusString素材状态
CreateTimeString创建时间,ISO 8601(UTC)
json
{
  "SubAppId": 123456789,
  "GroupId": "my-character-group",
  "AssetType": "Image",
  "Limit": 10,
  "Offset": 0
}

ModifyAigcMaterial ​

参数必选类型说明
SubAppId否Integer点播应用 ID
AssetId是String要修改的素材 ID
AssetName是String修改后的素材名称

返回 AssetId。

json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********",
  "AssetName": "主播A-正面"
}

DeleteAigcMaterial ​

参数必选类型说明
SubAppId是Integer点播应用 ID
AssetId否String要删除的素材 ID
GroupId否String要删除的素材组 ID

传 GroupId 会删除整组素材

传入 GroupId 时,该组内所有素材都会被删除。只想删单个素材时,只传 AssetId。

json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

CreateAigcMaterialGroup ​

参数必选类型说明
GroupName否String素材组名称
GroupDescription否String素材组描述

返回 GroupId。

json
{
  "GroupName": "角色素材组",
  "GroupDescription": "短剧角色素材"
}

DescribeAigcMaterialGroup ​

参数必选类型说明
SubAppId否Integer点播应用 ID
GroupId是String要查询的素材组 ID

返回 GroupId、GroupName、GroupDescription、GroupType(素材组类型)、CreateTime、UpdateTime(时间均为 ISO 8601,UTC)。

json
{
  "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 中每一项的字段:

字段类型说明
GroupIdString素材组 ID
GroupNameString素材组名称
GroupDescriptionString素材组描述
IsRealPersonString是否为真人素材组:True / False
CreateTimeString创建时间,ISO 8601(UTC)
UpdateTimeString更新时间,ISO 8601(UTC)
json
{
  "SubAppId": 123456789,
  "Limit": 10,
  "Offset": 0
}

ModifyAigcMaterialGroup ​

参数必选类型说明
SubAppId否Integer点播应用 ID
GroupId是String要修改的素材组 ID
GroupName否String修改后的素材组名称
GroupDescription否String修改后的素材组描述

返回 GroupId。

json
{
  "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),只生成视频;② 使用自有或已获授权的参考音频;③ 在提示词中强调不要使用版权音乐(有一定效果,但不保证)

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages