跳到内容

SDK Reference ​

更新时间

本文介绍如何用腾讯云官方 SDK调用 MPS 的 AIGC 关键接口。相比手动构造 TC3 签名(见 API Reference 的「请求执行」),SDK 封装了签名、重试、序列化与错误处理,是生产环境的推荐方式。

接口的鉴权、请求结构、任务状态与存储规范与直连 HTTP 完全一致,仅调用层由 SDK 代劳。各模型的专属参数请在左侧引擎菜单中查看。

关键接口一览 ​

MPS 的 AIGC 能力由「生成 + 查询」成对接口组成。每个接口在 SDK 里对应一个客户端方法(方法名与 Action 同名),下表给出各接口的官方开发者资源入口,可直接跳转到对应语言的 SDK 源码与示例。

能力生成接口(Action)查询接口(Action)SDK 开发者资源
图片CreateAigcImageTaskDescribeAigcImageTask生成 · 查询
视频 / 3DCreateAigcVideoTaskDescribeAigcVideoTask生成 · 查询
音频 / 音乐CreateAigcAudioTaskDescribeAigcAudioTask生成 · 查询

每个接口文档的「5. Developer Resources」区段均提供 Python / Java / PHP / Go / Node.js / .NET / C++ 七种语言的 SDK 入口,统一位于 MPS v20190612 客户端。CLI 调用见 腾讯云命令行工具 TCCLI。

调用流程 ​

无论图片、视频还是音频,SDK 调用都遵循同一套「五步」流程:

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

① 安装 ​

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

② 初始化客户端 ​

密钥通过环境变量注入,不要硬编码在代码里。地域按实际接入点填写(如 ap-singapore)。

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.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 字符串,需二次序列化。

python
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 秒。查询接口有频率上限,批量场景请用并发队列限流。

python
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 存储桶,遵循该桶的访问权限。

其它语言要点 ​

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

相关文档 ​

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