Skip to content

Vega Video HOT โ€‹

Updated

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.

Basic Information โ€‹

ItemValue
ModelNamewand-vega-video
ModelVersion1.5-pro / 1.5-lite / 1.0-pro / 1.0-pro-fast / 1.0-pro-mini / 1.0-lite
Input modesText / First & last frame / Image / Video / Audio reference
Output soundSupported (AudioGeneration: Enabled)
Real-person material referencePro versions only; register the image as a material (asset://) first. See Real-Person Material Integration
Guardrail bypass supportSupported

Supported Specifications by Version โ€‹

VersionResolutionAspect ratioDuration
1.5-pro720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~30 seconds
1.5-lite480P / 720P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive2~30 seconds / -1 model-selected
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 seconds
1.0-lite480P / 768P / 1080P / 2K / 4K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive4~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.

StepChinese mainland siteInternational site
Activate VODVOD consoleVOD console
Get SecretId / SecretKeyAPI key managementAPI key management
Get SubAppIdA default application is created when VOD is activated; you can also create another one. See Application SystemSame. See Application System
API hostvod.tencentcloudapi.comvod.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.

ScenarioApplies toCall chainSection
โ‘  Real-person materialReal people on the Chinese mainland siteStart liveness check โ†’ Query check result โ†’ Create real-person material โ†’ Query material result โ†’ Create video task โ†’ Query task resultReal-Person Material Integration
โ‘ก Non-real-person materialNon-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 resultNon-Real-Person and International Site Materials
โ‘ข General video generationMaterials without faces, on both sitesCreate video task โ†’ Query task resultPer-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:

SourceUsed forConstraint
GroupId returned by the liveness checkScenario โ‘  (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 GroupIdScenario โ‘ก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 AssetId and reuse it; there is no need to register it again.

Main APIs โ€‹

APIPurposeChinese mainland site docsInternational site docs
CreateAigcVideoTaskCreates a video generation task and returns a TaskIdCreate AIGC video taskCreateAigcVideoTask
CreateAigcLivenessValidateStarts a liveness checkSee Real-Person Material IntegrationNot needed on the international site
DescribeAigcLivenessValidateResultQueries the liveness check resultSee Real-Person Material IntegrationNot needed on the international site
CreateAigcMaterialCreates a material (real or non-real person)See Real-Person Material IntegrationSee Non-Real-Person and International Site Materials
DescribeTaskDetailQueries the result of material creation, video generation and other tasksQuery task detailsDescribeTaskDetail
Standard callbackPushes the result when a task finishes. RecommendedCallback settings ยท AigcVideoTask structureCallback Settings
Reliable callbackPulls event notifications. RecommendedPull event notificationsPullEvents

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.

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD 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
CallbackUrlNoStringCallback URL notified when the check finishes, for example https://example.com/callback
json
{
  "SubAppId": 123456789,
  "CallbackUrl": "https://example.com/callback"
}

The response returns H5Link (the liveness check page) and LivenessToken (the query credential):

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

Step 2: Query the Liveness Check Result โ€‹

  1. Have the person being verified open H5Link in a mobile browser and complete the liveness check.
  2. When the check is done, call DescribeAigcLivenessValidateResult with the LivenessToken.
ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
LivenessTokenYesStringThe LivenessToken returned in Step 1
json
{
  "SubAppId": 123456789,
  "LivenessToken": "2*******************************6B"
}
json
{
  "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.

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
FileInfo.TypeYesStringInput type. Value: Url
FileInfo.UrlYesStringURL of the material file
AssetTypeYesStringMaterial type: Image / Video / Audio
GroupIdYesStringMaterial group ID. A real-person material must use the GroupId returned by the liveness check
AssetNameNoStringMaterial name, user-defined
IsRealPersonNoString"True": a real person; "False": not a real person (including virtual humans). Note that this is a string, not a boolean
GroupNameNoStringMaterial group name, user-defined
GroupDescriptionNoStringMaterial group description, user-defined
SessionIdNoStringSession ID used for deduplication. It must be unique; a duplicate returns an error
SessionContextNoStringUser-defined session context, returned as-is in callbacks and task queries
TasksPriorityNoIntegerTask priority. A larger value means a higher priority. Example: 10
ExtInfoNoStringExtension parameter, reserved
json
{
  "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
}
json
{
  "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.

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

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

ParameterValue
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, matching the material's AssetType
FileInfos.N.UsageReference / FirstFrame / LastFrame
OutputConfig.Resolution1.5-pro: 720P / 1080P / 2K / 4K; 1.0-pro family: 480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration1.5-pro: 4~30; 1.0-pro family: 4~15; -1 lets the model decide
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": "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"
  }
}
json
{
  "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.

json
{
  "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 โ€‹

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

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

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.

APIPurpose
DescribeAigcMaterialQueries a single material
DescribeAigcMaterialListLists materials with paging, filtered by group or type
ModifyAigcMaterialRenames a material
DeleteAigcMaterialDeletes a single material or an entire group
CreateAigcMaterialGroupCreates a material group
DescribeAigcMaterialGroupQueries a material group
DescribeAigcMaterialGroupListLists material groups with paging
ModifyAigcMaterialGroupChanges a group's name and description

DescribeAigcMaterial โ€‹

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
AssetIdYesStringID of the material to query
json
{
  "SubAppId": 123456789,
  "AssetId": "asset-********"
}

DescribeAigcMaterialList โ€‹

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringMaterial group ID. Only materials in this group are returned
AssetTypeNoStringFilter by type: Image / Video / Audio
LimitNoIntegerRecords per page, [0, 300]. 0 uses the default of 10
OffsetNoIntegerStarting offset, default 0. Must be a multiple of Limit

Returns TotalCount (the number of matching materials) and AssetInfoList. Each item in AssetInfoList has:

FieldTypeDescription
AssetIdStringMaterial ID
AssetNameStringMaterial name
AssetTypeStringImage / Video / Audio
AssetUrlStringMaterial access URL
GroupIdStringID of the group the material belongs to
StatusStringMaterial status
CreateTimeStringCreation time, ISO 8601 (UTC)
json
{
  "SubAppId": 123456789,
  "GroupId": "my-character-group",
  "AssetType": "Image",
  "Limit": 10,
  "Offset": 0
}

ModifyAigcMaterial โ€‹

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
AssetIdYesStringID of the material to modify
AssetNameYesStringNew material name

Returns AssetId.

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

DeleteAigcMaterial โ€‹

ParameterRequiredTypeDescription
SubAppIdYesIntegerVOD application ID
AssetIdNoStringID of the material to delete
GroupIdNoStringID 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.

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

CreateAigcMaterialGroup โ€‹

ParameterRequiredTypeDescription
GroupNameNoStringMaterial group name
GroupDescriptionNoStringMaterial group description

Returns GroupId.

json
{
  "GroupName": "character-group",
  "GroupDescription": "Short-drama character materials"
}

DescribeAigcMaterialGroup โ€‹

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringID of the material group to query

Returns GroupId, GroupName, GroupDescription, GroupType (the group type), CreateTime and UpdateTime (both ISO 8601, UTC).

json
{
  "SubAppId": 123456789,
  "GroupId": "my-character-group"
}

DescribeAigcMaterialGroupList โ€‹

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
LimitNoIntegerRecords per page, [0, 300]. 0 uses the default of 10
OffsetNoIntegerStarting 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:

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

ModifyAigcMaterialGroup โ€‹

ParameterRequiredTypeDescription
SubAppIdNoIntegerVOD application ID
GroupIdYesStringID of the material group to modify
GroupNameNoStringNew group name
GroupDescriptionNoStringNew group description

Returns GroupId.

json
{
  "SubAppId": 123456789,
  "GroupId": "my-character-group",
  "GroupName": "character-group",
  "GroupDescription": "Short-drama character materials, managed together"
}

Common Errors โ€‹

Error messageCauseFix
The request failed because the input image may contain real person.The video request references a URL that contains a real person's face directlyRegister 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 GroupIdEach liveness-check GroupId accepts only its own face. For a different person, start a new liveness check to get a new GroupId
OutputAudioSensitiveContentDetectedThe 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)

Built with VitePress ยท Deployed on Tencent EdgeOne Pages