VS
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
VS 是点播(VOD)AIGC 生视频的通用模型,支持文生视频、首帧生视频、首尾帧生视频与多模态参考(图片 / 视频 / 音频)。本页覆盖开通准备、通用生视频、真人 / 非真人素材接入以及素材管理接口的完整调用口径。
使用前须知
本模型需要联系 WAND 团队,给到您的 APPID 和 UIN,将您的账号信息加入功能白名单后才能使用。
基本信息
| 项目 | 取值 |
|---|---|
| ModelName | VS |
| ModelVersion | 2.5-flash / 2.5 / 2.0 / 2.0-fast / 2.0-mini |
| 默认值 | ModelVersion=2.0 / Resolution=1080P |
| 是否支持解除安全护栏 | 不支持 |
各版本支持的规格
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
2.5-flash | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~30 秒 |
2.5 | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~30 秒 |
2.0 / 2.0-fast / 2.0-mini | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~15 秒 |
2K / 4K 为超分直出。VS 2.5 另外支持:
- 生成类型:文生视频、首帧生视频、首尾帧生视频、多模态参考(图片、视频、音频)
- 参考素材上限:
50(30张图 +10个视频 +10个音频) - 声音:支持音画同出
- 样片(Draft)模式:
480P先出预览,确认后用draft_task_id直出成片
VS 2.5-flash(2026-11-17 上新)是更轻量的版本,生成类型与 2.5 一致(文生视频、首帧、首尾帧、多模态参考),支持音画同出,1080P / 2K / 4K 均为超分直出;主要区别是参考素材上限为 20(10 张图 + 5 个视频 + 5 个音频)。
接入准备
开通 VOD
| 站点 | 入口 |
|---|---|
| 国内站 | 云点播控制台 |
| 国际站 | 云点播控制台(国际站) |
获取 AK / SK
控制台右上角账号头像 → 访问管理(CAM) → 左侧 访问密钥 → API 密钥管理,复制已启用密钥的 SecretId / SecretKey,或新建密钥。
密钥不要硬编码
持有 SecretId / SecretKey 即可操作账号下全部资源。示例代码统一从环境变量 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY 读取,不要写进代码仓库或文档截图。
获取 SubAppId
| 站点 | 入口 |
|---|---|
| 国内站 | 云点播控制台 |
| 国际站 | 云点播控制台(国际站) |
开通 VOD 后会创建一个默认应用(SubAppId),AIGC 调用可直接使用;也可以按下述步骤新建应用。
创建 VOD 标准版应用(按需)
用于 AIGC 数据存储,后续处理可走内网通信,节省流量成本。
控制台 → 应用管理 → 创建应用 → 填写应用名称 → 应用类型选 标准版 → 确定,列表中的应用名称下方即为该应用的 SubAppId。
"SubAppId": 1500000000素材(asset)与人脸一致性
VS 在涉及人脸时受版权与肖像权约束,官方通过**素材(asset)**机制处理:先把 URL(https://xxx)转成素材(asset://xxxx/),再在生视频时引用素材,而不是直接引用原始 URL。
关于 GroupId 的三条规则:
- 调用活体认证接口时(假设为人脸 A),会返回一个专属
GroupId,该GroupId只接受对应的人脸 A 作为素材输入;传入其他人脸会报错Face consistency verification failed. - 活体认证返回的
GroupId与人脸一一对应。 - 非真人素材可自定义
GroupId,专门用于非真人人脸(含虚拟人)素材的输入。
三种接入场景
| 场景 | 步骤 | 参考章节 |
|---|---|---|
| ① 现实真人素材 | 发起活体认证 → 查询活体认证结果 → 创建素材(真人 asset)→ 查询素材结果 → 创建视频任务 → 查询任务 | 真人素材接入 |
| ② 非现实真人(含虚拟人) | 创建素材(按需,非必须)→ 查询素材结果 → 创建视频任务 → 查询任务 | 非真人素材接入 |
| ③ 其他(通用生视频) | 创建视频任务 → 查询任务 | 通用生视频 |
短剧场景补充:
- 素材是否包含人脸很难可靠区分,建议对每个素材都先注册再引用。
- 建议引入缓存机制复用素材,避免重复生成。
关键参数
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID。2023 年 12 月 25 日起开通点播的客户,访问应用内资源(默认应用或新建应用)时必须填应用 ID。示例值:251007502 |
ModelName | 是 | String | 模型名称,固定 VS |
ModelVersion | 否 | String | 模型版本:2.0 / 2.0-fast / 2.0-mini / 2.5 / 2.5-flash |
Prompt | 否 | String | 输入提示词。FileInfos 为空时必填 |
FileInfos.N | 否 | Array | 参考素材列表。Usage 取 FirstFrame(首帧)、LastFrame(尾帧)、Reference(参考) |
FileInfos.N.Type | 否 | String | File(点播媒体文件)或 Url(可访问的 URL) |
FileInfos.N.Category | 否 | String | Image / Video / Audio |
FileInfos.N.FileId | 否 | String | Type=File 时的点播媒体 ID |
FileInfos.N.Url | 否 | String | Type=Url 时的文件地址;引用已注册素材时填 asset://asset-xxx |
OutputConfig.Resolution | 否 | String | 480P / 720P / 1080P / 2K / 4K。各版本取值相同 |
OutputConfig.Duration | 否 | Float | 输出时长(秒)。2.0 系列 4~15,2.5 / 2.5-flash 为 4~30;传 -1 由模型自动决定 |
OutputConfig.AspectRatio | 否 | String | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive |
OutputConfig.AudioGeneration | 否 | String | Enabled 开启音画同出,Disabled 关闭 |
OutputConfig.LogoAdd | 否 | String | Enabled 开启图标水印,Disabled 关闭 |
OutputConfig.StorageMode | 否 | String | Temporary(临时存储)/ Permanent(永久存储) |
OutputConfig.Seed | 否 | Integer | 随机种子。相同种子与输入可复现结果,示例值 123 |
ExtInfo | 否 | String | 拓展参数,需转义,取值见下表 |
ExtInfo 选项
ExtInfo 是一个 JSON 字符串,其 AdditionalParameters 字段本身又是 JSON 字符串,因此需要双重转义。
| 用途 | 取值 |
|---|---|
| 开启高码率输出 | "{\"AdditionalParameters\":\"{\\\"bitrate_mode\\\":\\\"high\\\"}\"}" |
| 返回尾帧图片(见返回尾帧图片) | "{\"AdditionalParameters\":\"{\\\"return_last_frame\\\":true}\"}" |
| 开启 Draft 样片模式(见 Draft 样片模式) | "{\"AdditionalParameters\":\"{\\\"draft\\\":true}\"}" |
| 指定 Draft 样片任务 ID(见 Draft 样片模式) | {"AdditionalParameters":"{\"draft_task_id\":\"1500013788-AigcVideoTask-*****2e4ae72f86db173at\"}"} |
指定任务类型 omni_reference_task_type(编辑 / 参考 / 视频延长) | "{\"AdditionalParameters\":\"{\\\"omni_reference_task_type\\\":\\\"extend\\\"}\"}" |
指定素材组 asset_group_id(见素材组直接参考) | "{\"AdditionalParameters\": \"{\\\"asset_group_id\\\": \\\"my-asset-group\\\"}\"}" |
omni_reference_task_type 的取值:
| 取值 | 含义与约束 |
|---|---|
auto | 由模型根据输入素材和提示词自动判定任务类型 |
reference | 参考生视频,基于参考图片、参考视频或参考音频生成新视频。ratio / duration 无特殊限制 |
edit | 视频编辑,对原视频的画面或音频做编辑。必须包含至少一个 reference_video,视频时长 4~30 秒;ratio 必须为 adaptive;duration 必须为 -1 |
extend | 视频延长,对原视频向前或向后延长。必须包含至少一个 reference_video;ratio 必须为 adaptive |
主要接口
| 编号 | 接口 | 文档 | 说明 |
|---|---|---|---|
| 1 | CreateAigcVideoTask | 创建 AIGC 生视频任务 | 通用 AIGC 生视频接口,支持自定义模型等特性,返回 TaskId,可通过主动查询或回调获取结果 |
| 2 | CreateAigcLivenessValidate | 见发起活体认证 | 发起活体检测 |
| 3 | DescribeAigcLivenessValidateResult | 见查询活体认证结果 | 查询活体检测结果 |
| 4 | CreateAigcMaterial | 见创建真人素材 | 创建素材(真人 / 非真人) |
| 5 | DescribeTaskDetail | 查询任务详情 | 查询素材、生视频等各类任务。生视频建议优先用回调获取结果 |
| 6 | 普通回调 | 配置:回调设置 结构:AigcVideoTask | 任务完成后推送结果,建议使用 |
| 7 | 可靠事件通知 | 配置:回调设置 API:拉取事件通知 | 主动拉取事件通知,建议使用 |
上游模型文档:https://docs.volcengine.com/docs/82379/2291680
请求示例
通用生视频
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.0",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/1.png",
"Usage": "Reference"
}
],
"Prompt": "他在散步",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "720P",
"Duration": 5,
"AspectRatio": "16:9",
"AudioGeneration": "Disabled"
}
}高码率输出
在 ExtInfo 中把 bitrate_mode 指定为 high。
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"Prompt": "a calm sunset over the ocean, cinematic",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"bitrate_mode\\\":\\\"high\\\"}\"}",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9"
}
}首帧生视频
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.0",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/1.png",
"Usage": "FirstFrame"
}
],
"Prompt": "他在散步"
}首尾帧生视频
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.0",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/1.png",
"Usage": "FirstFrame"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/2.png",
"Usage": "LastFrame"
}
],
"Prompt": "他在散步"
}指定任务类型(视频编辑 / 视频延长)
通过拓展参数传入官方 omni_reference_task_type。下例为视频延长:
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://example.com/source.mp4",
"Usage": "Reference"
}
],
"OutputConfig": {
"AspectRatio": "adaptive"
},
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"omni_reference_task_type\\\":\\\"extend\\\"}\"}"
}Python 示例
import os
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.vod.v20180717 import vod_client, models
try:
cred = credential.Credential(
os.environ["TENCENTCLOUD_SECRET_ID"],
os.environ["TENCENTCLOUD_SECRET_KEY"],
)
http_profile = HttpProfile()
http_profile.endpoint = "vod.tencentcloudapi.com"
client_profile = ClientProfile()
client_profile.httpProfile = http_profile
client = vod_client.VodClient(cred, "ap-guangzhou", client_profile)
req = models.CreateAigcVideoTaskRequest()
req.SubAppId = 1500000000
req.ModelName = "VS"
req.ModelVersion = "2.5"
req.Prompt = "一只猫咪在阳光下玩耍,慢镜头,电影质感"
output = models.AigcVideoOutputConfig()
output.StorageMode = "Temporary"
output.Resolution = "720P"
output.Duration = 5
output.AspectRatio = "16:9"
req.OutputConfig = output
resp = client.CreateAigcVideoTask(req)
print("TaskId:", resp.TaskId)
except TencentCloudSDKException as err:
print(err)响应示例
{
"Response": {
"RequestId": "aaa51**********d66c74f1a",
"TaskId": "123456-AigcVideoTask-********45f4ee25t"
}
}查询任务结果
拿到 TaskId 后调用 DescribeTaskDetail 查询;生视频任务建议优先使用普通回调或可靠事件通知,避免高频轮询。
{
"TaskId": "123456-AigcVideoTask-********45f4ee25t",
"SubAppId": 123456789
}生视频任务的结果位于 Response.AigcVideoTask:
| 字段 | 说明 |
|---|---|
Status | PROCESSING / FINISH / FAIL |
ErrCode / Message | 失败时的错误码与描述 |
Output.FileInfos[].FileUrl | 生成结果的访问地址 |
Output.FileInfos[].UsageType | 空字符串表示生成的视频;last_frame_url 表示尾帧图片 |
Output.FileInfos[].MetaData | 时长、码率、分辨率、编码等媒体信息 |
场景化示例
返回尾帧图片
第一步,发起生视频任务时在 ExtInfo 中指定 return_last_frame:
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.0",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/1.png",
"Usage": "Reference"
}
],
"Prompt": "他在散步",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"return_last_frame\\\":true}\"}"
}第二步,查询任务结果。AigcVideoTask.Output.FileInfos 中会包含两条记录:一条是生成的视频(UsageType 为空字符串),一条是尾帧图片(UsageType 为 last_frame_url)。
Draft 样片模式
样片(Draft)是一种「先快速验证效果,再生成高质量成片」的两步式生成方式:先用低分辨率快速产出一段预览,验证场景结构、镜头调度、主体动作和提示词意图是否符合预期;确认后再用 Draft 任务 ID 生成成片。
第一步,发起样片任务,在 ExtInfo 中指定 draft,并把分辨率设为 480P:
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://example.com/1.png",
"Usage": "Reference"
}
],
"Prompt": "他在散步",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "480P"
},
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"draft\\\":true}\"}"
}第二步,用上一步返回的 TaskId 作为 draft_task_id,分辨率设为 1080P:
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P"
},
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"draft_task_id\\\":\\\"1500013788-AigcVideoTask-*****2e4ae72f86db173at\\\"}\"}"
}第二步不要再传 Prompt
使用 draft_task_id 时不需要再传 Prompt、FileInfos 等参数 —— 即使传入的值与 Draft 阶段完全一致,也会触发报错。
素材组直接参考
在 FileInfos 中指定图片 URL,并在 ExtInfo.AdditionalParameters 中传入 asset_group_id,即可在同一请求里同时给出参考图与素材组。
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"Prompt": "参考图中的人物轻轻微笑并缓慢向前走,保持服装与糖果世界背景,固定机位",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "https://example.com/person-reference.jpg"
}
],
"OutputConfig": {
"Resolution": "720P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"asset_group_id\\\": \\\"my-asset-group\\\"}\"}"
}复用已注册素材
先用 CreateAigcMaterial 注册图片,再用 DescribeTaskDetail 查询返回的 AssetId,生视频时把 Url 写成 asset://asset-xxx 即可复用,无需重复注册。
参考数量上限
FileInfos 中可放入的参考素材,ModelVersion=2.5 时最多 50 个(图片 30 + 视频 10 + 音频 10);ModelVersion=2.5-flash 时最多 20 个(图片 10 + 视频 5 + 音频 5)。
真人素材接入
第一步:发起活体认证
调用 CreateAigcLivenessValidate,SubAppId 需替换为你的应用 ID。
{
"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": 123456789,
"LivenessToken": "2*******************************6B"
}{
"Response": {
"GroupId": "group-*************",
"LivenessToken": "2*******************C",
"Message": "ok",
"Status": "DONE",
"RequestId": "a82*************b38"
}
}返回的 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 | 任务优先级,数值越高优先级越高 |
ExtInfo | 否 | String | 拓展参数,保留 |
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/person.png"
},
"AssetType": "Image",
"GroupId": "group-*************",
"AssetName": "主播A",
"IsRealPerson": "True",
"GroupName": "真人素材组",
"GroupDescription": "真人素材库",
"SessionId": "session-001",
"SessionContext": "用户A提交的素材",
"TasksPriority": 10
}第四步:查询素材创建结果
用创建素材返回的 TaskId 调用 DescribeTaskDetail,结果位于 Response.CreateAigcMaterialTask,其中 Output.AssetId 即为后续生视频要引用的素材 ID。
{
"Response": {
"AigcVideoTask": null,
"CreateAigcMaterialTask": {
"Status": "FINISH",
"ErrCode": 0,
"Input": {
"AssetName": "主播A",
"AssetType": "Image",
"GroupId": "group-*************",
"IsRealPerson": "True"
},
"Output": {
"AssetId": "asset-********",
"AssetUrl": "url",
"GroupId": "group-*************"
},
"TaskId": "123456-CreateAigcMaterial-521c5f8288cd523e7ca27db213676ad0t"
},
"RequestId": "0e3c78d4-dbd6-4519-a1c6-0adfa06a67ef"
}
}第五步:用真人素材生视频
把 AssetId 写成 asset://asset-xxx 传给 FileInfos.N.Url。
| 参数 | 取值 |
|---|---|
ModelName | VS |
ModelVersion | 2.0 / 2.0-fast / 2.0-mini / 2.5 / 2.5-flash |
FileInfos.Category | Image / Video / Audio |
FileInfos.Usage | Reference(参考)/ FirstFrame / LastFrame |
OutputConfig.Resolution | 480P / 720P / 1080P / 2K / 4K |
OutputConfig.Duration | 2.0 系列 4~15,2.5 / 2.5-flash 为 4~30 |
OutputConfig.AspectRatio | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive |
OutputConfig.AudioGeneration | Enabled / Disabled |
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"Prompt": "主播A 在直播间介绍新品,镜头缓慢推进",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "asset://asset-********"
}
],
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"AudioGeneration": "Disabled"
}
}第六步:查询任务结果
用生视频返回的 TaskId 调用 DescribeTaskDetail,参考查询任务结果。
非真人素材接入
第一步:创建非真人素材
调用 CreateAigcMaterial,IsRealPerson 传 "False",GroupId 可自定义。
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/virtual-human.png"
},
"AssetType": "Image",
"GroupId": "my-virtual-group",
"AssetName": "虚拟角色B",
"IsRealPerson": "False",
"GroupName": "虚拟人素材组"
}AssetType 可取 Image / Video / Audio。
第二步:查询素材创建结果
同样使用 DescribeTaskDetail 查询,取得 Output.AssetId。
第三步:用素材生视频
{
"SubAppId": 123456789,
"ModelName": "VS",
"ModelVersion": "2.5",
"Prompt": "虚拟角色B 在霓虹街道上挥手,赛博朋克风格",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "asset://asset-********"
}
],
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9"
}
}第四步:查询任务结果
参考查询任务结果。
素材管理接口
DescribeAigcMaterial
查询单个素材。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
AssetId | 是 | String | 要查询的素材 ID |
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}DeleteAigcMaterial
删除素材。传 GroupId 时会删除该组内全部素材。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 是 | Integer | 点播应用 ID |
AssetId | 否 | String | 要删除的素材 ID |
GroupId | 否 | String | 要删除的素材组 ID,会连同组内所有素材一起删除 |
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}ModifyAigcMaterial
修改素材名称。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
AssetId | 是 | String | 要修改的素材 ID |
AssetName | 是 | String | 修改后的素材名称 |
返回:AssetId(素材 ID)。
{
"SubAppId": 123456789,
"AssetId": "asset-********",
"AssetName": "主播A-正面"
}ModifyAigcMaterialGroup
修改素材组的名称与描述。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 要修改的素材组 ID |
GroupName | 否 | String | 修改后的素材组名称 |
GroupDescription | 否 | String | 修改后的素材组描述 |
返回:GroupId(素材组 ID)。
{
"SubAppId": 123456789,
"GroupId": "my-virtual-group",
"GroupName": "虚拟人素材组",
"GroupDescription": "虚拟人素材统一管理"
}DescribeAigcMaterialGroup
查询素材组信息。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 要查询的素材组 ID |
返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
GroupId | String | 素材组 ID |
GroupName | String | 素材组名称 |
GroupDescription | String | 素材组描述 |
GroupType | String | 素材组类型 |
CreateTime | String | 创建时间,ISO 8601(UTC) |
UpdateTime | String | 更新时间,ISO 8601(UTC) |
{
"SubAppId": 123456789,
"GroupId": "my-virtual-group"
}DescribeAigcMaterialList
查询素材列表,支持按素材组、素材类型过滤,并通过 Offset / Limit 分页。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
GroupId | 是 | String | 素材组 ID,填写后仅返回该组下的素材 |
AssetType | 否 | String | 按类型过滤:Image / Video / Audio |
Limit | 否 | Integer | 每页条数,取值 [0, 300],为 0 时取默认值 10 |
Offset | 否 | Integer | 起始偏移量,默认 0,且必须是 Limit 的整数倍 |
返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
TotalCount | Integer | 符合过滤条件的素材总数 |
AssetInfoList | Array | 素材信息列表,结构见下表 |
AigcMaterialAssetInfo 结构:
| 字段 | 类型 | 说明 |
|---|---|---|
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-virtual-group",
"AssetType": "Image",
"Limit": 10,
"Offset": 0
}CreateAigcMaterialGroup
创建素材组。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
GroupName | 否 | String | 素材组名称 |
GroupDescription | 否 | String | 素材组描述 |
返回:GroupId(素材组 ID)。
{
"GroupName": "my-virtual-group",
"GroupDescription": "虚拟人素材统一管理"
}DescribeAigcMaterialGroupList
查询素材组列表,通过 Offset / Limit 分页返回素材组信息与总数。
| 参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 否 | Integer | 点播应用 ID |
Limit | 否 | Integer | 每页条数,取值 [0, 300],为 0 时取默认值 10 |
Offset | 否 | Integer | 起始偏移量,默认 0,且必须是 Limit 的整数倍;Limit 为 0 时须是默认值 10 的整数倍 |
返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
TotalCount | Integer | 符合条件的素材组总数 |
GroupInfoList | Array | 素材组信息列表,结构见下表 |
AigcMaterialGroupInfo 结构:
| 字段 | 类型 | 说明 |
|---|---|---|
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
}常见报错
| 序号 | 报错 | 解决方案 |
|---|---|---|
| 1 | task failed with status: FAIL, message: create gen_video task, failed. ret:-4,msg:The request failed because the input image may contain real person. | 直接引用的 URL 素材中包含人脸。先用 CreateAigcMaterial 生成素材(asset),再引用 asset:// 地址,见素材与人脸一致性 |
| 2 | code:OutputAudioSensitiveContentDetected, message:The request failed because the output audio may contain sensitive information | 开启音画同出时,生成结果可能带版权音乐而被内容审核拦截。原厂建议:① 去掉音频只出视频;② 使用自有非版权参考音频;③ 在提示词中强调不要引入版权音乐(有效但有限) |