Skip to content

API Reference โ€‹

Updated

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

ItemValue
RequestPOST https://mps.intl.tencentcloudapi.com
API version2019-06-12
AuthenticationTC3-HMAC-SHA256 / SecretId / SecretKey
Content-Typeapplication/json; charset=utf-8
Common headersX-TC-Action / X-TC-Version / X-TC-Timestamp / X-TC-Region

Generate / Query Actions โ€‹

CategoryActionPurpose
GenerateCreateAigcImageTaskImage generation
GenerateCreateAigcVideoTaskVideo generation, 3D scene generation
GenerateCreateAigcAudioTaskSound effects, music generation
QueryDescribeAigcImageTaskImage task query
QueryDescribeAigcVideoTaskVideo task query
QueryDescribeAigcAudioTaskAudio 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.

bash
python3 tencent-api.py mps CreateAigcImageTask request.json
bash
python3 tencent-api.py mps CreateAigcVideoTask request.json
bash
python3 tencent-api.py mps CreateAigcAudioTask request.json
http
POST / 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).

ActionPurposeSDK Developer Resources
CreateAigcImageTaskImage generationDeveloper Resources
CreateAigcVideoTaskVideo generationDeveloper Resources
CreateAigcAudioTaskAudio generationDeveloper Resources
DescribeAigcImageTaskImage task queryDeveloper Resources
DescribeAigcVideoTaskVideo task queryDeveloper Resources
DescribeAigcAudioTaskAudio task queryDeveloper 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 โ€‹

ItemConstraint
Image URLMust be externally accessible. 7MB or less is recommended for image generation, 10MB or less for video generation
Image formatjpeg, png, webp
Prompt length1000 characters for image, 2000 characters for video
Simultaneous audio generationEnableAudio is applied only on supported versions
LengthSpecify it within the Duration range supported by each engine

Common Fields โ€‹

FieldPurpose
OperatorCaller identification string
StoreCosParamCOS storage location
AdditionalParametersJSON string containing model-specific options

Response and Execution Flow โ€‹

Task Query โ€‹

  1. Call the generate action โ†’ receive TaskId
  2. Poll the query action โ†’ when Status is DONE, receive the result URL
  3. 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.

StatusMeaningHandling
WAITWaitingKeep polling
RUNRunningKeep polling
DONECompletedReceive the result URL
FAILCheck resultCheck Message and decide on subsequent requests
bash
python3 tencent-api.py mps DescribeAigcImageTask query.json
bash
python3 tencent-api.py mps DescribeAigcVideoTask query.json
bash
python3 tencent-api.py mps DescribeAigcAudioTask query.json

query.json:

json
{
  "TaskId": "<task-id>"
}

Acceptance Response โ€‹

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

json
{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "ImageUrls": [
      "https://aigc-output-image-<id>.cos.<region>.myqcloud.com/<file>.png?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}
json
{
  "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>"
  }
}
json
{
  "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>"
  }
}
json
{
  "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 โ€‹

TargetLimit
Image generation / query20 times per second
Video generation10 times per second
Video query20 times per second

For batch processing, it is safer to use a queue that limits the number of concurrent executions.

Response Codes โ€‹

Response codeItem to checkHow to configure
InvalidParameterRequest parametersCheck the model name / version / input specifications
InvalidParameter.ViolationContentBlocked by content moderation. The prompt or image violates the policyModify the prompt or image
AuthFailureAuthenticationCheck SecretId, SecretKey, timestamp, and signature
RequestLimitExceededCall frequency exceededLower the request rate or apply a queue
FailedOperationProcessing resultCheck 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.

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

ModeInputOutput
URL modePass a URL to API to run the taskCOS, VOS, S3, etc.
File modeTargets a file already stored in COSCOS

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.

ParameterDisable valueTarget
ExtraParameters.EnablelnputComplianceCheckfalseDisable input moderation
ExtraParameters.EnableOutputComplianceCheckfalseDisable output moderation

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

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

json
{
  "AdditionalParameters": "{\"seed\":12312}"
}
python
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.

Image โ€‹

Wan 2.2

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

EngineModelNameModelVersionFeatures
Nano BananaGEM3.1 / 3.1-lite / 3.0 / 2.5Up to 14 reference images
HunyuanHunyuan3.5-preview / 3.0General-purpose generation, image editing, up to 6 references
WAND-Vega-Imagewand-vega-image1.0-pro / 1.0-flash / 1.0-liteImage generation / reference image editing
QwenQwen0925General-purpose generation
SeedreamSeedream5.0-pro / 5.0-lite / 4.5 / 4.0General-purpose generation
KlingKling3.0-Omni / 3.0 / O1 / 2.1Realistic image generation
JimengJimeng4.0General-purpose generation
MidjourneyMJv8.2 / v8.1 / v7 / niji_7Tuned for anime/illustration
ViduViduq2General-purpose generation
Image2OGimage2_* / 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 โ€‹

ParameterRequiredTypeDescription
ModelNameRequiredStringFixed value <ModelName>
ModelVersionOptionalStringSupported version per engine
PromptRequiredStringGeneration prompt. See the detailed documentation for per-model limits
EnhancePromptOptionalBooleanAutomatic prompt correction. Default value false
ImageInfos.NOptionalArrayReference image array. Used for image-to-image and reference-based generation
ExtraParametersOptionalObjectOutput options such as Resolution / AspectRatio
AdditionalParametersOptionalStringJSON string containing model-specific options
StoreCosParamOptionalObjectCOS persistent storage configuration
OperatorOptionalStringString for identifying the caller

Input Specifications โ€‹

ItemConstraint
Image URLExternally accessible, 7MB or less is recommended
Formatjpeg, png, webp
Prompt lengthSee 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.

ItemVOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API version2018-07-172019-06-12
First frame / original imageFileInfos.N (distinguished by Usage)ImageInfos.N
Engine-specific optionsExtInfo (JSON string nested twice)AdditionalParameters (JSON string 1 times)
Storage methodOutputConfig.StorageMode = Temporary / PermanentResult is a COS presigned URL; store permanently with StoreCosParam
Query actionDescribeTaskDetailDescribeAigcImageTask
Status valuesStatus="FINISH" + ErrCode=0WAIT / RUN / DONE / FAIL
Result validity periodTemporary storage 7 daysPresigned 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.

json
"AdditionalParameters": "{\"size\":\"1536x1024\"}"
FieldDescription
CosBucketNameName of the bucket to store to
CosBucketRegionBucket region
CosBucketPathStorage path within the bucket

Call Frequency Limits โ€‹

TaskLimit
Image generation20 times per second
Image query20 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 โ€‹

EngineModelNameModelVersionFeatures
WAND-Vega-Videowand-vega-video1.5-pro / 1.0-pro / 1.0-liteText / image-based video generation
WanWan3.0 / 3.0-primeText and first/last frame generation
KlingKling3.0-Omni / 3.0 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 / O1Motion control, lip sync. Detailed documentation
HailuoHailuoH3 / 2.3 / 2.3-fast / 02
ViduViduq3-ad / q3-drama / q3 / q3-pro / q3-turbo / q3-mix / q2 seriesMulti-image reference, registered reference targets
VeoGV3.1 / 3.1-fast / 3.1-lite / omniVideo reference, state-preserving editing, native audio
PixVersePixVersec1 / v6 / v5.6Resolution in 4 steps, reference-based generation
HunyuanHunyuan1.5First/last frame
HappyhorseH21.1 / 1.0Multi-image reference, reference video (1.0 only)
MingmouMingmou1.0land2port landscape/portrait conversion
VSVS2.5 / 2.0 / 2.0-fast / 2.0-miniHigh bitrate, simultaneous audio generation
SVSeedance1.5-pro / 1.0-pro / 1.0-pro-fastโ€”

SceneType โ€‹

SceneTypeEnginePurpose
motion_controlKlingMotion control
lip_syncKlingLip sync
avatar_i2vKlingDigital human
multi_elementsKlingMulti-element editing
template_effectViduEffect template
land2portMingmouReconstruct landscape video into a portrait composition
3d_sceneHunyuan3D scene

Common Parameters โ€‹

ParameterRequiredTypeDescription
ModelNameRequiredStringFixed value <ModelName>
ModelVersionOptionalStringSupported version per engine
PromptRequiredStringGeneration prompt. See the per-model limits
NegativePromptOptionalStringElements to exclude from the result. Applied on supported models
EnhancePromptOptionalBooleanAutomatic prompt correction. Default value false
ImageUrlOptionalStringFirst frame image URL. Must be externally accessible and 10MB or less
LastImageUrlOptionalStringLast frame image URL. Used together with ImageUrl
ImageInfos.NOptionalArrayReference image array. Category / Url / ReferenceType, etc.
DurationOptionalIntegerGeneration length (seconds). Only values allowed by the model are applied
ExtraParametersOptionalObjectResolution / AspectRatio / EnableAudio
AdditionalParametersOptionalStringJSON string containing model-specific options
StoreCosParamOptionalObjectCOS persistent storage. CosBucketName / CosBucketRegion / CosBucketPath
OperatorOptionalStringString for identifying the caller
ExtraParameters.
EnablelnputComplianceCheck
OptionalBooleanPassing false explicitly disables input moderation. Contact your sales representative before use
ExtraParameters.
EnableOutputComplianceCheck
OptionalBooleanPassing 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.

ItemVOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API version2018-07-172019-06-12
First frameFileInfos.N.Usage=FirstFrameImageUrl
Last frameFileInfos.N.Usage=LastFrame or LastFrameUrlLastImageUrl
Reference imageFileInfos.NImageInfos.N
Reference videoFileInfos.N (Category=Video)VideoInfos.N
Video lengthOutputConfig.DurationTop-level Duration
Resolution / aspect ratioOutputConfig.Resolution / AspectRatioExtraParameters.Resolution / AspectRatio
Audio generationOutputConfig.AudioGenerationExtraParameters.EnableAudio
Engine-specific optionsExtInfo (JSON string nested twice)AdditionalParameters (JSON string 1 times)
Storage methodOutputConfig.StorageMode = Temporary / PermanentResult is a COS presigned URL; store permanently with StoreCosParam
Query actionDescribeTaskDetailDescribeAigcVideoTask
Status valuesStatus="FINISH" + ErrCode=0WAIT / RUN / DONE / FAIL
Result validity periodTemporary storage 7 daysPresigned 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.

FieldDescription
CosBucketNameName of the bucket to store to
CosBucketRegionBucket region
CosBucketPathStorage path within the bucket

Call Frequency Limits โ€‹

TaskLimit
Video generation10 times per second
Video query20 times per second

Response Codes โ€‹

CodeDescription
InvalidParameter.ViolationContentInput or output violates the content policy
InvalidParameterCheck the input fields and parameter specifications
AuthFailureCheck the authentication configuration
RequestLimitExceededCall frequency exceeded
FailedOperationCheck 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.

CategoryVOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API version2018-07-172019-06-12
Audio lengthOutputConfig.DurationTop-level Duration
Output formatOutputConfig.OutputAudioFormatTop-level OutputAudioFormat
Engine extension parametersTop-level AdditionalParameters (JSON string)Top-level AdditionalParameters (JSON string)
MiniMaxMusic lyrics fieldlyricslyric
MiniMaxMusic vocal removal fieldinstrumentalis_instrumental
Tme reference audioAudioInfos.N's Type + UrlAudioInfos.N's AudioUrl
Tme resource specificationAdditionalParameters's ResourceIdExtraParameters's ResourceId
Result queryDescribeTaskDetailDescribeAigcAudioTask
Status valuesFINISH + ErrCode=0WAIT / RUN / DONE / FAIL
Result URLOutput.AudioInfos.FileUrl + ExpireTime (temporary URL, 7 days)AudioInfos.Url (temporary URL including a signature, 12 hours)
Persistent storageOutputConfig.StorageMode=Permanent โ†’ VOD FileIdStoreCosParam 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)ModelVersionNotes
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

ModelName=GL is used. In the console, Google Lyria 3 corresponds to 3.0-clip, and 3 Pro corresponds to 3.0-pro.

ItemMiniMaxMusicGL (Google Lyria)
Lyrics inputPassed through AdditionalParameters's lyric fieldThe interface accepts only Prompt, so write the style and lyrics together in a single prompt
Instrumental{"is_instrumental": true} or omit the lyricsGenerates an instrumental track
Output formatMP3, WAVMP3
LengthDetermined by the model3 is an approximately 30 seconds clip, 3 Pro is a complete song structure

Request Parameters โ€‹

ParameterRequiredTypeDescription
ModelNameRequiredStringKling / MiniMaxMusic / GL / Tme
ModelVersionOptionalStringThe stable version is used when omitted
SceneTypeConditionalStringSpecifies the scene of the model, such as Kling. See the model details for Mureka / EL
PromptOptionalStringDescription of the audio to generate. Maximum 2000 characters
VideoInfos.NOptionalArrayReference video. Used for video-based sound effects
AudioInfos.NOptionalArrayReference audio. Used for cover track generation. MPS is the AudioUrl field
DurationOptionalIntegerAudio length (seconds). 0~60
OutputAudioFormatOptionalStringmp3 or wav
ExtraParametersOptionalObjectAdditional options per model. Tme requires ResourceId
AdditionalParametersOptionalStringModel-specific option JSON string. lyric / is_instrumental / bgm_prompt / asmr_mode, etc.
FieldTypeDescription
StatusStringWAIT / RUN / DONE / FAIL
MessageStringProcessing result message. ok on success
AudioInfosArrayList of generated audio
AudioInfos.UrlStringAudio download URL. Temporary link including a signature
VideoInfosArrayEmpty 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.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages