Vega Video HOT โ
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Vega Video is WAND's in-house video generation model. It supports text-to-video, first-frame / last-frame / first-and-last-frame generation, and multimodal reference generation from mixed image, video and audio inputs, and can generate audio alongside the video. The Pro series also supports editing and extending a reference video, with output up to 4K and up to 30 seconds per clip. 1.5-pro additionally supports a two-step draft preview: render a 480P draft first, then produce the final video from that draft task.
Choose a Version โ
The API docs are split by version. Open a card for that version's input specifications, request parameters, request examples and special settings.
1.5-pro- 720Pโ4K, 4โ30 s per clip
- Up to 30 images, 10 videos, 10 audio clips
- Edit / extend a reference video
- Two-step draft preview (480P โ final)
1.5-lite- 480Pโ4K, 2โ30 s or model-selected duration
- Up to 10 images, 5 videos and 5 audio clips
- Audio generation and multimodal reference
1.0-pro ยท 1.0-pro-fast ยท 1.0-pro-mini- 480Pโ4K, 4โ15 s per clip
- Up to 9 images, 3 videos, 3 audio clips
- Standard, fast and mini variants
1.0-lite- 480Pโ4K, 4โ15 s per clip
- Up to 12 image / video / audio inputs
- Fast and cinematic modes
Basic Information โ
| Item | Value |
|---|---|
| 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 |
| Input modes | Text / First & last frame / Image / Video / Audio reference |
| Output sound | Supported (AudioGeneration: Enabled) |
| Real-person material reference | Pro versions only; register the image as a material (asset://) first. See Real-Person Material Integration |
| Guardrail bypass support | Supported |
Supported Specifications by Version โ
| Version | Resolution | Aspect ratio | Duration |
|---|---|---|---|
1.5-pro | 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~30 seconds |
1.5-lite | 480P / 720P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 2~30 seconds / -1 model-selected |
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 seconds |
1.0-lite | 480P / 768P / 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive | 4~15 seconds |
All six ModelVersion values share the CreateAigcVideoTask API and ModelName: wand-vega-video. The three 1.0 Pro variants share one specification page.
Before You Start โ
Allowlist required
The Vega Video Pro series must be allowlisted before you can call it. Contact the WAND team with your APPID and UIN.
| Step | Chinese mainland site | International site |
|---|---|---|
| Activate VOD | VOD console | VOD console |
| Get SecretId / SecretKey | API key management | API key management |
Get SubAppId | A default application is created when VOD is activated; you can also create another one. See Application System | Same. See Application System |
| API host | vod.tencentcloudapi.com | vod.intl.tencentcloudapi.com |
The request bodies on this page work on both sites. To switch sites, change only the host.
Integration Scenarios โ
When a reference image contains a real person's face, portrait rights and copyright apply, so the platform handles it through materials (assets). First call CreateAigcMaterial to register the file URL as a material. Once you have the AssetId, reference it as asset://<AssetId> in FileInfos.N.Url of the video request instead of passing the original URL. A raw URL containing a real person's face is rejected; see Common Errors for the error.
| Scenario | Applies to | Call chain | Section |
|---|---|---|---|
| โ Real-person material | Real people on the Chinese mainland site | Start liveness check โ Query check result โ Create real-person material โ Query material result โ Create video task โ Query task result | Real-Person Material Integration |
| โก Non-real-person material | Non-real people / virtual humans on the Chinese mainland site; real people on the Chinese mainland site whose account is allowlisted to skip the liveness check; all materials on the international site (real and non-real people) | Create material โ Query material result โ Create video task โ Query task result | Non-Real-Person and International Site Materials |
| โข General video generation | Materials without faces, on both sites | Create video task โ Query task result | Per-version API docs (see the version cards above) |
No liveness check on the international site
The international site has no liveness check API. Whether the material shows a real person, a non-real person or a virtual human, integrate it as scenario โก on the international site: use a custom GroupId and pass "False" for IsRealPerson.
GroupId Rules โ
Every material belongs to a material group (GroupId). A group comes from one of two sources, with different rules:
| Source | Used for | Constraint |
|---|---|---|
GroupId returned by the liveness check | Scenario โ (real people, Chinese mainland site) | Bound one-to-one to the verified face and accepts only materials of that face. Any other face fails with Face consistency verification failed. |
Custom GroupId | Scenario โก | Pass "False" for IsRealPerson when creating the material. A GroupId used for the first time creates the group automatically; you can also create it first with CreateAigcMaterialGroup |
Version Support โ
asset:// material references are supported only on the Pro versions: 1.5-pro, 1.0-pro, 1.0-pro-fast and 1.0-pro-mini. The Lite versions (1.5-lite, 1.0-lite) do not support them.
Batch and Short-Drama Recommendations โ
- It is often hard to tell reliably whether a material contains a face. Register every material before referencing it instead of deciding image by image which path to take.
- The same character usually appears across many tasks. Cache the
AssetIdand reuse it; there is no need to register it again.
Main APIs โ
| API | Purpose | Chinese mainland site docs | International site docs |
|---|---|---|---|
CreateAigcVideoTask | Creates a video generation task and returns a TaskId | Create AIGC video task | CreateAigcVideoTask |
CreateAigcLivenessValidate | Starts a liveness check | See Real-Person Material Integration | Not needed on the international site |
DescribeAigcLivenessValidateResult | Queries the liveness check result | See Real-Person Material Integration | Not needed on the international site |
CreateAigcMaterial | Creates a material (real or non-real person) | See Real-Person Material Integration | See Non-Real-Person and International Site Materials |
DescribeTaskDetail | Queries the result of material creation, video generation and other tasks | Query task details | DescribeTaskDetail |
| Standard callback | Pushes the result when a task finishes. Recommended | Callback settings ยท AigcVideoTask structure | Callback Settings |
| Reliable callback | Pulls event notifications. Recommended | Pull event notifications | PullEvents |
Video generation tasks take a while. Prefer callbacks to receive results, and use DescribeTaskDetail polling as a fallback. For querying, modifying and deleting materials, see Material Management APIs.
Real-Person Material Integration โ
This section covers scenario โ and applies only to the Chinese mainland site (host vod.tencentcloudapi.com). All request bodies below are JSON; the SDK handles the common request parameters (signature headers such as X-TC-Action).
Step 1: Start a Liveness Check โ
Call CreateAigcLivenessValidate.
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Yes | Integer | VOD application ID. Customers who activated VOD on or after December 25, 2023 must set it when accessing resources in any application, default or newly created. Example: 251007502 |
CallbackUrl | No | String | Callback URL notified when the check finishes, for example https://example.com/callback |
{
"SubAppId": 123456789,
"CallbackUrl": "https://example.com/callback"
}The response returns H5Link (the liveness check page) and LivenessToken (the query credential):
{
"Response": {
"H5Link": "https://**************",
"LivenessToken": "2*******************************6B",
"RequestId": "76002966-e3f7-4156-a234-8a005046e6b7"
}
}Step 2: Query the Liveness Check Result โ
- Have the person being verified open
H5Linkin a mobile browser and complete the liveness check. - When the check is done, call
DescribeAigcLivenessValidateResultwith theLivenessToken.
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Yes | Integer | VOD application ID |
LivenessToken | Yes | String | The LivenessToken returned in Step 1 |
{
"SubAppId": 123456789,
"LivenessToken": "2*******************************6B"
}{
"Response": {
"GroupId": "group-*************",
"LivenessToken": "2*******************************6B",
"Message": "ok",
"Status": "DONE",
"RequestId": "a82*************b38"
}
}Status of DONE means the check passed. The returned GroupId is bound one-to-one to this face, and you must use it when creating the real-person material in the next step.
Step 3: Create a Real-Person Material โ
Call CreateAigcMaterial with the GroupId from Step 2 and pass "True" for IsRealPerson.
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Yes | Integer | VOD application ID |
FileInfo.Type | Yes | String | Input type. Value: Url |
FileInfo.Url | Yes | String | URL of the material file |
AssetType | Yes | String | Material type: Image / Video / Audio |
GroupId | Yes | String | Material group ID. A real-person material must use the GroupId returned by the liveness check |
AssetName | No | String | Material name, user-defined |
IsRealPerson | No | String | "True": a real person; "False": not a real person (including virtual humans). Note that this is a string, not a boolean |
GroupName | No | String | Material group name, user-defined |
GroupDescription | No | String | Material group description, user-defined |
SessionId | No | String | Session ID used for deduplication. It must be unique; a duplicate returns an error |
SessionContext | No | String | User-defined session context, returned as-is in callbacks and task queries |
TasksPriority | No | Integer | Task priority. A larger value means a higher priority. Example: 10 |
ExtInfo | No | String | Extension parameter, reserved |
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/person.jpg"
},
"AssetType": "Image",
"GroupId": "group-*************",
"AssetName": "host-a",
"IsRealPerson": "True",
"GroupName": "real-person-group",
"GroupDescription": "Real-person materials of host A",
"SessionId": "session-001",
"SessionContext": "submitted by user A",
"TasksPriority": 10
}{
"Response": {
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft",
"RequestId": "5f3537a2-b069-4b07-ab0d-9861f877ee12"
}
}Material creation is asynchronous. The response returns only a TaskId; the AssetId is not available yet.
Step 4: Query the Material Creation Result โ
Call DescribeTaskDetail with the TaskId from Step 3.
{
"SubAppId": 123456789,
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft"
}The result is in Response.CreateAigcMaterialTask. When Status is FINISH and ErrCode is 0, Output.AssetId is the material ID to reference in video generation (other task fields that are null are omitted below):
{
"Response": {
"CreateAigcMaterialTask": {
"TaskId": "123456-CreateAigcMaterial-6ae386*************************ft",
"Status": "FINISH",
"ErrCode": 0,
"Message": "",
"Progress": 100,
"Input": {
"AssetName": "host-a",
"AssetType": "Image",
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/person.jpg"
},
"GroupId": "group-*************",
"GroupName": "real-person-group",
"IsRealPerson": "True"
},
"Output": {
"AssetId": "asset-********",
"AssetUrl": "https://...",
"GroupId": "group-*************"
}
},
"RequestId": "0e3c78d4-dbd6-4519-a1c6-0adfa06a67ef"
}
}Step 5: Generate a Video with the Real-Person Material โ
Call CreateAigcVideoTask and pass the material as asset://<AssetId> in FileInfos.N.Url, keeping Type as Url. All other parameters are the same as for normal video generation, within the ranges of the version you choose.
| Parameter | Value |
|---|---|
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, matching the material's AssetType |
FileInfos.N.Usage | Reference / FirstFrame / LastFrame |
OutputConfig.Resolution | 1.5-pro: 720P / 1080P / 2K / 4K; 1.0-pro family: 480P / 720P / 1080P / 2K / 4K |
OutputConfig.Duration | 1.5-pro: 4~30; 1.0-pro family: 4~15; -1 lets the model decide |
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": "Host A introduces a new product in a livestream studio, slow push-in",
"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"
}
}Step 6: Query the Video Result โ
Call DescribeTaskDetail with the TaskId from Step 5. The result is in Response.AigcVideoTask.Output.FileInfos. You can also receive it by callback; see Main APIs.
Non-Real-Person and International Site Materials โ
This section covers scenario โก and applies to:
- non-real-person and virtual-human materials on the Chinese mainland site;
- real-person materials on the Chinese mainland site whose account is allowlisted to skip the liveness check;
- all materials on the international site (real people, non-real people and virtual humans). The international host is
vod.intl.tencentcloudapi.com.
Compared with real-person integration, this scenario needs no liveness check: use a custom GroupId and always pass "False" for IsRealPerson.
Step 1: Create a Material โ
Call CreateAigcMaterial. The parameters are the same as in Step 3: Create a Real-Person Material.
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://example.com/character.png"
},
"AssetType": "Image",
"GroupId": "my-character-group",
"AssetName": "character-b",
"IsRealPerson": "False",
"GroupName": "character-group",
"GroupDescription": "Short-drama character materials"
}The response returns a TaskId.
Step 2: Query the Material Creation Result โ
Call DescribeTaskDetail with the TaskId and read the material ID from Response.CreateAigcMaterialTask.Output.AssetId, as in Step 4.
Step 3: Generate a Video with the Material โ
{
"SubAppId": 123456789,
"ModelName": "wand-vega-video",
"ModelVersion": "1.0-pro",
"Prompt": "Character B turns and waves on a neon-lit street",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "Reference",
"Url": "asset://asset-********"
}
],
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9"
}
}Step 4: Query the Video Result โ
Same as Step 6: Query the Video Result.
Direct Material Group Reference (asset_group_id) โ
If you prefer not to register the material first, you can pass the image URL directly in the video request and set a custom asset_group_id in ExtInfo.AdditionalParameters; the platform uploads the image into that group for you. A group ID used for the first time is created automatically.
{
"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\\\"}\"}"
}This takes a single CreateAigcVideoTask call and suits occasional use. If the same character appears in many tasks, register the material first and cache the AssetId for reuse. Real-person materials on the Chinese mainland site still follow scenario โ , Real-Person Material Integration.
Material Management APIs โ
The following APIs query, modify and delete materials and material groups. They work on both sites.
| API | Purpose |
|---|---|
DescribeAigcMaterial | Queries a single material |
DescribeAigcMaterialList | Lists materials with paging, filtered by group or type |
ModifyAigcMaterial | Renames a material |
DeleteAigcMaterial | Deletes a single material or an entire group |
CreateAigcMaterialGroup | Creates a material group |
DescribeAigcMaterialGroup | Queries a material group |
DescribeAigcMaterialGroupList | Lists material groups with paging |
ModifyAigcMaterialGroup | Changes a group's name and description |
DescribeAigcMaterial โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Yes | Integer | VOD application ID |
AssetId | Yes | String | ID of the material to query |
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}DescribeAigcMaterialList โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | No | Integer | VOD application ID |
GroupId | Yes | String | Material group ID. Only materials in this group are returned |
AssetType | No | String | Filter by type: Image / Video / Audio |
Limit | No | Integer | Records per page, [0, 300]. 0 uses the default of 10 |
Offset | No | Integer | Starting offset, default 0. Must be a multiple of Limit |
Returns TotalCount (the number of matching materials) and AssetInfoList. Each item in AssetInfoList has:
| Field | Type | Description |
|---|---|---|
AssetId | String | Material ID |
AssetName | String | Material name |
AssetType | String | Image / Video / Audio |
AssetUrl | String | Material access URL |
GroupId | String | ID of the group the material belongs to |
Status | String | Material status |
CreateTime | String | Creation time, ISO 8601 (UTC) |
{
"SubAppId": 123456789,
"GroupId": "my-character-group",
"AssetType": "Image",
"Limit": 10,
"Offset": 0
}ModifyAigcMaterial โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | No | Integer | VOD application ID |
AssetId | Yes | String | ID of the material to modify |
AssetName | Yes | String | New material name |
Returns AssetId.
{
"SubAppId": 123456789,
"AssetId": "asset-********",
"AssetName": "host-a-front"
}DeleteAigcMaterial โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Yes | Integer | VOD application ID |
AssetId | No | String | ID of the material to delete |
GroupId | No | String | ID of the material group to delete |
Passing GroupId deletes the whole group
When you pass GroupId, every material in that group is deleted. To delete a single material, pass only AssetId.
{
"SubAppId": 123456789,
"AssetId": "asset-********"
}CreateAigcMaterialGroup โ
| Parameter | Required | Type | Description |
|---|---|---|---|
GroupName | No | String | Material group name |
GroupDescription | No | String | Material group description |
Returns GroupId.
{
"GroupName": "character-group",
"GroupDescription": "Short-drama character materials"
}DescribeAigcMaterialGroup โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | No | Integer | VOD application ID |
GroupId | Yes | String | ID of the material group to query |
Returns GroupId, GroupName, GroupDescription, GroupType (the group type), CreateTime and UpdateTime (both ISO 8601, UTC).
{
"SubAppId": 123456789,
"GroupId": "my-character-group"
}DescribeAigcMaterialGroupList โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | No | Integer | VOD application ID |
Limit | No | Integer | Records per page, [0, 300]. 0 uses the default of 10 |
Offset | No | Integer | Starting offset, default 0. Must be a multiple of Limit; when Limit is 0, a multiple of 10. For example, Offset=20 with Limit=10 returns page 3 |
Returns TotalCount and GroupInfoList. Each item in GroupInfoList has:
| Field | Type | Description |
|---|---|---|
GroupId | String | Material group ID |
GroupName | String | Material group name |
GroupDescription | String | Material group description |
IsRealPerson | String | Whether this is a real-person group: True / False |
CreateTime | String | Creation time, ISO 8601 (UTC) |
UpdateTime | String | Update time, ISO 8601 (UTC) |
{
"SubAppId": 123456789,
"Limit": 10,
"Offset": 0
}ModifyAigcMaterialGroup โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | No | Integer | VOD application ID |
GroupId | Yes | String | ID of the material group to modify |
GroupName | No | String | New group name |
GroupDescription | No | String | New group description |
Returns GroupId.
{
"SubAppId": 123456789,
"GroupId": "my-character-group",
"GroupName": "character-group",
"GroupDescription": "Short-drama character materials, managed together"
}Common Errors โ
| Error message | Cause | Fix |
|---|---|---|
The request failed because the input image may contain real person. | The video request references a URL that contains a real person's face directly | Register it as a material first, then reference it as asset://<AssetId>. Real people on the Chinese mainland site follow Real-Person Material Integration; everything else follows Non-Real-Person and International Site Materials |
Face consistency verification failed. | When creating a real-person material, the face in the image does not match the face verified for that GroupId | Each liveness-check GroupId accepts only its own face. For a different person, start a new liveness check to get a new GroupId |
OutputAudioSensitiveContentDetected | The generated audio appears to contain copyrighted music and was blocked by output moderation | โ Turn off audio (AudioGeneration: Disabled) and generate video only; โก use reference audio you own or are licensed to use; โข state in the prompt that copyrighted music must not be used (helps somewhat, not guaranteed) |