Skip to content

SDK Reference โ€‹

Updated

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 one DescribeAigcXxxTask per type); โ‘ก the API version is 2018-07-17, and the SDK client class is VodClient.

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.

CapabilityAPI (Action)SDK Developer Resources
Image generationCreateAigcImageTaskDeveloper Resources
Video / 3D generationCreateAigcVideoTaskDeveloper Resources
Audio / Music generationCreateAigcAudioTaskDeveloper Resources
Unified task queryDescribeTaskDetailDeveloper 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:

text
โ‘  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 via DescribeTaskDetail. Do not expect the generate API to return the media directly.
  • SubAppId is 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: Temporary keeps the result for 7 days, while Permanent registers it as a VOD media asset for long-term storage (longer than MPS's 12-hour pre-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 โ€‹

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

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

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

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

  • DescribeTaskDetail returns the corresponding sub-task structure by TaskType (AigcImageTask / AigcVideoTask / AigcAudioTask). The result media, ErrCode, and Message are inside that sub-task.
  • A StorageMode=Temporary result is kept for 7 days; StorageMode=Permanent registers it as a VOD media asset (returns a FileId) that you can manage as a regular VOD media.
  • On failure, ErrCode != 0; the reason is in the sub-task's Message.

Notes for Other Languages โ€‹

LanguageInstallClient classNote
Pythonpip install tencentcloud-sdk-python-intl-envod_client.VodClientExample in this page
JavaMaven dependency tencentcloud-sdk-java-intl-enVodClientRequest objects CreateAigcVideoTaskRequest, etc.
Gogo get github.com/tencentcloud/tencentcloud-sdk-go-intl-envod.NewClientPackage path vod/v20180717
Node.jsnpm i tencentcloud-sdk-nodejs-intl-enVodClientMethods return a Promise
PHP / .NET / C++See each API's developer resource linkVodClientMethod 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
InvalidParameterValue.SubAppIdApplication IDCheck that SubAppId is a valid application ID
FailedOperation.InvalidVodUserVOD not enabledEnable the VOD service first
LimitExceeded.QuotaQuota exceededLower concurrency or contact sales to raise it
UnauthorizedOperationAuthorizationCheck SecretId / SecretKey and permissions

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

Built with VitePress ยท Deployed on Tencent EdgeOne Pages