Skip to content

SDK Reference โ€‹

Updated

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.

CapabilityGenerate API (Action)Query API (Action)SDK Developer Resources
ImageCreateAigcImageTaskDescribeAigcImageTaskGenerate ยท Query
Video / 3DCreateAigcVideoTaskDescribeAigcVideoTaskGenerate ยท Query
Audio / MusicCreateAigcAudioTaskDescribeAigcAudioTaskGenerate ยท 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:

text
โ‘  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, pass StoreCosParam in 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 โ€‹

bash
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).

python
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.

python
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.

python
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 in VideoUrls, audio in AudioInfos[].Url.
  • Result URLs are COS pre-signed links that expire in 12 hours by 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 โ€‹

LanguageInstallClient classNote
Pythonpip install tencentcloud-sdk-python-intl-enmps_client.MpsClientExample in this page
JavaMaven dependency tencentcloud-sdk-java-intl-enMpsClientRequest objects CreateAigcVideoTaskRequest, etc.
Gogo get github.com/tencentcloud/tencentcloud-sdk-go-intl-enmps.NewClientPackage path mps/v20190612
Node.jsnpm i tencentcloud-sdk-nodejs-intl-enMpsClientMethods return a Promise
PHP / .NET / C++See each API's developer resource linkMpsClientMethod 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 CodeCheckHow to Handle
InvalidParameterRequest parametersCheck model name / version / input spec
InvalidParameter.ViolationContentInput moderation blockedModify the prompt or image
AuthFailureAuthenticationCheck SecretId / SecretKey / timestamp / signature
RequestLimitExceededRate limit exceededLower the request rate or add a queue
FailedOperationProcessing resultCheck the response Message

For the full list, see each API's "6. Error Code" and the Common Error Codes.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages