Skip to content

VS โ€‹

Updated

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

VS is the general-purpose video generation model of Tencent Cloud VOD AIGC. It supports text-to-video, first-frame-to-video, first-and-last-frame-to-video and multimodal references (image, video, audio). This page covers activation and credentials, general video generation, real-person and non-real-person material workflows, and the material management APIs.

Before you start

This model requires contacting the WAND team with your APPID and UIN so that your account can be added to the feature allowlist. It cannot be used until then.

Basic Information โ€‹

ItemValue
ModelNameVS
ModelVersion2.5-flash / 2.5 / 2.0 / 2.0-fast / 2.0-mini
Default valueModelVersion=2.0 / Resolution=1080P
Guardrail disable supportNot supported

Specifications Supported by Version โ€‹

VersionResolutionAspect ratioLength
2.5-flash480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 seconds
2.5480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 seconds
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 seconds

2K / 4K are produced by super-resolution. VS 2.5 additionally supports:

  • Generation types: text-to-video, first-frame-to-video, first-and-last-frame-to-video, multimodal references (image, video, audio)
  • Reference material limit: 50 (30 images + 10 videos + 10 audio clips)
  • Audio: audio can be generated together with video
  • Draft mode: a 480P preview first, then a full-quality render with draft_task_id

VS 2.5-flash (released 2026-11-17) is a lighter version with the same generation types as 2.5 (text-to-video, first-frame, first-and-last-frame, multimodal references), supports audio-with-video, and produces 1080P / 2K / 4K via super-resolution; the main difference is a reference material limit of 20 (10 images + 5 videos + 5 audio clips).

Preparation โ€‹

Activate VOD โ€‹

SiteEntry
Chinese mainlandVOD console
InternationalVOD console (international)

Get AK / SK โ€‹

Console โ†’ account avatar (top right) โ†’ Access Management (CAM) โ†’ Access Key โ†’ API Key Management. Copy the SecretId / SecretKey of an enabled key, or create a new one.

Never hard-code your keys

Anyone holding your SecretId / SecretKey can operate every resource under the account. The samples below read them from TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY; never commit keys to a repository or paste them into screenshots.

Get SubAppId โ€‹

SiteEntry
Chinese mainlandVOD console
InternationalVOD console (international)

Activating VOD creates a default application (SubAppId) that AIGC calls can use directly. You can also create a new application as described below.

Create a VOD Standard application (optional) โ€‹

Used for AIGC data storage; later processing can then run over the internal network and save traffic cost.

Console โ†’ Application Management โ†’ Create Application โ†’ enter a name โ†’ choose Standard โ†’ confirm. The application ID is shown under its name in the list.

json
"SubAppId": 1500000000

Materials (assets) and face consistency โ€‹

When VS is used with human faces, copyright and portrait-rights rules apply. They are handled through the material (asset) mechanism: convert a URL (https://xxx) into a material (asset://xxxx/) first, then reference the material instead of the original URL.

Three rules about GroupId:

  1. Calling the liveness verification API (say for face A) returns a dedicated GroupId that accepts only face A as material input; any other face fails with Face consistency verification failed.
  2. GroupIds returned by liveness verification map one-to-one to faces.
  3. For non-real-person materials you can define your own GroupId and use it exclusively for non-real-person faces (including virtual humans).

Three integration scenarios โ€‹

ScenarioStepsReference
โ‘  Real-person materialsStart liveness verification โ†’ query result โ†’ create material (real-person asset) โ†’ query material result โ†’ create video task โ†’ query taskReal-person materials
โ‘ก Non-real-person materials (incl. virtual humans)Create material (optional) โ†’ query material result โ†’ create video task โ†’ query taskNon-real-person materials
โ‘ข Other (general video generation)Create video task โ†’ query taskRequest Examples

Notes for short-drama scenarios:

  • Whether a material contains a face is hard to determine reliably, so register every material before referencing it.
  • Add a cache so materials can be reused instead of registered repeatedly.

Key Parameters โ€‹

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID. Customers who activated VOD on or after 2023-12-25 must pass the application ID when accessing resources in a VOD application (default or newly created). Example: 251007502
ModelNameYesStringModel name, fixed to VS
ModelVersionNoStringModel version: 2.0 / 2.0-fast / 2.0-mini / 2.5 / 2.5-flash
PromptNoStringInput prompt. Required when FileInfos is empty
FileInfos.NNoArrayReference materials. Usage is FirstFrame, LastFrame or Reference
FileInfos.N.TypeNoStringFile (VOD media file) or Url (accessible URL)
FileInfos.N.CategoryNoStringImage / Video / Audio
FileInfos.N.FileIdNoStringVOD media ID when Type=File
FileInfos.N.UrlNoStringFile address when Type=Url; use asset://asset-xxx to reference a registered material
OutputConfig.ResolutionNoString480P / 720P / 1080P / 2K / 4K. Same values for all versions
OutputConfig.DurationNoFloatOutput length in seconds. 4~15 for the 2.0 series, 4~30 for 2.5 / 2.5-flash; pass -1 to let the model decide
OutputConfig.AspectRatioNoString21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive
OutputConfig.AudioGenerationNoStringEnabled to generate audio with video, Disabled to turn it off
OutputConfig.LogoAddNoStringEnabled to add a logo watermark, Disabled to turn it off
OutputConfig.StorageModeNoStringTemporary / Permanent
OutputConfig.SeedNoIntegerRandom seed. The same seed and inputs reproduce the result. Example: 123
ExtInfoNoStringExtension parameters, must be escaped. See the table below

ExtInfo options โ€‹

ExtInfo is a JSON string whose AdditionalParameters field is itself a JSON string, so the value is escaped twice.

PurposeValue
Enable high-bitrate output"{\"AdditionalParameters\":\"{\\\"bitrate_mode\\\":\\\"high\\\"}\"}"
Return the last frame image (see Return the last frame)"{\"AdditionalParameters\":\"{\\\"return_last_frame\\\":true}\"}"
Enable draft mode (see Draft mode)"{\"AdditionalParameters\":\"{\\\"draft\\\":true}\"}"
Specify a draft task ID (see Draft mode){"AdditionalParameters":"{\"draft_task_id\":\"1500013788-AigcVideoTask-*****2e4ae72f86db173at\"}"}
Task type hint omni_reference_task_type (edit / reference / extend)"{\"AdditionalParameters\":\"{\\\"omni_reference_task_type\\\":\\\"extend\\\"}\"}"
Specify a material group asset_group_id (see Direct material group reference)"{\"AdditionalParameters\": \"{\\\"asset_group_id\\\": \\\"my-asset-group\\\"}\"}"

Values of omni_reference_task_type:

ValueMeaning and constraints
autoThe model decides the task type from the input materials and prompt
referenceReference-to-video: generate a new video from reference images, videos or audio. No special restriction on ratio or duration
editVideo editing: edit the picture or audio of the source video. Must contain at least one reference_video of 4~30 seconds; ratio must be adaptive; duration must be -1
extendVideo extension: extend the source video forwards or backwards. Must contain at least one reference_video; ratio must be adaptive

Main APIs โ€‹

#APIDocumentationDescription
1CreateAigcVideoTaskCreate AIGC video taskGeneral AIGC video generation API supporting custom models. Returns a TaskId; get the result by polling or via callback
2CreateAigcLivenessValidateSee Start liveness verificationStart liveness verification
3DescribeAigcLivenessValidateResultSee Query the liveness resultQuery the liveness verification result
4CreateAigcMaterialSee Create a real-person materialCreate a material (real person / non-real person)
5DescribeTaskDetailDescribe task detailQuery material and video generation tasks. For video generation, prefer callbacks
6Normal callbackConfiguration: Callback settings
Structure: AigcVideoTask
Pushes the result when the task completes. Recommended
7Reliable event notificationConfiguration: Callback settings
API: Pull event notifications
Pull events on demand. Recommended

Upstream model documentation: https://docs.volcengine.com/docs/82379/2291680

Request Examples โ€‹

General video generation โ€‹

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.0",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/1.png",
      "Usage": "Reference"
    }
  ],
  "Prompt": "A man is taking a walk",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "720P",
    "Duration": 5,
    "AspectRatio": "16:9",
    "AudioGeneration": "Disabled"
  }
}

High-bitrate output โ€‹

Set bitrate_mode to high in ExtInfo.

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

First-frame to video โ€‹

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.0",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/1.png",
      "Usage": "FirstFrame"
    }
  ],
  "Prompt": "A man is taking a walk"
}

First-and-last-frame to video โ€‹

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": "A man is taking a walk"
}

Task type hint (video editing / video extension) โ€‹

Pass the official omni_reference_task_type through the extension parameters. The example below extends a video:

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 sample โ€‹

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 = "A cat playing in the sunlight, slow motion, cinematic"

    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 Example โ€‹

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

Query the task result โ€‹

Once you have the TaskId, call DescribeTaskDetail. For video generation, prefer a normal callback or reliable event notification over tight polling.

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

Video generation results are returned in Response.AigcVideoTask:

FieldDescription
StatusPROCESSING / FINISH / FAIL
ErrCode / MessageError code and description on failure
Output.FileInfos[].FileUrlAddress of the generated output
Output.FileInfos[].UsageTypeEmpty string for the generated video; last_frame_url for the last frame image
Output.FileInfos[].MetaDataDuration, bitrate, resolution, codec and other media info

Scenario Examples โ€‹

Return the last frame image โ€‹

Step 1: set return_last_frame in ExtInfo when creating the task.

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.0",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/1.png",
      "Usage": "Reference"
    }
  ],
  "Prompt": "A man is taking a walk",
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"return_last_frame\\\":true}\"}"
}

Step 2: query the task result. AigcVideoTask.Output.FileInfos then contains two records โ€” the generated video (UsageType empty) and the last frame image (UsageType is last_frame_url).

Draft mode โ€‹

Draft is a two-step "validate cheaply, then render at full quality" workflow: generate a low-resolution preview first to validate scene structure, camera movement, subject motion and prompt intent, then produce the final video from the draft task ID.

Step 1: create a draft task with draft in ExtInfo and 480P resolution.

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.5",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/1.png",
      "Usage": "Reference"
    }
  ],
  "Prompt": "A man is taking a walk",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "480P"
  },
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"draft\\\":true}\"}"
}

Step 2: pass the TaskId from step 1 as draft_task_id and set the resolution to 1080P.

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.5",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P"
  },
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"draft_task_id\\\":\\\"1500013788-AigcVideoTask-*****2e4ae72f86db173at\\\"}\"}"
}

Do not send Prompt in step 2

With draft_task_id you must not send Prompt, FileInfos or similar parameters โ€” even if the values are identical to the draft stage, the request fails.

Direct material group reference โ€‹

Specify the image URL in FileInfos and pass asset_group_id in ExtInfo.AdditionalParameters to provide both the reference image and the material group in one request.

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.5",
  "Prompt": "The character in the reference image smiles gently and takes a slow step forward, keeping the clothing and the candy-world background, static camera",
  "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\\\"}\"}"
}

Reuse a registered material โ€‹

Register the image with CreateAigcMaterial, read the AssetId from DescribeTaskDetail, then pass asset://asset-xxx in Url to reuse it without registering again.

Reference count limit โ€‹

FileInfos accepts up to 50 references for ModelVersion=2.5 (30 images + 10 videos + 10 audio clips), and up to 20 for ModelVersion=2.5-flash (10 images + 5 videos + 5 audio clips).

Real-person materials โ€‹

Step 1: start liveness verification โ€‹

Call CreateAigcLivenessValidate; replace SubAppId with your own application ID.

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

The response returns H5Link and LivenessToken:

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

Step 2: query the liveness result โ€‹

Have the user open H5Link in a browser and complete verification, then query DescribeAigcLivenessValidateResult with the LivenessToken.

json
{
  "SubAppId": 123456789,
  "LivenessToken": "2*******************************6B"
}
json
{
  "Response": {
    "GroupId": "group-*************",
    "LivenessToken": "2*******************C",
    "Message": "ok",
    "Status": "DONE",
    "RequestId": "a82*************b38"
  }
}

The returned GroupId maps one-to-one to that face and must be used when creating the real-person material.

Step 3: create a real-person material โ€‹

Call CreateAigcMaterial with the GroupId from step 2 and IsRealPerson set to "True".

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
FileInfo.TypeYesStringInput type, Url
FileInfo.UrlYesStringMaterial URL
AssetTypeYesStringImage / Video / Audio
GroupIdYesStringMaterial group ID. Real-person materials must use the GroupId returned by liveness verification
AssetNameNoStringMaterial name
IsRealPersonNoString"True" for real people, "False" otherwise
GroupNameNoStringMaterial group name
GroupDescriptionNoStringMaterial group description
SessionIdNoStringSession ID; must be unique or the request fails
SessionContextNoStringSession context, returned as-is in callbacks or queries
TasksPriorityNoIntegerTask priority; higher values run first
ExtInfoNoStringExtension parameters, reserved
json
{
  "SubAppId": 123456789,
  "FileInfo": {
    "Type": "Url",
    "Url": "https://example.com/person.png"
  },
  "AssetType": "Image",
  "GroupId": "group-*************",
  "AssetName": "host-a",
  "IsRealPerson": "True",
  "GroupName": "real-person-group",
  "GroupDescription": "real person materials",
  "SessionId": "session-001",
  "SessionContext": "material submitted by user A",
  "TasksPriority": 10
}

Step 4: query the material creation result โ€‹

Call DescribeTaskDetail with the TaskId returned by the creation call. The result is in Response.CreateAigcMaterialTask, and Output.AssetId is the material ID used for video generation.

json
{
  "Response": {
    "AigcVideoTask": null,
    "CreateAigcMaterialTask": {
      "Status": "FINISH",
      "ErrCode": 0,
      "Input": {
        "AssetName": "host-a",
        "AssetType": "Image",
        "GroupId": "group-*************",
        "IsRealPerson": "True"
      },
      "Output": {
        "AssetId": "asset-********",
        "AssetUrl": "url",
        "GroupId": "group-*************"
      },
      "TaskId": "123456-CreateAigcMaterial-521c5f8288cd523e7ca27db213676ad0t"
    },
    "RequestId": "0e3c78d4-dbd6-4519-a1c6-0adfa06a67ef"
  }
}

Step 5: generate video with the real-person material โ€‹

Pass asset://asset-xxx as FileInfos.N.Url.

ParameterValue
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.Duration4~15 for the 2.0 series, 4~30 for 2.5 / 2.5-flash
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": "Host A introduces a new product in a livestream, camera slowly pushes in",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Usage": "Reference",
      "Url": "asset://asset-********"
    }
  ],
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P",
    "Duration": 5,
    "AspectRatio": "16:9",
    "AudioGeneration": "Disabled"
  }
}

Step 6: query the task result โ€‹

Call DescribeTaskDetail with the returned TaskId; see Query the task result.

Non-real-person materials โ€‹

Step 1: create a non-real-person material โ€‹

Call CreateAigcMaterial with IsRealPerson set to "False"; GroupId can be any value you choose.

json
{
  "SubAppId": 123456789,
  "FileInfo": {
    "Type": "Url",
    "Url": "https://example.com/virtual-human.png"
  },
  "AssetType": "Image",
  "GroupId": "my-virtual-group",
  "AssetName": "virtual-character-b",
  "IsRealPerson": "False",
  "GroupName": "virtual-human-group"
}

AssetType accepts Image / Video / Audio.

Step 2: query the material creation result โ€‹

Query with DescribeTaskDetail and read Output.AssetId.

Step 3: generate video with the material โ€‹

json
{
  "SubAppId": 123456789,
  "ModelName": "VS",
  "ModelVersion": "2.5",
  "Prompt": "Virtual character B waves on a neon-lit street, cyberpunk style",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Usage": "Reference",
      "Url": "asset://asset-********"
    }
  ],
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P",
    "Duration": 5,
    "AspectRatio": "16:9"
  }
}

Step 4: query the task result โ€‹

See Query the task result.

Material Management APIs โ€‹

DescribeAigcMaterial โ€‹

Query a single material.

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
AssetIdYesStringMaterial ID to query
json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

DeleteAigcMaterial โ€‹

Delete a material. Passing GroupId deletes every material in that group.

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
AssetIdNoStringMaterial ID to delete
GroupIdNoStringMaterial group ID to delete, including all materials in it
json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

ModifyAigcMaterial โ€‹

Rename a material.

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
AssetIdYesStringMaterial ID to modify
AssetNameYesStringNew material name

Returns AssetId.

json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********",
  "AssetName": "host-a-front"
}

ModifyAigcMaterialGroup โ€‹

Rename a material group and update its description.

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringMaterial group ID to modify
GroupNameNoStringNew group name
GroupDescriptionNoStringNew group description

Returns GroupId.

json
{
  "SubAppId": 123456789,
  "GroupId": "my-virtual-group",
  "GroupName": "virtual-human-group",
  "GroupDescription": "all virtual human materials"
}

DescribeAigcMaterialGroup โ€‹

Query material group information.

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringMaterial group ID to query

Response fields:

FieldTypeDescription
GroupIdStringMaterial group ID
GroupNameStringMaterial group name
GroupDescriptionStringMaterial group description
GroupTypeStringMaterial group type
CreateTimeStringCreation time, ISO 8601 (UTC)
UpdateTimeStringUpdate time, ISO 8601 (UTC)
json
{
  "SubAppId": 123456789,
  "GroupId": "my-virtual-group"
}

DescribeAigcMaterialList โ€‹

Query a material list, filtered by group and type, paginated with Offset / Limit.

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringMaterial group ID; only materials in this group are returned
AssetTypeNoStringFilter by type: Image / Video / Audio
LimitNoIntegerPage size in [0, 300]; 0 means the default of 10
OffsetNoIntegerOffset, default 0; must be a multiple of Limit

Response fields:

FieldTypeDescription
TotalCountIntegerTotal number of materials matching the filter
AssetInfoListArrayMaterial list, structure below

AigcMaterialAssetInfo:

FieldTypeDescription
AssetIdStringMaterial ID
AssetNameStringMaterial name
AssetTypeStringImage / Video / Audio
AssetUrlStringMaterial URL
GroupIdStringMaterial group ID
StatusStringMaterial status
CreateTimeStringCreation time, ISO 8601 (UTC)
json
{
  "SubAppId": 123456789,
  "GroupId": "my-virtual-group",
  "AssetType": "Image",
  "Limit": 10,
  "Offset": 0
}

CreateAigcMaterialGroup โ€‹

Create a material group.

ParameterRequiredTypeDescription
GroupNameNoStringMaterial group name
GroupDescriptionNoStringMaterial group description

Returns GroupId (the material group ID).

json
{
  "GroupName": "my-virtual-group",
  "GroupDescription": "centralized management of virtual human materials"
}

DescribeAigcMaterialGroupList โ€‹

Query a material group list, paginated with Offset / Limit, returning group information and the total count.

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
LimitNoIntegerPage size in [0, 300]; 0 means the default of 10
OffsetNoIntegerOffset, default 0; must be a multiple of Limit, or a multiple of the default 10 when Limit is 0

Response fields:

FieldTypeDescription
TotalCountIntegerTotal number of material groups matching the filter
GroupInfoListArrayMaterial group list, structure below

AigcMaterialGroupInfo:

FieldTypeDescription
GroupIdStringMaterial group ID
GroupNameStringMaterial group name
GroupDescriptionStringMaterial group description
IsRealPersonStringWhether it is a real-person material group: True / False
CreateTimeStringCreation time, ISO 8601 (UTC)
UpdateTimeStringUpdate time, ISO 8601 (UTC)
json
{
  "SubAppId": 123456789,
  "Limit": 10,
  "Offset": 0
}

Common Errors โ€‹

#ErrorSolution
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.The URL you referenced directly contains a face. Create a material (asset) with CreateAigcMaterial and reference the asset:// address instead โ€” see Materials and face consistency
2code:OutputAudioSensitiveContentDetected, message:The request failed because the output audio may contain sensitive informationWith audio generation enabled, the output may contain copyrighted music that moderation then blocks. Upstream recommendations: โ‘  drop audio and generate video only; โ‘ก use your own non-copyrighted reference audio; โ‘ข state in the prompt that no copyrighted music should be used (helps, but only slightly)

Built with VitePress ยท Deployed on Tencent EdgeOne Pages