跳到内容

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 调用都遵循同一套「五步」流程:

text
① 安装 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(国际版)演示完整流程。其余语言的客户端方法名一致,仅语法不同,请对照上表的开发者资源链接。

① 安装 ​

bash
pip install tencentcloud-sdk-python-intl-en

② 初始化客户端 ​

密钥通过环境变量注入,不要硬编码在代码里。地域按实际接入点填写(如 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)

③ 创建生成任务 ​

请求体用 SDK 的 from_json_string 填充,字段与 HTTP JSON 完全一致。SubAppId 必填;引擎专属选项通过 ExtInfo(JSON 字符串)传递。

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)

④ 轮询统一查询接口 ​

VOD 所有 AIGC 任务都用 DescribeTaskDetail 查询。推荐轮询间隔 3 秒,并同时确认 Status="FINISH" 与 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":
        # 具体结果字段按任务类型取: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。

其它语言要点 ​

语言安装客户端类备注
Pythonpip install tencentcloud-sdk-python-intl-envod_client.VodClient本文示例
JavaMaven 依赖 tencentcloud-sdk-java-intl-enVodClient请求对象 CreateAigcVideoTaskRequest 等
Gogo get github.com/tencentcloud/tencentcloud-sdk-go-intl-envod.NewClient包路径 vod/v20180717
Node.jsnpm i tencentcloud-sdk-nodejs-intl-enVodClient方法返回 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」及公共错误码。

相关文档 ​

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages