SDK Reference
本文介绍如何用腾讯云官方 SDK调用 MPS 的 AIGC 关键接口。相比手动构造 TC3 签名(见 API Reference 的「请求执行」),SDK 封装了签名、重试、序列化与错误处理,是生产环境的推荐方式。
接口的鉴权、请求结构、任务状态与存储规范与直连 HTTP 完全一致,仅调用层由 SDK 代劳。各模型的专属参数请在左侧引擎菜单中查看。
关键接口一览
MPS 的 AIGC 能力由「生成 + 查询」成对接口组成。每个接口在 SDK 里对应一个客户端方法(方法名与 Action 同名),下表给出各接口的官方开发者资源入口,可直接跳转到对应语言的 SDK 源码与示例。
| 能力 | 生成接口(Action) | 查询接口(Action) | SDK 开发者资源 |
|---|---|---|---|
| 图片 | CreateAigcImageTask | DescribeAigcImageTask | 生成 · 查询 |
| 视频 / 3D | CreateAigcVideoTask | DescribeAigcVideoTask | 生成 · 查询 |
| 音频 / 音乐 | CreateAigcAudioTask | DescribeAigcAudioTask | 生成 · 查询 |
每个接口文档的「5. Developer Resources」区段均提供 Python / Java / PHP / Go / Node.js / .NET / C++ 七种语言的 SDK 入口,统一位于 MPS v20190612 客户端。CLI 调用见 腾讯云命令行工具 TCCLI。
调用流程
无论图片、视频还是音频,SDK 调用都遵循同一套「五步」流程:
① 安装 SDK pip / maven / npm / go get …
② 初始化客户端 SecretId + SecretKey + 地域 → MpsClient
③ 创建生成任务 CreateAigcXxxTask → 返回 TaskId
④ 轮询查询任务 DescribeAigcXxxTask,间隔 3 秒,直到 Status=DONE
⑤ 处理结果 取结果 URL(12 小时有效),下载或转存自有存储- 生成接口只返回
TaskId,结果通过查询接口异步获取,不要期望生成接口直接返回图片/视频。 - 默认结果 URL 有效期
12 小时;需长期保存请在生成请求中传StoreCosParam落到自有 COS。 - 生成请求会产生实际使用费用。若超时导致受理状态不明,先查任务再重试,避免重复计费。
Python 示例(以视频生成为例)
以下以 Python SDK(国际版)演示完整流程。其余语言的客户端方法名一致,仅语法不同,请对照上表的开发者资源链接。
① 安装
pip install tencentcloud-sdk-python-intl-en② 初始化客户端
密钥通过环境变量注入,不要硬编码在代码里。地域按实际接入点填写(如 ap-singapore)。
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)③ 创建生成任务
请求体用 SDK 的 from_json_string 填充,字段与 HTTP JSON 完全一致。AdditionalParameters 是 JSON 字符串,需二次序列化。
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)④ 轮询查询任务
推荐轮询间隔 3 秒。查询接口有频率上限,批量场景请用并发队列限流。
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)⑤ 处理结果
- 图片结果在
ImageUrls,视频在VideoUrls,音频在AudioInfos[].Url。 - 结果 URL 为 COS 预签名链接,默认
12 小时过期,请及时下载或转存。 - 若请求中带了
StoreCosParam,结果会落到自有 COS 存储桶,遵循该桶的访问权限。
其它语言要点
| 语言 | 安装 | 客户端类 | 备注 |
|---|---|---|---|
| Python | pip install tencentcloud-sdk-python-intl-en | mps_client.MpsClient | 本文示例 |
| Java | Maven 依赖 tencentcloud-sdk-java-intl-en | MpsClient | 请求对象 CreateAigcVideoTaskRequest 等 |
| Go | go get github.com/tencentcloud/tencentcloud-sdk-go-intl-en | mps.NewClient | 包路径 mps/v20190612 |
| Node.js | npm i tencentcloud-sdk-nodejs-intl-en | MpsClient | 方法返回 Promise |
| PHP / .NET / C++ | 见各接口开发者资源链接 | MpsClient | 方法名与 Action 一致 |
各语言的客户端初始化(密钥、地域、Endpoint)与方法签名细节,请以上表对应接口文档「5. Developer Resources」里的官方 SDK 源码为准。
错误码
SDK 会把 API 错误抛为 TencentCloudSDKException,异常里带 code 与 message。常见错误码与处理方式:
| 响应码 | 检查项 | 处理方法 |
|---|---|---|
InvalidParameter | 请求参数 | 检查模型名 / 版本 / 输入规范 |
InvalidParameter.ViolationContent | 输入审核被拦截 | 修改 Prompt 或图片 |
AuthFailure | 认证 | 检查 SecretId / SecretKey / 时间戳 / 签名 |
RequestLimitExceeded | 超出调用频率 | 降低请求速率或引入队列 |
FailedOperation | 处理结果 | 检查响应 Message |
完整错误码见各接口文档的「6. Error Code」及公共错误码。
相关文档
- API Reference:MPS 的认证、请求结构、任务查询与存储规范,含手动 TC3 签名脚本。
- 各接口开发者资源:见上方关键接口一览表格中的跳转链接。
- 腾讯云命令行工具 TCCLI:命令行与脚本化调用。