Skip to content

API Reference โ€‹

Updated

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

ItemValue
RequestPOST https://vod.intl.tencentcloudapi.com
API version2018-07-17
AuthenticationTC3-HMAC-SHA256 / SecretId / SecretKey
Content-Typeapplication/json; charset=utf-8
Common headersX-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 โ€‹

CategoryActionPurpose
GenerateCreateAigcImageTaskImage generation
GenerateCreateAigcVideoTaskVideo generation, 3D scene generation
GenerateCreateAigcAudioTaskSound effect and music generation
QueryDescribeTaskDetailCommon 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.

bash
python3 tencent-api.py vod CreateAigcImageTask request.json
bash
python3 tencent-api.py vod CreateAigcVideoTask request.json
bash
python3 tencent-api.py vod CreateAigcAudioTask request.json
http
POST / 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 โ€‹

ParameterRequiredTypeDescription
SubAppIdOptionalIntegerVOD Application ID. A new Application requires the actual ID to be specified.
ModelNameRequiredStringEngine name
ModelVersionOptionalStringEngine version. The default version is used when omitted
PromptRequiredStringGeneration prompt
SceneTypeOptionalStringSpecify a special mode
FileInfos.NOptionalArrayReference input. Type / Category / Usage / Url
OutputConfigOptionalObjectResolution / Duration / AspectRatio / StorageMode, etc.
ExtInfoOptionalStringAdvanced options. A string within 2, JSON-encoded

The FileInfos.N Usage indicates the reference purpose.

UsageMeaning
FirstFrameFirst frame
ReferenceReference input
LastFrameLast 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.

bash
python3 tencent-api.py vod DescribeTaskDetail query.json

query.json:

json
{
  "SubAppId": 0,
  "TaskId": "<task-id>"
}
StatusHandling
WAITING / PROCESSINGContinue polling
FINISHSuccess when ErrCode=0. On error, confirm Message
TypeStatusResult URL
ImageAigcImageTask.StatusAigcImageTask.Output.FileInfos.FileUrl
VideoAigcVideoTask.StatusAigcVideoTask.Output.FileInfos.FileUrl
MusicAigcAudioTask.StatusAigcAudioTask.Output.AudioInfos.FileUrl

Acceptance Response โ€‹

json
{
  "Response": {
    "TaskId": "<task-id>",
    "RequestId": "<request-id>"
  }
}

TaskId is used for subsequent queries, and RequestId for request tracking.

Example Response โ€‹

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

StorageModeValidity
Temporary7 days
PermanentPermanent. 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.

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

ParameterDisable valueApplies to
OutputConfig.InputComplianceCheckDisabledDisable input moderation
OutputConfig.OutputComplianceCheckDisabledDisable output moderation

Merge the following configuration into an existing generation request. To disable both input and output moderation, pass both fields together.

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

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

CategoryVOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API version2018-07-172019-06-12
Reference imageFileInfos.N (Type + Url)ImageInfos.N (ImageUrl)
Resolution / ratioOutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
Number of outputsOutputConfig.OutputImageCountOutputImageCount (top level)
Engine-specific parametersExtInfo = {"AdditionalParameters": "<JSON string>"} (encoded in 2)AdditionalParameters (JSON string, in 1)
Result queryDescribeTaskDetailDescribeAigcImageTask
Status valueFINISH + ErrCode=0WAIT / RUN / DONE / FAIL
Result URLOutput.FileInfos.FileUrl + ExpireTimeImageInfos.Url (COS presigned, 12 hours)

Supported Engines โ€‹

EngineModelNameModelVersion
Nano BananaGEM3.6 / 3.1 / 3.1-lite / 3.0 / 2.5
HunyuanHunyuan3.5-preview / 3.0
WAND-Vega-Imagewand-vega-image1.0-pro / 1.0-flash / 1.0-lite
QwenQwen0925
Seedream 5.xSI5.5 / 5.0-flash / 5.0-pro
SeedreamSeedream5.0-lite / 4.5 / 4.0
KlingKling4.0 / 4.0-long / 3.0-Omni / 3.0 / O1 / 2.1
JimengJimeng4.0
MidjourneyMJv8.2 / v8.1 / v7 / niji_7
ViduViduq2
GPT-ImageOGimage2_* / image2.5_sunburst_* / image2.5_flare_* / image2.6_sunburst_* / image2.6_flare_*

Common Parameters โ€‹

ParameterRequiredTypeDescription
SubAppIdOptionalIntegerVOD Application ID
ModelNameRequiredStringEngine name
ModelVersionOptionalStringEngine version
PromptOptionalStringGeneration prompt. Required in text input mode
NegativePromptOptionalStringNegative prompt
SceneTypeOptionalString3d_panorama (Hunyuan panorama), image_expand (Kling expansion), etc.
FileInfos.NOptionalArrayReference image. Specify a mask via ReferenceType=mask
OutputConfigOptionalObjectOutput settings
ExtInfoOptionalStringEngine-specific extension parameters
SessionIdOptionalStringKey used for deduplication
SessionContextOptionalStringCallback pass-through value. Up to 1000 characters
OutputConfig โ€‹
FieldDescription
Resolution1K / 2K / 4K, etc. The allowed values differ by engine
AspectRatio1:1 / 16:9 / 9:16 / 4:3 / 3:4, etc.
OutputImageCountNumber of outputs. For the allowed range of each model, see the detailed documentation
OutputFormatjpeg / png / webp. The model default is used when unspecified
StorageModeTemporary (7 days) / Permanent
MediaNameMedia name when StorageMode=Permanent
PersonGenerationAllowAdult / Disallowed. Whether to allow generating people
InputComplianceCheckDisables input moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use
OutputComplianceCheckDisables 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.

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

CategoryVOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API version2018-07-172019-06-12
First frameFileInfos.N + Usage=FirstFrameImageUrl
Last frameFileInfos.N + Usage=LastFrame, or LastFrameUrlLastImageUrl
Multiple reference imagesFileInfos.N (Category + Usage)ImageInfos.N
Reference videoFileInfos.N + Category=VideoVideoInfos.N
Video lengthOutputConfig.DurationTop level Duration
Resolution / ratioOutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
Simultaneous audio generationOutputConfig.AudioGenerationExtraParameters.EnableAudio
Engine-specific parametersExtInfo = {"AdditionalParameters": "<JSON string>"} (encoded in 2)AdditionalParameters (JSON string, in 1)
Result queryDescribeTaskDetailDescribeAigcVideoTask
Status valueFINISH + ErrCode=0WAIT / RUN / DONE / FAIL
Result URLOutput.FileInfos.FileUrl + ExpireTimeVideoInfos.Url (COS presigned, 12 hours)

Supported Engines โ€‹

EngineModelNameRepresentative ModelVersion
Vegawand-vega-video1.5-pro / 1.0-pro / 1.0-lite
KlingKling3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6
ViduViduq4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 / 2.0
PixVersePixVersec1 / v6 / v5.6
HailuoHailuoH3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02
GV
HunyuanHunyuan1.5 / 3d_2.0 (SceneType=3d_scene)
WanWan3.0 / 3.0-prime
MingmouMingmou1.0
VSVS2.5 / 2.0 / 2.0-fast / 2.0-mini
SVSV1.5-pro / 1.0-pro / 1.0-pro-fast
HappyhorseH21.1 / 1.0

Common Parameters โ€‹

ParameterRequiredTypeDescription
SubAppIdOptionalIntegerVOD Application ID. Required for accounts opened after 2023-12-25
ModelNameRequiredStringEngine name
ModelVersionOptionalStringEngine version. The stable version is used when unspecified
PromptOptionalStringGeneration prompt. Required in text input mode
NegativePromptOptionalStringNegative prompt
EnhancePromptOptionalStringEnabled / Disabled. Automatically enhances the prompt
SceneTypeOptionalStringSpecial mode of each engine (motion_control / lip_sync / avatar_i2v / template_effect / 3d_scene / image_expand, etc.)
FileInfos.NOptionalArrayReference input (image, video, audio)
SubjectInfos.NOptionalArraySpecify a registered reference object
LastFrameUrl / LastFrameFileIdOptionalStringLast frame
OutputConfigOptionalObjectOutput settings
ExtInfoOptionalStringEngine-specific extension parameters
SessionIdOptionalStringKey used for deduplication. Duplicate requests with the same value are handled based on the existing request
SessionContextOptionalStringCallback 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.

FieldDescription
TypeUrl (external URL) or File (VOD FileId)
UrlAddress when Type=Url
FileIdWhen Type=File, the VOD media file ID
CategoryImage / Video / Audio
UsageFirstFrame (first frame) / LastFrame (last frame) / Reference (reference)
ReferenceTypeReference nature. For allowed values and combinations, see the model details
ObjectIdName of the temporary reference object used for reference generation
TextImage 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 โ€‹
FieldDescription
Resolution480P / 720P / 1080P / 2K / 4K
DurationVideo length (seconds). The allowed range differs by engine and version
AspectRatio16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9, etc.
AudioGenerationEnabled / Disabled. Simultaneous audio generation
StorageModeTemporary (7 days) / Permanent (issues a FileId)
MediaNameMedia name stored when StorageMode=Permanent
InputComplianceCheckDisables input moderation on supported engines when Disabled. Hy Image excluded. Contact your sales representative before use
OutputComplianceCheckDisables 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.

json
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true}\"}"
}

The generation order is as follows.

python
import json
params = {"multi_shot": True}
inner = json.dumps(params, ensure_ascii=False)              # first serialization
ext = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False)  # second serialization

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

CategoryVOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API version2018-07-172019-06-12
Video lengthOutputConfig.DurationTop level Duration
Output formatOutputConfig.OutputAudioFormatOutputConfig.OutputAudioFormat or top level
Engine extension parametersTop level AdditionalParameters (JSON string, among 1)Top level AdditionalParameters (JSON string, among 1)
Result queryDescribeTaskDetailDescribeAigcAudioTask
Status valueFINISH + ErrCode=0WAIT / 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)ModelVersionNote
sfxKlingDefault value usedtext-to-sfx, video-to-sfx
musicMiniMaxMusic3.0 / 2.6 / 2.5 / 2.0Lyrics input supported
musicGL (Google Lyria)3.0-clip / 3.0-proLyrics are included in the prompt
musicTmeDefault value usedCover track generation
Not requiredMurekasong_9.5 / song_9 / song_8 / easy_song_9.5 / instrumental_9.5song_* lyrics to song (lyrics); easy_song_9.5 prompt to song only; instrumental_9.5 instrumental
Not requiredEL (ElevenLabs)compose_v2.5 / compose_v2 / compose_detailed_v2.5Prompt to music
Not requiredEL (ElevenLabs)sound_t2s_v3 / sound_t2s_v2Text-to-sfx, Duration in [1, 30]

Mureka / EL select the mode via ModelVersion and do not use SceneType. song_9.5 / easy_song_9.5 / instrumental_9.5 and compose_v2.5 / compose_detailed_v2.5 / sound_t2s_v3 were added on 2026-11-16.

Request Parameters โ€‹

ParameterRequiredTypeDescription
SubAppIdOptionalIntegerVOD Application ID
ModelNameOptionalStringKling / MiniMaxMusic / GL / Tme / Mureka / EL. Default Kling
ModelVersionConditionalStringMiniMaxMusic / GL are optional. Mureka / EL select the mode by version, so specify it explicitly. When specified, only supported versions are allowed
SceneTypeOptionalStringsfx / music. Not required for Mureka / EL
PromptOptionalStringAudio description. Required in text input mode
VideoInfos.NOptionalArrayReference video for video-to-sfx
AudioInfos.NOptionalArrayReference audio
OutputConfigOptionalObjectOutput settings
AdditionalParametersOptionalStringEngine extension parameters (JSON string)
OutputConfig โ€‹
FieldDescription
StorageModeTemporary (7 days) / Permanent
MediaNameMedia name when StorageMode=Permanent
DurationLength (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
OutputAudioFormatOutput 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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages