SDK Reference โ
This page explains how to call the key VOD 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 query, 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 values and examples.
Two key differences between VOD and MPS: โ the query action is unified as
DescribeTaskDetail(MPS has oneDescribeAigcXxxTaskper type); โก the API version is2018-07-17, and the SDK client class isVodClient.
Key APIs at a Glance โ
VOD AIGC capabilities consist of three generation APIs plus one unified query API. 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 | API (Action) | SDK Developer Resources |
|---|---|---|
| Image generation | CreateAigcImageTask | Developer Resources |
| Video / 3D generation | CreateAigcVideoTask | Developer Resources |
| Audio / Music generation | CreateAigcAudioTask | Developer Resources |
| Unified task query | DescribeTaskDetail | Developer Resources |
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 VOD v20180717 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 โ VodClient
โข Create a task CreateAigcXxxTask (with SubAppId) โ returns TaskId
โฃ Poll the query DescribeTaskDetail every 3s until Status=FINISH
โค Handle the result Confirm ErrCode=0, get the media; download or manage by StorageMode- The generate API returns only a
TaskId; the result is fetched asynchronously viaDescribeTaskDetail. Do not expect the generate API to return the media directly. SubAppIdis the VOD application ID. Customers who activated VOD on or after 2023-12-25 must provide it when accessing resources inside an application.- Result lifetime is set by
OutputConfig.StorageMode:Temporarykeeps the result for7 days, whilePermanentregisters it as a VOD media asset for long-term storage (longer than MPS's12-hourpre-signed URL). - 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-guangzhou).
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.vod.v20180717 import vod_client, models
cred = credential.Credential(
os.environ["TENCENT_SECRET_ID"],
os.environ["TENCENT_SECRET_KEY"],
)
http_profile = HttpProfile(endpoint="vod.intl.tencentcloudapi.com")
client_profile = ClientProfile(httpProfile=http_profile)
client = vod_client.VodClient(cred, "ap-guangzhou", client_profile)โข Create a Generation Task โ
Populate the request with the SDK's from_json_string; fields match the HTTP JSON exactly. SubAppId is required; engine-specific options are passed via ExtInfo (a JSON string).
import json
req = models.CreateAigcVideoTaskRequest()
req.from_json_string(json.dumps({
"SubAppId": 1500062800,
"ModelName": "GV",
"ModelVersion": "3.1-fast",
"Prompt": "a cat walking in the rain, cinematic",
"OutputConfig": {
"StorageMode": "Temporary",
"AspectRatio": "16:9",
},
}))
resp = client.CreateAigcVideoTask(req)
task_id = resp.TaskId
print("TaskId:", task_id)โฃ Poll the Unified Query API โ
All VOD AIGC tasks are queried via DescribeTaskDetail. The recommended polling interval is 3 seconds, and you must confirm both Status="FINISH" and ErrCode=0.
import time
while True:
q = models.DescribeTaskDetailRequest()
q.from_json_string(json.dumps({
"TaskId": task_id,
"SubAppId": 1500062800,
}))
r = client.DescribeTaskDetail(q)
if r.Status == "FINISH":
# Read the result by task type: r.AigcVideoTask / r.AigcImageTask / r.AigcAudioTask
print("task finished:", r.TaskType)
break
if r.Status == "ABORTED":
raise RuntimeError("task aborted")
time.sleep(3)โค Handle the Result โ
DescribeTaskDetailreturns the corresponding sub-task structure byTaskType(AigcImageTask/AigcVideoTask/AigcAudioTask). The result media,ErrCode, andMessageare inside that sub-task.- A
StorageMode=Temporaryresult is kept for7 days;StorageMode=Permanentregisters it as a VOD media asset (returns aFileId) that you can manage as a regular VOD media. - On failure,
ErrCode != 0; the reason is in the sub-task'sMessage.
Notes for Other Languages โ
| Language | Install | Client class | Note |
|---|---|---|---|
| Python | pip install tencentcloud-sdk-python-intl-en | vod_client.VodClient | Example in this page |
| Java | Maven dependency tencentcloud-sdk-java-intl-en | VodClient | Request objects CreateAigcVideoTaskRequest, etc. |
| Go | go get github.com/tencentcloud/tencentcloud-sdk-go-intl-en | vod.NewClient | Package path vod/v20180717 |
| Node.js | npm i tencentcloud-sdk-nodejs-intl-en | VodClient | Methods return a Promise |
| PHP / .NET / C++ | See each API's developer resource link | VodClient | 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 |
InvalidParameterValue.SubAppId | Application ID | Check that SubAppId is a valid application ID |
FailedOperation.InvalidVodUser | VOD not enabled | Enable the VOD service first |
LimitExceeded.Quota | Quota exceeded | Lower concurrency or contact sales to raise it |
UnauthorizedOperation | Authorization | Check SecretId / SecretKey and permissions |
For the full list, see each API's "6. Error Code" and the Common Error Codes.
Related Documents โ
- API Reference: VOD 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.