跳到内容

API Reference ​

更新时间

MPS 的认证、请求结构、任务查询与存储规范。各模型的值与示例请在左侧引擎菜单中查看。

调用规范 ​

项目值
请求POST https://mps.intl.tencentcloudapi.com
API 版本2019-06-12
认证TC3-HMAC-SHA256 / SecretId / SecretKey
Content-Typeapplication/json; charset=utf-8
公共请求头X-TC-Action / X-TC-Version / X-TC-Timestamp / X-TC-Region

生成 / 查询动作 ​

分类动作用途
生成CreateAigcImageTask图片生成
生成CreateAigcVideoTask视频生成、3D 场景生成
生成CreateAigcAudioTask音效、音乐生成
查询DescribeAigcImageTask图片任务查询
查询DescribeAigcVideoTask视频任务查询
查询DescribeAigcAudioTask音频任务查询

请求执行 ​

将 TC3 调用脚本保存为 tencent-api.py。仅使用 Python 3 标准库,每次请求都会基于当前时间与请求体计算签名。设置 TENCENT_SECRET_ID / TENCENT_SECRET_KEY 环境变量后,请将引擎页面的 JSON 保存为 request.json。

bash
python3 tencent-api.py mps CreateAigcImageTask request.json
bash
python3 tencent-api.py mps CreateAigcVideoTask request.json
bash
python3 tencent-api.py mps CreateAigcAudioTask request.json
http
POST / HTTP/1.1
Host: mps.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAigcImageTask
X-TC-Version: 2019-06-12
X-TC-Timestamp: <unix-timestamp>
X-TC-Region: ap-singapore
Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/mps/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<Signature>

生成请求会产生实际使用费用。若因超时导致是否受理不明确,请在重复生成前先确认任务状态。临时凭证可通过 TENCENT_TOKEN 指定,地域可通过 --region 指定。

SDK 调用 ​

除手动构造 TC3 签名外,也可直接使用腾讯云官方 SDK。SDK 封装了签名、重试与序列化,各语言版本的入口文件见下表(点击跳转至对应动作的「开发者资源 › SDK」)。

动作用途SDK 开发者资源
CreateAigcImageTask图片生成开发者资源
CreateAigcVideoTask视频生成开发者资源
CreateAigcAudioTask音频生成开发者资源
DescribeAigcImageTask图片任务查询开发者资源
DescribeAigcVideoTask视频任务查询开发者资源
DescribeAigcAudioTask音频任务查询开发者资源

各动作文档均提供 Python / Java / PHP / Go / Node.js / .NET / C++ 七种语言的 SDK 入口,统一位于 MPS v20190612 客户端。

CLI 调用 ​

若偏好在命令行或脚本中操作,可使用腾讯云命令行工具 TCCLI。安装、配置与命令格式请参考 腾讯云命令行工具 TCCLI。安装后,上述所有动作均可通过 tccli mps <Action> --cli-unfold-argument 的形式直接调用。

API 列表与请求参数 ​

输入规范 ​

项目限制
图片 URL需可外部访问。图片生成建议 7MB 以内,视频生成建议 10MB 以内
图片格式jpeg, png, webp
Prompt 长度图片 1000 字,视频 2000 字
音频同时生成EnableAudio 仅在受支持的版本生效
时长按各引擎 Duration 支持范围指定

公共字段 ​

字段用途
Operator调用方标识字符串
StoreCosParamCOS 存储位置
AdditionalParameters承载模型专属选项的 JSON 字符串

响应与执行流程 ​

任务查询 ​

  1. 调用生成动作 → 接收 TaskId
  2. 轮询查询动作 → 当 Status 为 DONE 时接收结果 URL
  3. 下载结果或转存到自有存储

推荐轮询间隔为 3 秒。查询 API 存在调用频率限制,请参考下表。

Status含义处理
WAIT等待中继续轮询
RUN执行中继续轮询
DONE完成接收结果 URL
FAIL需确认结果确认 Message 并决定后续请求
bash
python3 tencent-api.py mps DescribeAigcImageTask query.json
bash
python3 tencent-api.py mps DescribeAigcVideoTask query.json
bash
python3 tencent-api.py mps DescribeAigcAudioTask query.json

query.json:

json
{
  "TaskId": "<task-id>"
}

受理响应 ​

json
{
  "Response": {
    "TaskId": "<task-id>",
    "RequestId": "<request-id>"
  }
}

TaskId 用于后续查询,RequestId 用于请求追踪。

视频查询响应中的 CoverUrl 是代表性帧 URL。

响应示例 ​

json
{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "ImageUrls": [
      "https://aigc-output-image-<id>.cos.<region>.myqcloud.com/<file>.png?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}
json
{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "Resolution": "1920x1080",
    "VideoUrls": [
      "https://aigc-output-video-<id>.cos.<region>.myqcloud.com/<file>.mp4?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}
json
{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "AudioInfos": [
      {
        "Url": "https://aigc-output-audio-file-<id>.cos.<region>.myqcloud.com/<file>.mp3?q-sign-algorithm=sha1&..."
      }
    ],
    "VideoInfos": ,
    "RequestId": "<request-id>"
  }
}
json
{
  "Response": {
    "Status": "DONE",
    "TaskId": "<task-id>",
    "VideoUrl": "https://<bucket>.cos.<region>.myqcloud.com/<file>.mp4",
    "CoverUrl": "https://<bucket>.cos.<region>.myqcloud.com/<cover>.jpg",
    "RequestId": "<request-id>"
  }
}

错误与调用限制 ​

调用频率限制 ​

对象限制
图片生成 / 查询每秒 20 次
视频生成每秒 10 次
视频查询每秒 20 次

批量处理时,设置限制并发执行数量的队列更为稳妥。

响应码 ​

响应码检查项处理方法
InvalidParameter请求参数检查模型名 / 版本 / 输入规范
InvalidParameter.ViolationContent输入审核被拦截。Prompt 或图片违反策略修改 Prompt 或图片
AuthFailure认证检查 SecretId、SecretKey、时间戳、签名
RequestLimitExceeded超出调用频率降低请求速率或引入队列
FailedOperation处理结果检查响应 Message

请求示例 ​

请使用待调用模型或协议的请求示例。不要在同一个请求中混用不同路径的鉴权方式与请求字段。请同时参考下方的引擎文档与各协议参数。

结果与资源管理 ​

结果存储 ​

默认的临时结果 URL 有效期为 12 小时。如需将结果保存到自有存储桶,请在生成请求中指定 StoreCosParam。自有存储桶的结果 URL 遵循该存储桶的访问权限,私有对象可通过 COS SDK 或签名 URL 下载。

json
{
  "StoreCosParam": {
    "CosBucketName": "<bucket>",
    "CosBucketRegion": "<region>",
    "CosBucketPath": "aigc/video/"
  }
}

如需使用 COS 存储,目标存储桶必须已委托 MPS_QcsRole 角色。

分辨率与超分输出 ​

通过 ExtraParameters.Resolution 指定 720P / 1080P / 2K / 4K。超出模型可直接输出的分辨率的值,需经平台增强环节生成。若要提升已生成视频的画质,请使用 MPS 转码及增强模板。

模式输入输出
URL 模式向 API 传入 URL 执行任务COS、VOS、S3 等
File 模式以 COS 中已保存的文件为对象COS

内置增强模板分为动画场景与写实场景,720P / 1080P / 2K / 4K 输出的帧率沿用片源。降噪、超分输出与综合增强会一并应用。

应用超分输出处理时,先配置 COS 永久存储更为稳妥。12 小时 URL 过期后,增强任务的输入将丢失。

护栏解除 ​

在视频上可应用于 Kling / Vidu / Wan / Happyhorse / Hailuo H3。不适用于 Hailuo 的其他版本。WAND-Vega-Video 的支持范围请参考相应引擎文档。不适用于 VS。不适用于 Hy Image。

如需使用护栏解除参数,须先联系商务人员确认使用权限。即使在受支持的引擎上,也只有显式传递该参数时才会生效。省略该参数则不会解除。

参数解除值作用对象
ExtraParameters.EnablelnputComplianceCheckfalse解除输入审核
ExtraParameters.EnableOutputComplianceCheckfalse解除输出审核

将以下配置合并到已有的生成请求中。若要同时解除输入与输出审核,请一并传递这两个字段。

json
{
  "ExtraParameters": {
    "EnablelnputComplianceCheck": false,
    "EnableOutputComplianceCheck": false
  }
}

VOD 向 OutputConfig.InputComplianceCheck / OutputConfig.OutputComplianceCheck 传递字符串 Disabled。请勿与 MPS 的 Boolean false 混用。请参考 VOD API Reference。

模型附加配置 ​

Seed ​

seed 需指定在顶层 AdditionalParameters 的 JSON 字符串内。它与 ExtraParameters 对象是相互独立的字段。若同一请求中存在其他模型选项,请合并为一个 JSON 对象后再序列化。

json
{
  "AdditionalParameters": "{\"seed\":12312}"
}
python
import json

additional_parameters = json.dumps({"seed": 12312})

公共输入字段请参考 图片生成 API 与 视频生成 API。选项的适用范围因模型而异。

引擎目录与相关文档 ​

Image ​

Wan 2.2

通过 CreateAigcImageTask 生成图片。请区分指定公共请求字段与各模型的输出选项。支持的版本与专属选项请在各引擎文档中确认。

引擎列表 ​

引擎ModelNameModelVersion特点
Nano BananaGEM3.1 / 3.1-lite / 3.0 / 2.5参考图片最多 14 张
HunyuanHunyuan3.5-preview / 3.0通用生成、图片编辑、参考图最多 6 张
WAND-Vega-Imagewand-vega-image1.0-pro / 1.0-flash / 1.0-lite图片生成 / 参考图片编辑
QwenQwen0925通用生成
SeedreamSeedream5.0-pro / 5.0-lite / 4.5 / 4.0通用生成
KlingKling3.0-Omni / 3.0 / O1 / 2.1写实图片生成
JimengJimeng4.0通用生成
MidjourneyMJv8.2 / v8.1 / v7 / niji_7动画 / 插画风格调优
ViduViduq2通用生成
Image2OGimage2_* / image2.5_sunburst_* / image2.5_flare_*参考图片、自定义分辨率、蒙版编辑

WAND-Vega-Image 的输出尺寸在 AdditionalParameters 的 size 中指定。详细结构请参考 WAND-Vega-Image。

公共参数 ​

参数必填类型说明
ModelName必填String固定值 <ModelName>
ModelVersion选填String各引擎支持的版本
Prompt必填String生成 Prompt。各模型限制详见文档
EnhancePrompt选填BooleanPrompt 自动校正。默认值 false
ImageInfos.N选填Array参考图片数组。用于 image-to-image 及参考生成
ExtraParameters选填ObjectResolution / AspectRatio 等输出选项
AdditionalParameters选填String承载模型专属选项的 JSON 字符串
StoreCosParam选填ObjectCOS 永久存储配置
Operator选填String用于标识调用方的字符串

输入规范 ​

项目限制
图片 URL需可外部访问,建议 7MB 以内
格式jpeg, png, webp
Prompt 长度参见各模型限制

与 VOD 路径的差异 ​

虽然使用相同的 CreateAigcImageTask 动作名称,但 VOD 与 MPS 的调用对象与参数结构不同。

项目VOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API 版本2018-07-172019-06-12
首帧 / 原始图片FileInfos.N (以 Usage 区分)ImageInfos.N
引擎专属选项ExtInfo (JSON 字符串嵌套两层)AdditionalParameters (JSON 字符串 1 次)
存储方式OutputConfig.StorageMode = Temporary / Permanent结果为 COS 预签名 URL,可通过 StoreCosParam 永久存储
查询动作DescribeTaskDetailDescribeAigcImageTask
状态值Status="FINISH" + ErrCode=0WAIT / RUN / DONE / FAIL
结果有效期临时存储 7 天预签名 URL 12 小时

OG 的自定义分辨率传递位置不同

OG(Image2) 的自定义 size 在两条路径上都通过 AdditionalParameters 内的 size 字段传递,但 VOD 中该值会在 ExtInfo 内再嵌套一层。MPS 中则直接在 AdditionalParameters 字符串内指定。

json
"AdditionalParameters": "{\"size\":\"1536x1024\"}"
字段说明
CosBucketName要保存到的存储桶名称
CosBucketRegion存储桶地域
CosBucketPath存储桶内的保存路径

调用频率限制 ​

任务限制
图片生成每秒 20 次
图片查询每秒 20 次

在左侧菜单中选择引擎,即可查看该引擎的版本、专属选项与请求示例。

Video ​

通过 CreateAigcVideoTask 生成视频。分辨率与比例在 ExtraParameters 中指定,时长在顶层 Duration 中指定。引擎专属功能通过 SceneType 与 AdditionalParameters 指定。

引擎列表 ​

引擎ModelNameModelVersion特点
WAND-Vega-Videowand-vega-video1.5-pro / 1.0-pro / 1.0-lite基于文本 / 图片的视频生成
WanWan3.0 / 3.0-prime文本生成及首/尾帧生成
KlingKling3.0-Omni / 3.0 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 / O1动作控制、唇形同步。详细文档
HailuoHailuoH3 / 2.3 / 2.3-fast / 02
ViduViduq3-ad / q3-drama / q3 / q3-pro / q3-turbo / q3-mix / q2 系列多图参考、已注册的参考对象
VeoGV3.1 / 3.1-fast / 3.1-lite / omni视频参考、保持状态的一致性编辑、原生音频
PixVersePixVersec1 / v6 / v5.6分辨率分 4 档,参考生成
HunyuanHunyuan1.5首/尾帧
HappyhorseH21.1 / 1.0多图参考、参考视频(仅 1.0)
MingmouMingmou1.0land2port 横竖转换
VSVS2.5 / 2.0 / 2.0-fast / 2.0-mini高码率、音频同时生成
SVSeedance1.5-pro / 1.0-pro / 1.0-pro-fast—

SceneType ​

SceneType引擎用途
motion_controlKling动作控制
lip_syncKling唇形同步
avatar_i2vKling数字人
multi_elementsKling多元素编辑
template_effectVidu特效模板
land2portMingmou将横版视频重构为竖版构图
3d_sceneHunyuan3D 场景

公共参数 ​

参数必填类型说明
ModelName必填String固定值 <ModelName>
ModelVersion选填String各引擎支持的版本
Prompt必填String生成 Prompt。参见各模型限制
NegativePrompt选填String结果中需排除的元素。仅在受支持的模型上生效
EnhancePrompt选填BooleanPrompt 自动校正。默认值 false
ImageUrl选填String首帧图片 URL。需可外部访问且不超过 10MB
LastImageUrl选填String尾帧图片 URL。需与 ImageUrl 一起使用
ImageInfos.N选填Array参考图片数组。Category / Url / ReferenceType 等
Duration选填Integer生成时长(秒)。仅按各模型允许的值生效
ExtraParameters选填ObjectResolution / AspectRatio / EnableAudio
AdditionalParameters选填String承载模型专属选项的 JSON 字符串
StoreCosParam选填ObjectCOS 永久存储。CosBucketName / CosBucketRegion / CosBucketPath
Operator选填String用于标识调用方的字符串
ExtraParameters.
EnablelnputComplianceCheck
选填Boolean显式传递 false 即解除输入审核。使用前请咨询商务人员
ExtraParameters.
EnableOutputComplianceCheck
选填Boolean显式传递 false 即解除输出审核。使用前请咨询商务人员

与 VOD 路径的差异 ​

VOD 与 MPS 各自使用不同的 Endpoint 与参数结构。请在下表中查看 MPS 的请求字段。

项目VOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API 版本2018-07-172019-06-12
首帧FileInfos.N.Usage=FirstFrameImageUrl
尾帧FileInfos.N.Usage=LastFrame 或 LastFrameUrlLastImageUrl
参考图片FileInfos.NImageInfos.N
参考视频FileInfos.N (Category=Video)VideoInfos.N
视频时长OutputConfig.Duration顶层 Duration
分辨率 / 比例OutputConfig.Resolution / AspectRatioExtraParameters.Resolution / AspectRatio
音频生成OutputConfig.AudioGenerationExtraParameters.EnableAudio
引擎专属选项ExtInfo (JSON 字符串嵌套两层)AdditionalParameters (JSON 字符串 1 次)
存储方式OutputConfig.StorageMode = Temporary / Permanent结果为 COS 预签名 URL,可通过 StoreCosParam 永久存储
查询动作DescribeTaskDetailDescribeAigcVideoTask
状态值Status="FINISH" + ErrCode=0WAIT / RUN / DONE / FAIL
结果有效期临时存储 7 天预签名 URL 12 小时

切换路径时需重新映射参数

MPS 使用顶层 Duration 与 JSON 字符串 AdditionalParameters。VOD 中对应的项为 OutputConfig.Duration 与 ExtInfo。

字段说明
CosBucketName要保存到的存储桶名称
CosBucketRegion存储桶地域
CosBucketPath存储桶内的保存路径

调用频率限制 ​

任务限制
视频生成每秒 10 次
视频查询每秒 20 次

响应码 ​

代码说明
InvalidParameter.ViolationContent输入或输出违反内容策略
InvalidParameter检查输入字段与参数规范
AuthFailure检查认证配置
RequestLimitExceeded超出调用频率
FailedOperation检查处理结果

在左侧菜单中选择引擎,即可查看该引擎各版本支持的能力、专属选项与请求示例。

Music ​

Mureka / EL 音乐 / 音效

这是通过 MPS 路径调用的音频生成。动作为 CreateAigcAudioTask,结果查询为 DescribeAigcAudioTask。使用场景的模型需指定 sfx(音效) 或 music(音乐)。Mureka / EL 遵循模型详情中的请求结构。

与 VOD 路径的差异 ​

虽然使用相同的 CreateAigcAudioTask 动作,但 Endpoint 与结果查询方式不同。

分类VOD (vod.intl.tencentcloudapi.com)MPS (mps.intl.tencentcloudapi.com)
API 版本2018-07-172019-06-12
音频时长OutputConfig.Duration顶层 Duration
输出格式OutputConfig.OutputAudioFormat顶层 OutputAudioFormat
引擎扩展参数顶层 AdditionalParameters (JSON 字符串)顶层 AdditionalParameters (JSON 字符串)
MiniMaxMusic 歌词字段lyricslyric
MiniMaxMusic 人声移除字段instrumentalis_instrumental
Tme 参考音源AudioInfos.N 的 Type + UrlAudioInfos.N 的 AudioUrl
Tme 资源指定AdditionalParameters 的 ResourceIdExtraParameters 的 ResourceId
结果查询DescribeTaskDetailDescribeAigcAudioTask
状态值FINISH + ErrCode=0WAIT / RUN / DONE / FAIL
结果 URLOutput.AudioInfos.FileUrl + ExpireTime (临时 URL,7 天)AudioInfos.Url (含签名的临时 URL,12 小时)
永久存储OutputConfig.StorageMode=Permanent → VOD FileId通过 StoreCosParam 保存到自有 COS 存储桶

音频扩展参数

音频扩展参数在 VOD / MPS 中均于顶层 AdditionalParameters 指定。

支持的引擎 ​

场景 (SceneType)引擎 (ModelName)ModelVersion备注
sfxKling使用默认值text-to-sfx, video-to-sfx
musicMiniMaxMusic3.0 / 2.6 / 2.5 / 2.0支持歌词输入
musicGL (Google Lyria)3.0-clip / 3.0-pro歌词包含在 Prompt 中
musicTme使用默认值生成翻唱音源

使用 ModelName=GL。控制台的 Google Lyria 3 对应 3.0-clip,3 Pro 对应 3.0-pro。

项目MiniMaxMusicGL (Google Lyria)
歌词输入通过 AdditionalParameters 的 lyric 字段传递接口仅接收 Prompt 一个参数,因此需将风格与歌词合并在同一个 Prompt 中撰写
纯音乐{"is_instrumental": true} 或省略歌词生成演奏曲
输出格式MP3, WAVMP3
时长由模型决定3 约为 30 秒 的片段,3 Pro 为完整的歌曲结构

请求参数 ​

参数必填类型说明
ModelName必填StringKling / MiniMaxMusic / GL / Tme
ModelVersion选填String省略时使用稳定版本
SceneType条件必填String指定 Kling 等对应模型的场景。Mureka / EL 参见模型详情
Prompt选填String待生成音频的描述。最多 2000 字
VideoInfos.N选填Array参考视频。用于基于视频的音效
AudioInfos.N选填Array参考音频。用于生成翻唱音源。MPS 为 AudioUrl 字段
Duration选填Integer音频时长(秒)。0~60
OutputAudioFormat选填Stringmp3 或 wav
ExtraParameters选填Object各模型的附加选项。Tme 需要 ResourceId
AdditionalParameters选填String模型专属选项 JSON 字符串。lyric / is_instrumental / bgm_prompt / asmr_mode 等
字段类型说明
StatusStringWAIT / RUN / DONE / FAIL
MessageString处理结果消息。成功时为 ok
AudioInfosArray已生成的音频列表
AudioInfos.UrlString音频下载 URL。含签名的临时链接
VideoInfosArray音乐生成时为空数组

在左侧菜单中选择引擎,即可查看该引擎的歌词传递方式、专属选项与请求示例。

3D ​

3D 专属模型 / 模式 / 输入输出规格请在 Hy 3D Panorama 与 Hy World Model 中查看。认证 / 任务状态 / 存储策略遵循本文档的通用规范。

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