SDK Reference
本文介绍如何用腾讯云官方 SDK调用 VOD 的 AIGC 关键接口。相比手动构造 TC3 签名(见 API Reference 的「执行请求」),SDK 封装了签名、重试、序列化与错误处理,是生产环境的推荐方式。
接口的鉴权、请求结构、任务查询与存储规范与直连 HTTP 完全一致,仅调用层由 SDK 代劳。各模型的取值与示例请在左侧引擎菜单中查看。
VOD 与 MPS 的两点关键差异:① 查询动作统一为
DescribeTaskDetail(MPS 是每类一个DescribeAigcXxxTask);② API 版本为2018-07-17,SDK 客户端类是VodClient。
关键接口一览
VOD 的 AIGC 能力由三个生成接口 + 一个统一查询接口组成。每个接口在 SDK 里对应一个客户端方法(方法名与 Action 同名),下表给出各接口的官方开发者资源入口,可直接跳转到对应语言的 SDK 源码与示例。
| 能力 | 接口(Action) | SDK 开发者资源 |
|---|---|---|
| 图片生成 | CreateAigcImageTask | 开发者资源 |
| 视频 / 3D 生成 | CreateAigcVideoTask | 开发者资源 |
| 音频 / 音乐生成 | CreateAigcAudioTask | 开发者资源 |
| 通用任务查询 | DescribeTaskDetail | 开发者资源 |
每个接口文档的「5. Developer Resources」区段均提供 Python / Java / PHP / Go / Node.js / .NET / C++ 七种语言的 SDK 入口,统一位于 VOD v20180717 客户端。CLI 调用见 腾讯云命令行工具 TCCLI。
调用流程
无论图片、视频还是音频,SDK 调用都遵循同一套「五步」流程:
① 安装 SDK pip / maven / npm / go get …
② 初始化客户端 SecretId + SecretKey + 地域 → VodClient
③ 创建生成任务 CreateAigcXxxTask(带 SubAppId)→ 返回 TaskId
④ 轮询查询任务 DescribeTaskDetail,间隔 3 秒,直到 Status=FINISH
⑤ 处理结果 确认 ErrCode=0,取结果媒体;按 StorageMode 下载或管理- 生成接口只返回
TaskId,结果通过DescribeTaskDetail异步获取,不要期望生成接口直接返回媒体。 SubAppId为点播应用 ID。2023-12-25 之后开通点播的客户访问应用内资源时必须填写。- 结果有效期由
OutputConfig.StorageMode决定:Temporary保留7 天,Permanent则注册为 VOD 媒体资源长期保存(比 MPS 的12 小时预签名 URL 更长)。 - 生成请求会产生实际使用费用。若超时导致受理状态不明,先查任务再重试,避免重复计费。
Python 示例(以视频生成为例)
以下以 Python SDK(国际版)演示完整流程。其余语言的客户端方法名一致,仅语法不同,请对照上表的开发者资源链接。
① 安装
pip install tencentcloud-sdk-python-intl-en② 初始化客户端
密钥通过环境变量注入,不要硬编码在代码里。地域按实际接入点填写(如 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)③ 创建生成任务
请求体用 SDK 的 from_json_string 填充,字段与 HTTP JSON 完全一致。SubAppId 必填;引擎专属选项通过 ExtInfo(JSON 字符串)传递。
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)④ 轮询统一查询接口
VOD 所有 AIGC 任务都用 DescribeTaskDetail 查询。推荐轮询间隔 3 秒,并同时确认 Status="FINISH" 与 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":
# 具体结果字段按任务类型取:r.AigcVideoTask / r.AigcImageTask / r.AigcAudioTask
print("task finished:", r.TaskType)
break
if r.Status == "ABORTED":
raise RuntimeError("task aborted")
time.sleep(3)⑤ 处理结果
DescribeTaskDetail按TaskType(AigcImageTask/AigcVideoTask/AigcAudioTask)返回对应子任务结构,结果媒体与ErrCode/Message都在子任务里。StorageMode=Temporary的结果保留7 天;StorageMode=Permanent会注册为 VOD 媒体资源(返回FileId),可直接按点播媒体管理。- 任务失败时
ErrCode != 0,错误原因见子任务的Message。
其它语言要点
| 语言 | 安装 | 客户端类 | 备注 |
|---|---|---|---|
| Python | pip install tencentcloud-sdk-python-intl-en | vod_client.VodClient | 本文示例 |
| Java | Maven 依赖 tencentcloud-sdk-java-intl-en | VodClient | 请求对象 CreateAigcVideoTaskRequest 等 |
| Go | go get github.com/tencentcloud/tencentcloud-sdk-go-intl-en | vod.NewClient | 包路径 vod/v20180717 |
| Node.js | npm i tencentcloud-sdk-nodejs-intl-en | VodClient | 方法返回 Promise |
| PHP / .NET / C++ | 见各接口开发者资源链接 | VodClient | 方法名与 Action 一致 |
各语言的客户端初始化(密钥、地域、Endpoint)与方法签名细节,请以上表对应接口文档「5. Developer Resources」里的官方 SDK 源码为准。
错误码
SDK 会把 API 错误抛为 TencentCloudSDKException,异常里带 code 与 message。常见错误码与处理方式:
| 响应码 | 检查项 | 处理方法 |
|---|---|---|
InvalidParameter | 请求参数 | 检查模型名 / 版本 / 输入规范 |
InvalidParameter.ViolationContent | 输入审核被拦截 | 修改 Prompt 或图片 |
InvalidParameterValue.SubAppId | 应用 ID | 检查 SubAppId 是否为有效应用 ID |
FailedOperation.InvalidVodUser | 未开通 VOD | 先开通点播服务 |
LimitExceeded.Quota | 超出配额 | 降低并发或联系商务扩容 |
UnauthorizedOperation | 鉴权 | 检查 SecretId / SecretKey 及权限 |
完整错误码见各接口文档的「6. Error Code」及公共错误码。
相关文档
- API Reference:VOD 的认证、请求结构、任务查询与存储规范,含手动 TC3 签名脚本。
- 各接口开发者资源:见上方关键接口一览表格中的跳转链接。
- 腾讯云命令行工具 TCCLI:命令行与脚本化调用。