API Reference โ
Authentication, request structure, task query, and storage specifications for VOD. For each model's values and examples, see the engine menu on the left.
Call Specifications โ
| Item | Value |
|---|---|
| Request | POST https://vod.intl.tencentcloudapi.com |
| API version | 2018-07-17 |
| Authentication | TC3-HMAC-SHA256 / SecretId / SecretKey |
| Content-Type | application/json; charset=utf-8 |
| Common headers | X-TC-Action / X-TC-Version / X-TC-Timestamp / X-TC-Region |
Text models use Bearer authentication and https://mmu.vod-qcloud.com. See the Text call specifications.
Generate / Query Actions โ
| Category | Action | Purpose |
|---|---|---|
| Generate | CreateAigcImageTask | Image generation |
| Generate | CreateAigcVideoTask | Video generation, 3D scene generation |
| Generate | CreateAigcAudioTask | Sound effect and music generation |
| Query | DescribeTaskDetail | Common query for all AIGC tasks |
Unlike MPS, the query action is unified into one.
Executing a Request โ
Save the TC3 call script as tencent-api.py. The script uses only the Python 3 standard library, and computes the signature on each request based on the current time and the request body. After setting the TENCENT_SECRET_ID / TENCENT_SECRET_KEY environment variables, save the JSON from the engine page as request.json.
python3 tencent-api.py vod CreateAigcImageTask request.jsonpython3 tencent-api.py vod CreateAigcVideoTask request.jsonpython3 tencent-api.py vod CreateAigcAudioTask request.jsonPOST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAigcImageTask
X-TC-Version: 2018-07-17
X-TC-Timestamp: <unix-timestamp>
X-TC-Region: ap-guangzhou
Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/vod/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<Signature>Generation requests incur actual usage charges. If you cannot confirm whether a request was accepted because of a timeout, query the task status before generating again. Temporary credentials can be specified via TENCENT_TOKEN, and the region via --region.
API List and Request Parameters โ
Common Fields โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Optional | Integer | VOD Application ID. A new Application requires the actual ID to be specified. |
ModelName | Required | String | Engine name |
ModelVersion | Optional | String | Engine version. The default version is used when omitted |
Prompt | Required | String | Generation prompt |
SceneType | Optional | String | Specify a special mode |
FileInfos.N | Optional | Array | Reference input. Type / Category / Usage / Url |
OutputConfig | Optional | Object | Resolution / Duration / AspectRatio / StorageMode, etc. |
ExtInfo | Optional | String | Advanced options. A string within 2, JSON-encoded |
The FileInfos.N Usage indicates the reference purpose.
| Usage | Meaning |
|---|---|
FirstFrame | First frame |
Reference | Reference input |
LastFrame | Last frame |
Models that support a last frame use FileInfos.N.Usage=LastFrame. LastFrameUrl / LastFrameFileId are fields kept for compatibility with legacy integrations.
Response and Execution Flow โ
Task Query โ
Query via DescribeTaskDetail. You must confirm both Status="FINISH" and ErrCode=0.
python3 tencent-api.py vod DescribeTaskDetail query.jsonquery.json:
{
"SubAppId": 0,
"TaskId": "<task-id>"
}| Status | Handling |
|---|---|
WAITING / PROCESSING | Continue polling |
FINISH | Success when ErrCode=0. On error, confirm Message |
| Type | Status | Result URL |
|---|---|---|
| Image | AigcImageTask.Status | AigcImageTask.Output.FileInfos.FileUrl |
| Video | AigcVideoTask.Status | AigcVideoTask.Output.FileInfos.FileUrl |
| Music | AigcAudioTask.Status | AigcAudioTask.Output.AudioInfos.FileUrl |
Acceptance Response โ
{
"Response": {
"TaskId": "<task-id>",
"RequestId": "<request-id>"
}
}TaskId is used for subsequent queries, and RequestId for request tracking.
Example Response โ
{
"AigcImageTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcImageGenFile.png",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1024,
"Height": 1024,
"Container": "png"
}
}
]
}
}
}{
"AigcVideoTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1920,
"Height": 1080,
"Duration": 5.07,
"Container": "mov,mp4,m4a",
"Bitrate": 9494850
}
}
]
}
}
}{
"AigcAudioTask": {
"Status": "FINISH",
"ErrCode": 0,
"Output": {
"AudioInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcAudioGenFile.mp3"
}
]
}
}
}Errors and Call Limits โ
Confirm the response's HTTP status, error code, and request identifier together. For authentication and permission errors, re-issue the request after confirming your configuration; if a task or resource has already been created, query the current status before resubmitting. For the limits and error codes of each API, see the related documents below.
Request Examples โ
Use the request example of the model or protocol you are calling. Do not mix authentication methods and request fields from different paths in the same request. Refer to both the engine documents below and the parameter descriptions for each protocol.
Result and Resource Management โ
Result Storage โ
| StorageMode | Validity |
|---|---|
Temporary | 7 days |
Permanent | Permanent. Registered as a VOD media asset |
Longer than the MPS path's 12 hours, and using Permanent lets you manage it directly as a VOD media asset.
{
"OutputConfig": {
"StorageMode": "Permanent"
}
}Disabling Guardrails โ
For video, it can be applied to Kling / Vidu / Wan / Happyhorse / Hailuo H3. It does not apply to other versions of Hailuo. For the supported range of WAND-Vega-Video, see the corresponding engine document. It does not apply to VS. It does not apply to Hy Image.
To use the guardrail disable parameter, first contact your sales representative to confirm usage permission. Even on supported engines, guardrails are disabled only when the parameter is passed explicitly. If the parameter is omitted, guardrails are not disabled.
| Parameter | Disable value | Applies to |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | Disable input moderation |
OutputConfig.OutputComplianceCheck | Disabled | Disable output moderation |
Merge the following configuration into an existing generation request. To disable both input and output moderation, pass both fields together.
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}MPS uses the Boolean value of ExtraParameters. Do not pass VOD's OutputConfig or the string Disabled as-is to MPS. See MPS API Reference.
Engine Catalog and Related Documentation โ
Image โ
Image generation called through the VOD path. The action is CreateAigcImageTask and the result query is DescribeTaskDetail. The action name is the same as the MPS path (mps-image), but the parameter structure differs.
WAND-Vega-Image integration
For WAND-Vega-Image's VOD request specification and generation examples, see WAND-Vega-Image.
Differences from the MPS Path โ
| Category | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API version | 2018-07-17 | 2019-06-12 |
| Reference image | FileInfos.N (Type + Url) | ImageInfos.N (ImageUrl) |
| Resolution / ratio | OutputConfig.Resolution / OutputConfig.AspectRatio | ExtraParameters.Resolution / ExtraParameters.AspectRatio |
| Number of outputs | OutputConfig.OutputImageCount | OutputImageCount (top level) |
| Engine-specific parameters | ExtInfo = {"AdditionalParameters": "<JSON string>"} (encoded in 2) | AdditionalParameters (JSON string, in 1) |
| Result query | DescribeTaskDetail | DescribeAigcImageTask |
| Status value | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| Result URL | Output.FileInfos.FileUrl + ExpireTime | ImageInfos.Url (COS presigned, 12 hours) |
Supported Engines โ
| Engine | ModelName | ModelVersion |
|---|---|---|
| Nano Banana | GEM | 3.6 / 3.1 / 3.1-lite / 3.0 / 2.5 |
| Hunyuan | Hunyuan | 3.5-preview / 3.0 |
| WAND-Vega-Image | wand-vega-image | 1.0-pro / 1.0-flash / 1.0-lite |
| Qwen | Qwen | 0925 |
| Seedream 5.x | SI | 5.5 / 5.0-flash / 5.0-pro |
| Seedream | Seedream | 5.0-lite / 4.5 / 4.0 |
| Kling | Kling | 4.0 / 4.0-long / 3.0-Omni / 3.0 / O1 / 2.1 |
| Jimeng | Jimeng | 4.0 |
| Midjourney | MJ | v8.2 / v8.1 / v7 / niji_7 |
| Vidu | Vidu | q2 |
| GPT-Image | OG | image2_* / image2.5_sunburst_* / image2.5_flare_* / image2.6_sunburst_* / image2.6_flare_* |
Common Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Optional | Integer | VOD Application ID |
ModelName | Required | String | Engine name |
ModelVersion | Optional | String | Engine version |
Prompt | Optional | String | Generation prompt. Required in text input mode |
NegativePrompt | Optional | String | Negative prompt |
SceneType | Optional | String | 3d_panorama (Hunyuan panorama), image_expand (Kling expansion), etc. |
FileInfos.N | Optional | Array | Reference image. Specify a mask via ReferenceType=mask |
OutputConfig | Optional | Object | Output settings |
ExtInfo | Optional | String | Engine-specific extension parameters |
SessionId | Optional | String | Key used for deduplication |
SessionContext | Optional | String | Callback pass-through value. Up to 1000 characters |
OutputConfig โ
| Field | Description |
|---|---|
Resolution | 1K / 2K / 4K, etc. The allowed values differ by engine |
AspectRatio | 1:1 / 16:9 / 9:16 / 4:3 / 3:4, etc. |
OutputImageCount | Number of outputs. For the allowed range of each model, see the detailed documentation |
OutputFormat | jpeg / png / webp. The model default is used when unspecified |
StorageMode | Temporary (7 days) / Permanent |
MediaName | Media name when StorageMode=Permanent |
PersonGeneration | AllowAdult / Disallowed. Whether to allow generating people |
InputComplianceCheck | Disables input moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use |
OutputComplianceCheck | Disables output moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use |
ExtInfo โ
As with video, image generation uses, within 2, the JSON encoding.
{
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\":\\\"1536x1024\\\"}\"}"
}Video โ
Video generation called through the VOD path. The action is CreateAigcVideoTask and the result query is DescribeTaskDetail.
Differences from the MPS Path โ
Even when the same engine name is used, the location where parameters are placed differs.
| Category | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API version | 2018-07-17 | 2019-06-12 |
| First frame | FileInfos.N + Usage=FirstFrame | ImageUrl |
| Last frame | FileInfos.N + Usage=LastFrame, or LastFrameUrl | LastImageUrl |
| Multiple reference images | FileInfos.N (Category + Usage) | ImageInfos.N |
| Reference video | FileInfos.N + Category=Video | VideoInfos.N |
| Video length | OutputConfig.Duration | Top level Duration |
| Resolution / ratio | OutputConfig.Resolution / OutputConfig.AspectRatio | ExtraParameters.Resolution / ExtraParameters.AspectRatio |
| Simultaneous audio generation | OutputConfig.AudioGeneration | ExtraParameters.EnableAudio |
| Engine-specific parameters | ExtInfo = {"AdditionalParameters": "<JSON string>"} (encoded in 2) | AdditionalParameters (JSON string, in 1) |
| Result query | DescribeTaskDetail | DescribeAigcVideoTask |
| Status value | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| Result URL | Output.FileInfos.FileUrl + ExpireTime | VideoInfos.Url (COS presigned, 12 hours) |
Supported Engines โ
| Engine | ModelName | Representative ModelVersion |
|---|---|---|
| Vega | wand-vega-video | 1.5-pro / 1.0-pro / 1.0-lite |
| Kling | Kling | 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 |
| Vidu | Vidu | q4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 / 2.0 |
| PixVerse | PixVerse | c1 / v6 / v5.6 |
| Hailuo | Hailuo | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
| GV | ||
| Hunyuan | Hunyuan | 1.5 / 3d_2.0 (SceneType=3d_scene) |
| Wan | Wan | 3.0 / 3.0-prime |
| Mingmou | Mingmou | 1.0 |
| VS | VS | 2.5 / 2.0 / 2.0-fast / 2.0-mini |
| SV | SV | 1.5-pro / 1.0-pro / 1.0-pro-fast |
| Happyhorse | H2 | 1.1 / 1.0 |
Common Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Optional | Integer | VOD Application ID. Required for accounts opened after 2023-12-25 |
ModelName | Required | String | Engine name |
ModelVersion | Optional | String | Engine version. The stable version is used when unspecified |
Prompt | Optional | String | Generation prompt. Required in text input mode |
NegativePrompt | Optional | String | Negative prompt |
EnhancePrompt | Optional | String | Enabled / Disabled. Automatically enhances the prompt |
SceneType | Optional | String | Special mode of each engine (motion_control / lip_sync / avatar_i2v / template_effect / 3d_scene / image_expand, etc.) |
FileInfos.N | Optional | Array | Reference input (image, video, audio) |
SubjectInfos.N | Optional | Array | Specify a registered reference object |
LastFrameUrl / LastFrameFileId | Optional | String | Last frame |
OutputConfig | Optional | Object | Output settings |
ExtInfo | Optional | String | Engine-specific extension parameters |
SessionId | Optional | String | Key used for deduplication. Duplicate requests with the same value are handled based on the existing request |
SessionContext | Optional | String | Callback pass-through value. Up to 1000 characters |
FileInfos.N โ
Reference input is handled uniformly as a single FileInfos type. The kind is distinguished by Category, and the role by Usage.
| Field | Description |
|---|---|
Type | Url (external URL) or File (VOD FileId) |
Url | Address when Type=Url |
FileId | When Type=File, the VOD media file ID |
Category | Image / Video / Audio |
Usage | FirstFrame (first frame) / LastFrame (last frame) / Reference (reference) |
ReferenceType | Reference nature. For allowed values and combinations, see the model details |
ObjectId | Name of the temporary reference object used for reference generation |
Text | Image name. Referenced as @name in the prompt (PixVerse multi-image mode) |
Usage is attached per reference
For multiple references, you must specify Usage on every item. If only some are specified, the remaining items may be ignored.
OutputConfig โ
| Field | Description |
|---|---|
Resolution | 480P / 720P / 1080P / 2K / 4K |
Duration | Video length (seconds). The allowed range differs by engine and version |
AspectRatio | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9, etc. |
AudioGeneration | Enabled / Disabled. Simultaneous audio generation |
StorageMode | Temporary (7 days) / Permanent (issues a FileId) |
MediaName | Media name stored when StorageMode=Permanent |
InputComplianceCheck | Disables input moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use |
OutputComplianceCheck | Disables output moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use |
ExtInfo โ
Engine-specific parameters are specified in ExtInfo, among 2, with JSON encoding. ExtInfo itself is a JSON string, and the AdditionalParameters value within it is also a JSON string.
{
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true}\"}"
}The generation order is as follows.
import json
params = {"multi_shot": True}
inner = json.dumps(params, ensure_ascii=False) # first serialization
ext = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False) # second serializationExtension parameters per service
MPS puts, in the top-level AdditionalParameters, a JSON string, while VOD encodes it inside ExtInfo.
Post-processing: Upscale Output โ
Save the generation result as Permanent to obtain a FileId, then post-process it with a VOD upscale output template or workflow.
New Notice and Call Scope โ
GV's 3.1-lite is a version that requires confirming the VOD detailed call specification. See VOD GV details.
Music โ
Mureka / EL music / sound effects
This is audio generation called through the VOD path. The action is CreateAigcAudioTask and the result query is DescribeTaskDetail. There are two scenes, sfx (sound effects) and music (music), and the scene and engine follow a fixed mapping.
Differences from the MPS Path โ
| Category | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API version | 2018-07-17 | 2019-06-12 |
| Video length | OutputConfig.Duration | Top level Duration |
| Output format | OutputConfig.OutputAudioFormat | OutputConfig.OutputAudioFormat or top level |
| Engine extension parameters | Top level AdditionalParameters (JSON string, among 1) | Top level AdditionalParameters (JSON string, among 1) |
| Result query | DescribeTaskDetail | DescribeAigcAudioTask |
| Status value | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
Audio extension parameters
In both VOD / MPS, audio extension parameters are specified in the top-level AdditionalParameters.
Supported Engines โ
Scene (SceneType) | Engine (ModelName) | ModelVersion | Note |
|---|---|---|---|
sfx | Kling | Default value used | text-to-sfx, video-to-sfx |
music | MiniMaxMusic | 3.0 / 2.6 / 2.5 / 2.0 | Lyrics input supported |
music | GL (Google Lyria) | 3.0-clip / 3.0-pro | Lyrics are included in the prompt |
music | Tme | Default value used | Cover track generation |
| Not required | Mureka | song_9.5 / song_9 / song_8 / easy_song_9.5 / instrumental_9.5 | song_* lyrics to song (lyrics); easy_song_9.5 prompt to song only; instrumental_9.5 instrumental |
| Not required | EL (ElevenLabs) | compose_v2.5 / compose_v2 / compose_detailed_v2.5 | Prompt to music |
| Not required | EL (ElevenLabs) | sound_t2s_v3 / sound_t2s_v2 | Text-to-sfx, Duration in [1, 30] |
Mureka/ELselect the mode viaModelVersionand do not useSceneType.song_9.5/easy_song_9.5/instrumental_9.5andcompose_v2.5/compose_detailed_v2.5/sound_t2s_v3were added on 2026-11-16.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
SubAppId | Optional | Integer | VOD Application ID |
ModelName | Optional | String | Kling / MiniMaxMusic / GL / Tme / Mureka / EL. Default Kling |
ModelVersion | Conditional | String | MiniMaxMusic / GL are optional. Mureka / EL select the mode by version, so specify it explicitly. When specified, only supported versions are allowed |
SceneType | Optional | String | sfx / music. Not required for Mureka / EL |
Prompt | Optional | String | Audio description. Required in text input mode |
VideoInfos.N | Optional | Array | Reference video for video-to-sfx |
AudioInfos.N | Optional | Array | Reference audio |
OutputConfig | Optional | Object | Output settings |
AdditionalParameters | Optional | String | Engine extension parameters (JSON string) |
OutputConfig โ
| Field | Description |
|---|---|
StorageMode | Temporary (7 days) / Permanent |
MediaName | Media name when StorageMode=Permanent |
Duration | Length (seconds). Kling text-to-sfx: [3, 10]; EL sound_t2s_v2 / sound_t2s_v3: [1, 30]. Not applied to video-to-sfx or to Mureka / EL compose_* music |
OutputAudioFormat | Output format. e.g. mp3 / wav (Mureka supports mp3 / wav / flac). The model default is used when unspecified |
AdditionalParameters โ
A JSON string holding each model's options. See the detailed fields of Kling, MiniMaxMusic, Tme, Mureka (lyrics).
3D โ
For the model / mode / input and output specifications specific to 3D, see Hy 3D Panorama and Hy World Model. Authentication / task status / storage policies follow the common specifications in this document.