API Reference โ
Authentication, request structure, task query, and storage specifications for MPS. Check the engine menu on the left for model-specific values and examples.
Call Specifications โ
| Item | Value |
|---|---|
| Request | POST https://mps.intl.tencentcloudapi.com |
| API version | 2019-06-12 |
| 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 |
Generate / Query Actions โ
| Category | Action | Purpose |
|---|---|---|
| Generate | CreateAigcImageTask | Image generation |
| Generate | CreateAigcVideoTask | Video generation, 3D scene generation |
| Generate | CreateAigcAudioTask | Sound effects, music generation |
| Query | DescribeAigcImageTask | Image task query |
| Query | DescribeAigcVideoTask | Video task query |
| Query | DescribeAigcAudioTask | Audio task query |
Executing a Request โ
Save the TC3 call script as tencent-api.py. It uses only the Python 3 standard library and computes the signature from the current time and the body on every request. 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 mps CreateAigcImageTask request.jsonpython3 tencent-api.py mps CreateAigcVideoTask request.jsonpython3 tencent-api.py mps CreateAigcAudioTask request.jsonPOST / HTTP/1.1
Host: mps.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAigcImageTask
X-TC-Version: 2019-06-12
X-TC-Timestamp: <unix-timestamp>
X-TC-Region: ap-singapore
Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/mps/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<Signature>Generation requests incur actual usage charges. If a timeout makes it unclear whether the request was accepted, check the task status before generating again. Temporary credentials can be specified with TENCENT_TOKEN, and the region with --region.
SDK Invocation โ
Besides constructing the TC3 signature manually, you can use the official Tencent Cloud SDKs. The SDKs wrap signing, retries, and serialization. The table below links to the "Developer Resources โบ SDK" section of each action (click to jump).
| Action | Purpose | SDK Developer Resources |
|---|---|---|
CreateAigcImageTask | Image generation | Developer Resources |
CreateAigcVideoTask | Video generation | Developer Resources |
CreateAigcAudioTask | Audio generation | Developer Resources |
DescribeAigcImageTask | Image task query | Developer Resources |
DescribeAigcVideoTask | Video task query | Developer Resources |
DescribeAigcAudioTask | Audio task query | Developer Resources |
Each action's page provides SDK entry points for seven languages โ Python / Java / PHP / Go / Node.js / .NET / C++ โ all under the MPS v20190612 client.
CLI Invocation โ
If you prefer the command line or scripting, use the Tencent Cloud CLI (TCCLI). For installation, configuration, and command syntax, see Tencent Cloud CLI (TCCLI). Once installed, all of the actions above can be called directly in the form tccli mps <Action> --cli-unfold-argument.
API List and Request Parameters โ
Input Specifications โ
| Item | Constraint |
|---|---|
| Image URL | Must be externally accessible. 7MB or less is recommended for image generation, 10MB or less for video generation |
| Image format | jpeg, png, webp |
| Prompt length | 1000 characters for image, 2000 characters for video |
| Simultaneous audio generation | EnableAudio is applied only on supported versions |
| Length | Specify it within the Duration range supported by each engine |
Common Fields โ
| Field | Purpose |
|---|---|
Operator | Caller identification string |
StoreCosParam | COS storage location |
AdditionalParameters | JSON string containing model-specific options |
Response and Execution Flow โ
Task Query โ
- Call the generate action โ receive
TaskId - Poll the query action โ when
StatusisDONE, receive the result URL - Download the result or transfer it to your own storage
The recommended polling interval is 3 seconds. Query API is subject to call frequency limits, so refer to the table below.
| Status | Meaning | Handling |
|---|---|---|
WAIT | Waiting | Keep polling |
RUN | Running | Keep polling |
DONE | Completed | Receive the result URL |
FAIL | Check result | Check Message and decide on subsequent requests |
python3 tencent-api.py mps DescribeAigcImageTask query.jsonpython3 tencent-api.py mps DescribeAigcVideoTask query.jsonpython3 tencent-api.py mps DescribeAigcAudioTask query.jsonquery.json:
{
"TaskId": "<task-id>"
}Acceptance Response โ
{
"Response": {
"TaskId": "<task-id>",
"RequestId": "<request-id>"
}
}TaskId is used for subsequent queries, and RequestId is used for request tracing.
CoverUrl in the video query response is the representative frame URL.
Example Response โ
{
"Response": {
"Status": "DONE",
"Message": "ok",
"ImageUrls": [
"https://aigc-output-image-<id>.cos.<region>.myqcloud.com/<file>.png?q-sign-algorithm=sha1&..."
],
"RequestId": "<request-id>"
}
}{
"Response": {
"Status": "DONE",
"Message": "ok",
"Resolution": "1920x1080",
"VideoUrls": [
"https://aigc-output-video-<id>.cos.<region>.myqcloud.com/<file>.mp4?q-sign-algorithm=sha1&..."
],
"RequestId": "<request-id>"
}
}{
"Response": {
"Status": "DONE",
"Message": "ok",
"AudioInfos": [
{
"Url": "https://aigc-output-audio-file-<id>.cos.<region>.myqcloud.com/<file>.mp3?q-sign-algorithm=sha1&..."
}
],
"VideoInfos": ,
"RequestId": "<request-id>"
}
}{
"Response": {
"Status": "DONE",
"TaskId": "<task-id>",
"VideoUrl": "https://<bucket>.cos.<region>.myqcloud.com/<file>.mp4",
"CoverUrl": "https://<bucket>.cos.<region>.myqcloud.com/<cover>.jpg",
"RequestId": "<request-id>"
}
}Errors and Call Limits โ
Call Frequency Limits โ
| Target | Limit |
|---|---|
| Image generation / query | 20 times per second |
| Video generation | 10 times per second |
| Video query | 20 times per second |
For batch processing, it is safer to use a queue that limits the number of concurrent executions.
Response Codes โ
| Response code | Item to check | How to configure |
|---|---|---|
InvalidParameter | Request parameters | Check the model name / version / input specifications |
InvalidParameter.ViolationContent | Blocked by content moderation. The prompt or image violates the policy | Modify the prompt or image |
AuthFailure | Authentication | Check SecretId, SecretKey, timestamp, and signature |
RequestLimitExceeded | Call frequency exceeded | Lower the request rate or apply a queue |
FailedOperation | Processing result | Check the response Message |
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 a single request. Check the engine documentation below together with the parameters for each protocol.
Result and Resource Management โ
Result Storage โ
The default temporary result URL is valid for 12 hours. To keep results in your own bucket, specify StoreCosParam in the generation request. Result URLs in your own bucket follow the access permissions of that bucket, and private objects are downloaded using COS SDK or a signed URL.
{
"StoreCosParam": {
"CosBucketName": "<bucket>",
"CosBucketRegion": "<region>",
"CosBucketPath": "aigc/video/"
}
}To use COS storage, the MPS_QcsRole role must be delegated to the target bucket.
Resolution and Upscale Output โ
Use ExtraParameters.Resolution to specify 720P / 1080P / 2K / 4K. Values that exceed the resolution the model can output directly are produced through a platform enhancement step. To improve the quality of an already generated video, use the MPS transcoding and enhancement template.
| Mode | Input | Output |
|---|---|---|
| URL mode | Pass a URL to API to run the task | COS, VOS, S3, etc. |
| File mode | Targets a file already stored in COS | COS |
Built-in enhancement templates are divided into animation scenes and live-action scenes; for 720P / 1080P / 2K / 4K output, the frame rate follows the source. Noise removal, upscale output, and comprehensive enhancement are applied together.
When applying upscale output processing, it is safer to configure COS persistent storage first. If the 12 hours URL expires, the input to the enhancement task is lost.
Disabling Guardrails โ
For video, it can be applied to Kling / Vidu / Wan / Happyhorse / Hailuo H3. It is not applied to other versions of Hailuo. For the supported range of WAND-Vega-Video, refer to the documentation of that engine. It is not applied to VS. It is not applied 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 | Target |
|---|---|---|
ExtraParameters.EnablelnputComplianceCheck | false | Disable input moderation |
ExtraParameters.EnableOutputComplianceCheck | false | Disable output moderation |
Merge the following configuration into an existing generation request. To disable both input and output moderation, pass both fields together.
{
"ExtraParameters": {
"EnablelnputComplianceCheck": false,
"EnableOutputComplianceCheck": false
}
}VOD passes OutputConfig.InputComplianceCheck / OutputConfig.OutputComplianceCheck the string Disabled. Do not mix it with MPS's Boolean false. See VOD API Reference.
Additional Model Configuration โ
Seed โ
seed is specified inside the top-level AdditionalParameters JSON string. It is a separate field from the ExtraParameters object. If the same request contains other model options, merge them into a single JSON object and serialize it.
{
"AdditionalParameters": "{\"seed\":12312}"
}import json
additional_parameters = json.dumps({"seed": 12312})For common input fields, refer to Image Generation API and Video Generation API. The scope in which options apply varies by model.
Engine Catalog and Related Documentation โ
Image โ
CreateAigcImageTask generates images. Specify common request fields and model-specific output options separately. Check each engine's documentation for supported versions and dedicated options.
Engine List โ
| Engine | ModelName | ModelVersion | Features |
|---|---|---|---|
| Nano Banana | GEM | 3.1 / 3.1-lite / 3.0 / 2.5 | Up to 14 reference images |
| Hunyuan | Hunyuan | 3.5-preview / 3.0 | General-purpose generation, image editing, up to 6 references |
| WAND-Vega-Image | wand-vega-image | 1.0-pro / 1.0-flash / 1.0-lite | Image generation / reference image editing |
| Qwen | Qwen | 0925 | General-purpose generation |
| Seedream | Seedream | 5.0-pro / 5.0-lite / 4.5 / 4.0 | General-purpose generation |
| Kling | Kling | 3.0-Omni / 3.0 / O1 / 2.1 | Realistic image generation |
| Jimeng | Jimeng | 4.0 | General-purpose generation |
| Midjourney | MJ | v8.2 / v8.1 / v7 / niji_7 | Tuned for anime/illustration |
| Vidu | Vidu | q2 | General-purpose generation |
| Image2 | OG | image2_* / image2.5_sunburst_* / image2.5_flare_* | Reference images, custom resolution, mask editing |
The output size of WAND-Vega-Image is specified in AdditionalParameters's size. For detailed configuration, see WAND-Vega-Image.
Common Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ModelName | Required | String | Fixed value <ModelName> |
ModelVersion | Optional | String | Supported version per engine |
Prompt | Required | String | Generation prompt. See the detailed documentation for per-model limits |
EnhancePrompt | Optional | Boolean | Automatic prompt correction. Default value false |
ImageInfos.N | Optional | Array | Reference image array. Used for image-to-image and reference-based generation |
ExtraParameters | Optional | Object | Output options such as Resolution / AspectRatio |
AdditionalParameters | Optional | String | JSON string containing model-specific options |
StoreCosParam | Optional | Object | COS persistent storage configuration |
Operator | Optional | String | String for identifying the caller |
Input Specifications โ
| Item | Constraint |
|---|---|
| Image URL | Externally accessible, 7MB or less is recommended |
| Format | jpeg, png, webp |
| Prompt length | See the per-model limits |
Differences from the VOD Path โ
Although the same CreateAigcImageTask action name is used, VOD and MPS differ in the call target and parameter structure.
| Item | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.intl.tencentcloudapi.com) |
|---|---|---|
| API version | 2018-07-17 | 2019-06-12 |
| First frame / original image | FileInfos.N (distinguished by Usage) | ImageInfos.N |
| Engine-specific options | ExtInfo (JSON string nested twice) | AdditionalParameters (JSON string 1 times) |
| Storage method | OutputConfig.StorageMode = Temporary / Permanent | Result is a COS presigned URL; store permanently with StoreCosParam |
| Query action | DescribeTaskDetail | DescribeAigcImageTask |
| Status values | Status="FINISH" + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| Result validity period | Temporary storage 7 days | Presigned URL 12 hours |
The custom resolution of OG is passed in a different location
The custom size of OG (Image2) is passed through AdditionalParameters's size field in both paths, but in VOD this value is nested once more inside ExtInfo. In MPS, it is specified directly inside the AdditionalParameters string.
"AdditionalParameters": "{\"size\":\"1536x1024\"}"| Field | Description |
|---|---|
CosBucketName | Name of the bucket to store to |
CosBucketRegion | Bucket region |
CosBucketPath | Storage path within the bucket |
Call Frequency Limits โ
| Task | Limit |
|---|---|
| Image generation | 20 times per second |
| Image query | 20 times per second |
Select an engine from the left menu to see the versions, dedicated options, and request examples of that engine.
Video โ
CreateAigcVideoTask generates videos. Resolution and aspect ratio are specified in ExtraParameters, and length in the top-level Duration. Engine-specific features are specified with SceneType and AdditionalParameters.
Engine List โ
| Engine | ModelName | ModelVersion | Features |
|---|---|---|---|
| WAND-Vega-Video | wand-vega-video | 1.5-pro / 1.0-pro / 1.0-lite | Text / image-based video generation |
| Wan | Wan | 3.0 / 3.0-prime | Text and first/last frame generation |
| Kling | Kling | 3.0-Omni / 3.0 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 / O1 | Motion control, lip sync. Detailed documentation |
| Hailuo | Hailuo | H3 / 2.3 / 2.3-fast / 02 | |
| Vidu | Vidu | q3-ad / q3-drama / q3 / q3-pro / q3-turbo / q3-mix / q2 series | Multi-image reference, registered reference targets |
| Veo | GV | 3.1 / 3.1-fast / 3.1-lite / omni | Video reference, state-preserving editing, native audio |
| PixVerse | PixVerse | c1 / v6 / v5.6 | Resolution in 4 steps, reference-based generation |
| Hunyuan | Hunyuan | 1.5 | First/last frame |
| Happyhorse | H2 | 1.1 / 1.0 | Multi-image reference, reference video (1.0 only) |
| Mingmou | Mingmou | 1.0 | land2port landscape/portrait conversion |
| VS | VS | 2.5 / 2.0 / 2.0-fast / 2.0-mini | High bitrate, simultaneous audio generation |
| SV | Seedance | 1.5-pro / 1.0-pro / 1.0-pro-fast | โ |
SceneType โ
| SceneType | Engine | Purpose |
|---|---|---|
motion_control | Kling | Motion control |
lip_sync | Kling | Lip sync |
avatar_i2v | Kling | Digital human |
multi_elements | Kling | Multi-element editing |
template_effect | Vidu | Effect template |
land2port | Mingmou | Reconstruct landscape video into a portrait composition |
3d_scene | Hunyuan | 3D scene |
Common Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ModelName | Required | String | Fixed value <ModelName> |
ModelVersion | Optional | String | Supported version per engine |
Prompt | Required | String | Generation prompt. See the per-model limits |
NegativePrompt | Optional | String | Elements to exclude from the result. Applied on supported models |
EnhancePrompt | Optional | Boolean | Automatic prompt correction. Default value false |
ImageUrl | Optional | String | First frame image URL. Must be externally accessible and 10MB or less |
LastImageUrl | Optional | String | Last frame image URL. Used together with ImageUrl |
ImageInfos.N | Optional | Array | Reference image array. Category / Url / ReferenceType, etc. |
Duration | Optional | Integer | Generation length (seconds). Only values allowed by the model are applied |
ExtraParameters | Optional | Object | Resolution / AspectRatio / EnableAudio |
AdditionalParameters | Optional | String | JSON string containing model-specific options |
StoreCosParam | Optional | Object | COS persistent storage. CosBucketName / CosBucketRegion / CosBucketPath |
Operator | Optional | String | String for identifying the caller |
ExtraParameters.EnablelnputComplianceCheck | Optional | Boolean | Passing false explicitly disables input moderation. Contact your sales representative before use |
ExtraParameters.EnableOutputComplianceCheck | Optional | Boolean | Passing false explicitly disables output moderation. Contact your sales representative before use |
Differences from the VOD Path โ
VOD and MPS each use their own endpoint and parameter structure. Check the MPS request fields in the table below.
| Item | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.intl.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 |
| Reference image | FileInfos.N | ImageInfos.N |
| Reference video | FileInfos.N (Category=Video) | VideoInfos.N |
| Video length | OutputConfig.Duration | Top-level Duration |
| Resolution / aspect ratio | OutputConfig.Resolution / AspectRatio | ExtraParameters.Resolution / AspectRatio |
| Audio generation | OutputConfig.AudioGeneration | ExtraParameters.EnableAudio |
| Engine-specific options | ExtInfo (JSON string nested twice) | AdditionalParameters (JSON string 1 times) |
| Storage method | OutputConfig.StorageMode = Temporary / Permanent | Result is a COS presigned URL; store permanently with StoreCosParam |
| Query action | DescribeTaskDetail | DescribeAigcVideoTask |
| Status values | Status="FINISH" + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| Result validity period | Temporary storage 7 days | Presigned URL 12 hours |
Parameters must be remapped when switching paths
MPS uses the top-level Duration and the JSON string AdditionalParameters. The corresponding items in VOD are OutputConfig.Duration and ExtInfo.
| Field | Description |
|---|---|
CosBucketName | Name of the bucket to store to |
CosBucketRegion | Bucket region |
CosBucketPath | Storage path within the bucket |
Call Frequency Limits โ
| Task | Limit |
|---|---|
| Video generation | 10 times per second |
| Video query | 20 times per second |
Response Codes โ
| Code | Description |
|---|---|
InvalidParameter.ViolationContent | Input or output violates the content policy |
InvalidParameter | Check the input fields and parameter specifications |
AuthFailure | Check the authentication configuration |
RequestLimitExceeded | Call frequency exceeded |
FailedOperation | Check the processing result |
Select an engine from the left menu to see the capabilities supported by each version of that engine, its dedicated options, and request examples.
Music โ
Mureka / EL Music / Sound Effects
This is audio generation called through the MPS path. The action is CreateAigcAudioTask and the result query is DescribeAigcAudioTask. Models that use a scene specify sfx (sound effects) or music (music). Mureka / EL follow the request structure in the model details.
Differences from the VOD Path โ
The same CreateAigcAudioTask action is used, but the endpoint and the result query method differ.
| Category | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.intl.tencentcloudapi.com) |
|---|---|---|
| API version | 2018-07-17 | 2019-06-12 |
| Audio length | OutputConfig.Duration | Top-level Duration |
| Output format | OutputConfig.OutputAudioFormat | Top-level OutputAudioFormat |
| Engine extension parameters | Top-level AdditionalParameters (JSON string) | Top-level AdditionalParameters (JSON string) |
| MiniMaxMusic lyrics field | lyrics | lyric |
| MiniMaxMusic vocal removal field | instrumental | is_instrumental |
| Tme reference audio | AudioInfos.N's Type + Url | AudioInfos.N's AudioUrl |
| Tme resource specification | AdditionalParameters's ResourceId | ExtraParameters's ResourceId |
| Result query | DescribeTaskDetail | DescribeAigcAudioTask |
| Status values | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| Result URL | Output.AudioInfos.FileUrl + ExpireTime (temporary URL, 7 days) | AudioInfos.Url (temporary URL including a signature, 12 hours) |
| Persistent storage | OutputConfig.StorageMode=Permanent โ VOD FileId | StoreCosParam stores it to your own COS bucket |
Audio Extension Parameters
In both VOD / MPS, audio extension parameters are specified in the top-level AdditionalParameters.
Supported Engines โ
Scene (SceneType) | Engine (ModelName) | ModelVersion | Notes |
|---|---|---|---|
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 |
ModelName=GL is used. In the console, Google Lyria 3 corresponds to 3.0-clip, and 3 Pro corresponds to 3.0-pro.
| Item | MiniMaxMusic | GL (Google Lyria) |
|---|---|---|
| Lyrics input | Passed through AdditionalParameters's lyric field | The interface accepts only Prompt, so write the style and lyrics together in a single prompt |
| Instrumental | {"is_instrumental": true} or omit the lyrics | Generates an instrumental track |
| Output format | MP3, WAV | MP3 |
| Length | Determined by the model | 3 is an approximately 30 seconds clip, 3 Pro is a complete song structure |
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ModelName | Required | String | Kling / MiniMaxMusic / GL / Tme |
ModelVersion | Optional | String | The stable version is used when omitted |
SceneType | Conditional | String | Specifies the scene of the model, such as Kling. See the model details for Mureka / EL |
Prompt | Optional | String | Description of the audio to generate. Maximum 2000 characters |
VideoInfos.N | Optional | Array | Reference video. Used for video-based sound effects |
AudioInfos.N | Optional | Array | Reference audio. Used for cover track generation. MPS is the AudioUrl field |
Duration | Optional | Integer | Audio length (seconds). 0~60 |
OutputAudioFormat | Optional | String | mp3 or wav |
ExtraParameters | Optional | Object | Additional options per model. Tme requires ResourceId |
AdditionalParameters | Optional | String | Model-specific option JSON string. lyric / is_instrumental / bgm_prompt / asmr_mode, etc. |
| Field | Type | Description |
|---|---|---|
Status | String | WAIT / RUN / DONE / FAIL |
Message | String | Processing result message. ok on success |
AudioInfos | Array | List of generated audio |
AudioInfos.Url | String | Audio download URL. Temporary link including a signature |
VideoInfos | Array | Empty array for music generation |
Select an engine from the left menu to see how that engine passes lyrics, its dedicated options, and request examples.
3D โ
The model / mode / input and output specifications specific to 3D are described in Hy 3D Panorama and Hy World Model. Authentication / task status / storage policies follow the common specifications in this document.