SDK Reference โ
This page explains how to call the key MPS AIGC APIs with the official Tencent Cloud SDKs. Compared with constructing the TC3 signature manually (see "Executing a Request" in the API Reference), the SDKs wrap signing, retries, serialization, and error handling, which is the recommended approach for production.
Authentication, request structure, task status, and storage specifications are identical to direct HTTP calls โ only the invocation layer is handled by the SDK. Check the engine menu on the left for model-specific parameters.
Key APIs at a Glance โ
MPS AIGC capabilities consist of paired "generate + query" APIs. Each API maps to a client method in the SDK (the method name matches the Action). The table below links to each API's official developer resources โ click to jump to the SDK source and examples for your language.
| Capability | Generate API (Action) | Query API (Action) | SDK Developer Resources |
|---|---|---|---|
| Image | CreateAigcImageTask | DescribeAigcImageTask | Generate ยท Query |
| Video / 3D | CreateAigcVideoTask | DescribeAigcVideoTask | Generate ยท Query |
| Audio / Music | CreateAigcAudioTask | DescribeAigcAudioTask | Generate ยท Query |
The "5. Developer Resources" section of each API page provides SDK entry points for seven languages โ Python / Java / PHP / Go / Node.js / .NET / C++ โ all under the MPS v20190612 client. For CLI invocation, see Tencent Cloud CLI (TCCLI).
Call Flow โ
Whether image, video, or audio, SDK calls follow the same five-step flow:
โ Install the SDK pip / maven / npm / go get โฆ
โก Init the client SecretId + SecretKey + region โ MpsClient
โข Create a task CreateAigcXxxTask โ returns TaskId
โฃ Poll the query DescribeAigcXxxTask every 3s until Status=DONE
โค Handle the result Get result URL (valid 12h), download or store it- The generate API returns only a
TaskId; the result is fetched asynchronously via the query API. Do not expect the generate API to return the image/video directly. - The default result URL is valid for
12 hours; to persist it, passStoreCosParamin the generation request to save to your own COS. - Generation requests incur actual usage charges. If a timeout leaves the acceptance status unclear, check the task before retrying to avoid duplicate billing.
Python Example (Video Generation) โ
The following demonstrates the full flow with the Python SDK (international edition). Client method names are identical in other languages โ only the syntax differs; refer to the developer resource links in the table above.
โ Install โ
pip install tencentcloud-sdk-python-intl-enโก Initialize the Client โ
Inject credentials via environment variables โ never hard-code them. Fill in the region for your access point (e.g. ap-singapore).
import os
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models
cred = credential.Credential(
os.environ["TENCENT_SECRET_ID"],
os.environ["TENCENT_SECRET_KEY"],
)
http_profile = HttpProfile(endpoint="mps.intl.tencentcloudapi.com")
client_profile = ClientProfile(httpProfile=http_profile)
client = mps_client.MpsClient(cred, "ap-singapore", client_profile)โข Create a Generation Task โ
Populate the request with the SDK's from_json_string; fields match the HTTP JSON exactly. AdditionalParameters is a JSON string and must be serialized twice.
import json
req = models.CreateAigcVideoTaskRequest()
req.from_json_string(json.dumps({
"ModelName": "Hunyuan",
"Prompt": "a cat walking in the rain, cinematic",
"Duration": 5,
"ExtraParameters": {"Resolution": "720P", "AspectRatio": "16:9"},
"Operator": "sdk-demo",
}))
resp = client.CreateAigcVideoTask(req)
task_id = resp.TaskId
print("TaskId:", task_id)โฃ Poll the Query API โ
The recommended polling interval is 3 seconds. The query API has a rate limit; for batch scenarios use a concurrency-limited queue.
import time
while True:
q = models.DescribeAigcVideoTaskRequest()
q.from_json_string(json.dumps({"TaskId": task_id}))
r = client.DescribeAigcVideoTask(q)
if r.Status == "DONE":
print("Video URLs:", r.VideoUrls)
break
if r.Status == "FAIL":
raise RuntimeError(f"task failed: {r.Message}")
time.sleep(3)โค Handle the Result โ
- Image results are in
ImageUrls, video inVideoUrls, audio inAudioInfos[].Url. - Result URLs are COS pre-signed links that expire in
12 hoursby default โ download or store them promptly. - If the request carried
StoreCosParam, results are saved to your own COS bucket and follow that bucket's access permissions.
Notes for Other Languages โ
| Language | Install | Client class | Note |
|---|---|---|---|
| Python | pip install tencentcloud-sdk-python-intl-en | mps_client.MpsClient | Example in this page |
| Java | Maven dependency tencentcloud-sdk-java-intl-en | MpsClient | Request objects CreateAigcVideoTaskRequest, etc. |
| Go | go get github.com/tencentcloud/tencentcloud-sdk-go-intl-en | mps.NewClient | Package path mps/v20190612 |
| Node.js | npm i tencentcloud-sdk-nodejs-intl-en | MpsClient | Methods return a Promise |
| PHP / .NET / C++ | See each API's developer resource link | MpsClient | Method names match the Action |
For each language's client initialization (credentials, region, endpoint) and method signatures, refer to the official SDK source under "5. Developer Resources" of the corresponding API page above.
Error Codes โ
The SDK raises API errors as TencentCloudSDKException, carrying code and message. Common error codes and how to handle them:
| Response Code | Check | How to Handle |
|---|---|---|
InvalidParameter | Request parameters | Check model name / version / input spec |
InvalidParameter.ViolationContent | Input moderation blocked | Modify the prompt or image |
AuthFailure | Authentication | Check SecretId / SecretKey / timestamp / signature |
RequestLimitExceeded | Rate limit exceeded | Lower the request rate or add a queue |
FailedOperation | Processing result | Check the response Message |
For the full list, see each API's "6. Error Code" and the Common Error Codes.
Related Documents โ
- API Reference: MPS authentication, request structure, task query, and storage specifications, including the manual TC3 signing script.
- Per-API developer resources: see the jump links in the Key APIs at a Glance table above.
- Tencent Cloud CLI (TCCLI): command-line and scripted invocation.