跳到内容

VS ​

更新时间

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

VS 是点播(VOD)AIGC 生视频的通用模型,支持文生视频、首帧生视频、首尾帧生视频与多模态参考(图片 / 视频 / 音频)。本页覆盖开通准备、通用生视频、真人 / 非真人素材接入以及素材管理接口的完整调用口径。

使用前须知

本模型需要联系 WAND 团队,给到您的 APPID 和 UIN,将您的账号信息加入功能白名单后才能使用。

基本信息 ​

项目取值
ModelNameVS
ModelVersion2.5-flash / 2.5 / 2.0 / 2.0-fast / 2.0-mini
默认值ModelVersion=2.0 / Resolution=1080P
是否支持解除安全护栏不支持

各版本支持的规格 ​

版本分辨率比例时长
2.5-flash480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 秒
2.5480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 秒
2.0 / 2.0-fast / 2.0-mini480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~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。

json
"SubAppId": 1500000000

素材(asset)与人脸一致性 ​

VS 在涉及人脸时受版权与肖像权约束,官方通过**素材(asset)**机制处理:先把 URL(https://xxx)转成素材(asset://xxxx/),再在生视频时引用素材,而不是直接引用原始 URL。

关于 GroupId 的三条规则:

  1. 调用活体认证接口时(假设为人脸 A),会返回一个专属 GroupId,该 GroupId 只接受对应的人脸 A 作为素材输入;传入其他人脸会报错 Face consistency verification failed.
  2. 活体认证返回的 GroupId 与人脸一一对应。
  3. 非真人素材可自定义 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否StringFile(点播媒体文件)或 Url(可访问的 URL)
FileInfos.N.Category否StringImage / Video / Audio
FileInfos.N.FileId否StringType=File 时的点播媒体 ID
FileInfos.N.Url否StringType=Url 时的文件地址;引用已注册素材时填 asset://asset-xxx
OutputConfig.Resolution否String480P / 720P / 1080P / 2K / 4K。各版本取值相同
OutputConfig.Duration否Float输出时长(秒)。2.0 系列 4~15,2.5 / 2.5-flash 为 4~30;传 -1 由模型自动决定
OutputConfig.AspectRatio否String21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive
OutputConfig.AudioGeneration否StringEnabled 开启音画同出,Disabled 关闭
OutputConfig.LogoAdd否StringEnabled 开启图标水印,Disabled 关闭
OutputConfig.StorageMode否StringTemporary(临时存储)/ 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

主要接口 ​

编号接口文档说明
1CreateAigcVideoTask创建 AIGC 生视频任务通用 AIGC 生视频接口,支持自定义模型等特性,返回 TaskId,可通过主动查询或回调获取结果
2CreateAigcLivenessValidate见发起活体认证发起活体检测
3DescribeAigcLivenessValidateResult见查询活体认证结果查询活体检测结果
4CreateAigcMaterial见创建真人素材创建素材(真人 / 非真人)
5DescribeTaskDetail查询任务详情查询素材、生视频等各类任务。生视频建议优先用回调获取结果
6普通回调配置:回调设置
结构:AigcVideoTask
任务完成后推送结果,建议使用
7可靠事件通知配置:回调设置
API:拉取事件通知
主动拉取事件通知,建议使用

上游模型文档:https://docs.volcengine.com/docs/82379/2291680

请求示例 ​

通用生视频 ​

json
{
  "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。

json
{
  "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"
  }
}

首帧生视频 ​

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.0",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/1.png",
      "Usage": "FirstFrame"
    }
  ],
  "Prompt": "他在散步"
}

首尾帧生视频 ​

json
{
  "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。下例为视频延长:

json
{
  "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 示例 ​

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)

响应示例 ​

json
{
  "Response": {
    "RequestId": "aaa51**********d66c74f1a",
    "TaskId": "123456-AigcVideoTask-********45f4ee25t"
  }
}

查询任务结果 ​

拿到 TaskId 后调用 DescribeTaskDetail 查询;生视频任务建议优先使用普通回调或可靠事件通知,避免高频轮询。

json
{
  "TaskId": "123456-AigcVideoTask-********45f4ee25t",
  "SubAppId": 123456789
}

生视频任务的结果位于 Response.AigcVideoTask:

字段说明
StatusPROCESSING / FINISH / FAIL
ErrCode / Message失败时的错误码与描述
Output.FileInfos[].FileUrl生成结果的访问地址
Output.FileInfos[].UsageType空字符串表示生成的视频;last_frame_url 表示尾帧图片
Output.FileInfos[].MetaData时长、码率、分辨率、编码等媒体信息

场景化示例 ​

返回尾帧图片 ​

第一步,发起生视频任务时在 ExtInfo 中指定 return_last_frame:

json
{
  "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:

json
{
  "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:

json
{
  "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,即可在同一请求里同时给出参考图与素材组。

json
{
  "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。

json
{
  "SubAppId": 123456789,
  "CallbackUrl": "https://example.com/callback"
}

返回 H5Link 与 LivenessToken:

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

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

让用户在浏览器打开 H5Link 完成活体认证,认证完成后用 LivenessToken 调用 DescribeAigcLivenessValidateResult 查询结果。

json
{
  "SubAppId": 123456789,
  "LivenessToken": "2*******************************6B"
}
json
{
  "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是StringImage / 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拓展参数,保留
json
{
  "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。

json
{
  "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。

参数取值
ModelNameVS
ModelVersion2.0 / 2.0-fast / 2.0-mini / 2.5 / 2.5-flash
FileInfos.CategoryImage / Video / Audio
FileInfos.UsageReference(参考)/ FirstFrame / LastFrame
OutputConfig.Resolution480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration2.0 系列 4~15,2.5 / 2.5-flash 为 4~30
OutputConfig.AspectRatio21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive
OutputConfig.AudioGenerationEnabled / Disabled
json
{
  "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 可自定义。

json
{
  "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。

第三步:用素材生视频 ​

json
{
  "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
json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

DeleteAigcMaterial ​

删除素材。传 GroupId 时会删除该组内全部素材。

参数必选类型说明
SubAppId是Integer点播应用 ID
AssetId否String要删除的素材 ID
GroupId否String要删除的素材组 ID,会连同组内所有素材一起删除
json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

ModifyAigcMaterial ​

修改素材名称。

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

返回:AssetId(素材 ID)。

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

ModifyAigcMaterialGroup ​

修改素材组的名称与描述。

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

返回:GroupId(素材组 ID)。

json
{
  "SubAppId": 123456789,
  "GroupId": "my-virtual-group",
  "GroupName": "虚拟人素材组",
  "GroupDescription": "虚拟人素材统一管理"
}

DescribeAigcMaterialGroup ​

查询素材组信息。

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

返回字段:

字段类型说明
GroupIdString素材组 ID
GroupNameString素材组名称
GroupDescriptionString素材组描述
GroupTypeString素材组类型
CreateTimeString创建时间,ISO 8601(UTC)
UpdateTimeString更新时间,ISO 8601(UTC)
json
{
  "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 的整数倍

返回字段:

字段类型说明
TotalCountInteger符合过滤条件的素材总数
AssetInfoListArray素材信息列表,结构见下表

AigcMaterialAssetInfo 结构:

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

CreateAigcMaterialGroup ​

创建素材组。

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

返回:GroupId(素材组 ID)。

json
{
  "GroupName": "my-virtual-group",
  "GroupDescription": "虚拟人素材统一管理"
}

DescribeAigcMaterialGroupList ​

查询素材组列表,通过 Offset / Limit 分页返回素材组信息与总数。

参数必选类型说明
SubAppId否Integer点播应用 ID
Limit否Integer每页条数,取值 [0, 300],为 0 时取默认值 10
Offset否Integer起始偏移量,默认 0,且必须是 Limit 的整数倍;Limit 为 0 时须是默认值 10 的整数倍

返回字段:

字段类型说明
TotalCountInteger符合条件的素材组总数
GroupInfoListArray素材组信息列表,结构见下表

AigcMaterialGroupInfo 结构:

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

常见报错 ​

序号报错解决方案
1task 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:// 地址,见素材与人脸一致性
2code:OutputAudioSensitiveContentDetected, message:The request failed because the output audio may contain sensitive information开启音画同出时,生成结果可能带版权音乐而被内容审核拦截。原厂建议:① 去掉音频只出视频;② 使用自有非版权参考音频;③ 在提示词中强调不要引入版权音乐(有效但有限)

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