API Reference
VOD 的认证、请求结构、任务查询与存储规范。各模型的取值与示例请在左侧引擎菜单中查看。
调用规范
| 项目 | 取值 |
|---|---|
| 请求 | POST https://vod.intl.tencentcloudapi.com |
| API 版本 | 2018-07-17 |
| 认证 | TC3-HMAC-SHA256 / SecretId / SecretKey |
| Content-Type | application/json; charset=utf-8 |
| 公共请求头 | X-TC-Action / X-TC-Version / X-TC-Timestamp / X-TC-Region |
文本模型使用 Bearer 认证与 https://mmu.vod-qcloud.com。请参考 Text 调用规范。
生成 / 查询动作
| 类别 | 动作 | 用途 |
|---|---|---|
| 生成 | CreateAigcImageTask | 图片生成 |
| 生成 | CreateAigcVideoTask | 视频生成、3D 场景生成 |
| 生成 | CreateAigcAudioTask | 音效、音乐生成 |
| 查询 | DescribeTaskDetail | 所有 AIGC 任务的通用查询 |
与 MPS 不同,查询动作统一为一个。
执行请求
将 TC3 调用脚本保存为 tencent-api.py。脚本仅使用 Python 3 标准库,每次请求都会基于当前时间与请求体计算签名。设置 TENCENT_SECRET_ID / TENCENT_SECRET_KEY 环境变量后,请将引擎页面的 JSON 保存为 request.json。
python3 tencent-api.py vod CreateAigcImageTask request.jsonpython3 tencent-api.py vod CreateAigcVideoTask request.jsonpython3 tencent-api.py vod CreateAigcAudioTask request.jsonPOST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAigcImageTask
X-TC-Version: 2018-07-17
X-TC-Timestamp: <unix-timestamp>
X-TC-Region: ap-guangzhou
Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/vod/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=<Signature>生成请求会产生实际使用费用。若因超时而无法确认是否已受理,请在重复生成前先查询任务状态。临时凭证可通过 TENCENT_TOKEN 指定,地域可通过 --region 指定。
API 列表与请求参数
公共字段
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 可选 | Integer | VOD Application ID。新建 Application 需指定实际 ID。 |
ModelName | 必填 | String | 引擎名称 |
ModelVersion | 可选 | String | 引擎版本。省略时使用默认版本 |
Prompt | 必填 | String | 生成提示词 |
SceneType | 可选 | String | 指定特殊模式 |
FileInfos.N | 可选 | Array | 参考输入。Type / Category / Usage / Url |
OutputConfig | 可选 | Object | Resolution / Duration / AspectRatio / StorageMode 等 |
ExtInfo | 可选 | String | 高级选项。2 中的 JSON 编码字符串 |
FileInfos.N 的 Usage 表示参考用途。
| Usage | 含义 |
|---|---|
FirstFrame | 首帧 |
Reference | 参考输入 |
LastFrame | 尾帧 |
支持尾帧的模型使用 FileInfos.N.Usage=LastFrame。LastFrameUrl / LastFrameFileId 是与旧版接入保持兼容的字段。
响应与执行流程
任务查询
通过 DescribeTaskDetail 查询。需同时确认 Status="FINISH" 与 ErrCode=0。
python3 tencent-api.py vod DescribeTaskDetail query.jsonquery.json:
{
"SubAppId": 0,
"TaskId": "<task-id>"
}| Status | 处理方式 |
|---|---|
WAITING / PROCESSING | 继续轮询 |
FINISH | 为 ErrCode=0 即成功。出错时请确认 Message |
| 类型 | 状态 | 结果 URL |
|---|---|---|
| Image | AigcImageTask.Status | AigcImageTask.Output.FileInfos.FileUrl |
| Video | AigcVideoTask.Status | AigcVideoTask.Output.FileInfos.FileUrl |
| Music | AigcAudioTask.Status | AigcAudioTask.Output.AudioInfos.FileUrl |
受理响应
{
"Response": {
"TaskId": "<task-id>",
"RequestId": "<request-id>"
}
}TaskId 用于后续查询,RequestId 用于请求追踪。
响应示例
{
"AigcImageTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcImageGenFile.png",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1024,
"Height": 1024,
"Container": "png"
}
}
]
}
}
}{
"AigcVideoTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1920,
"Height": 1080,
"Duration": 5.07,
"Container": "mov,mp4,m4a",
"Bitrate": 9494850
}
}
]
}
}
}{
"AigcAudioTask": {
"Status": "FINISH",
"ErrCode": 0,
"Output": {
"AudioInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcAudioGenFile.mp3"
}
]
}
}
}错误与调用限制
请同时确认响应的 HTTP 状态、错误码及请求标识符。认证与权限类错误请在确认配置后重新发起请求;若任务或资源已创建,请在重新提交前先查询当前状态。各 API 的限制与错误码请参考下方相关文档。
请求示例
请使用所调用模型或协议的请求示例。请勿在同一个请求中混用不同路径的认证方式与请求字段。请同时查阅下方引擎文档与各协议的参数说明。
结果与资源管理
结果存储
| StorageMode | 有效期 |
|---|---|
Temporary | 7 天 |
Permanent | 永久。注册为 VOD 媒体资源 |
比 MPS 路径的 12 小时 更长,使用 Permanent 则可直接按 VOD 媒体进行管理。
{
"OutputConfig": {
"StorageMode": "Permanent"
}
}解除内容护栏
视频方面可应用于 Kling / Vidu / Wan / Happyhorse / Hailuo H3。不适用于 Hailuo 的其他版本。WAND-Vega-Video 的支持范围请参考相应引擎文档。不适用于 VS。不适用于 Hy Image。
如需使用解除内容护栏参数,须先联系商务对接人确认使用权限。即使在受支持的引擎上,也仅在显式传入该参数时才会解除内容护栏。省略参数则不会解除。
| 参数 | 解除值 | 适用对象 |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | 解除输入审核 |
OutputConfig.OutputComplianceCheck | Disabled | 解除输出审核 |
请将以下配置合并到现有的生成请求中。若要同时解除输入与输出审核,请一并传入两个字段。
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}MPS 使用 ExtraParameters 的 Boolean 值。请勿将 VOD 的 OutputConfig 与字符串 Disabled 原样传入 MPS。请参考 MPS API Reference。
引擎目录与相关文档
Image
通过 VOD 路径调用的图片生成。动作为 CreateAigcImageTask,结果查询为 DescribeTaskDetail。与 MPS 路径(mps-image)的动作名称相同,但参数结构不同。
WAND-Vega-Image 接入
WAND-Vega-Image 的 VOD 请求规范与生成示例请参考 WAND-Vega-Image。
与 MPS 路径的差异
| 类别 | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API 版本 | 2018-07-17 | 2019-06-12 |
| 参考图片 | FileInfos.N (Type + Url) | ImageInfos.N (ImageUrl) |
| 分辨率 / 比例 | OutputConfig.Resolution / OutputConfig.AspectRatio | ExtraParameters.Resolution / ExtraParameters.AspectRatio |
| 输出张数 | OutputConfig.OutputImageCount | OutputImageCount (最顶层) |
| 引擎专用参数 | ExtInfo = {"AdditionalParameters": "<JSON 字符串>"} (2 中编码) | AdditionalParameters (JSON 字符串,1 中) |
| 结果查询 | DescribeTaskDetail | DescribeAigcImageTask |
| 状态值 | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| 结果 URL | Output.FileInfos.FileUrl + ExpireTime | ImageInfos.Url (COS 预签名,12 小时) |
支持的引擎
| 引擎 | ModelName | ModelVersion |
|---|---|---|
| Nano Banana | GEM | 3.6 / 3.1 / 3.1-lite / 3.0 / 2.5 |
| Hunyuan | Hunyuan | 3.5-preview / 3.0 |
| WAND-Vega-Image | wand-vega-image | 1.0-pro / 1.0-flash / 1.0-lite |
| Qwen | Qwen | 0925 |
| Seedream 5.x | SI | 5.5 / 5.0-flash / 5.0-pro |
| Seedream | Seedream | 5.0-lite / 4.5 / 4.0 |
| Kling | Kling | 4.0 / 4.0-long / 3.0-Omni / 3.0 / O1 / 2.1 |
| Jimeng | Jimeng | 4.0 |
| Midjourney | MJ | v8.2 / v8.1 / v7 / niji_7 |
| Vidu | Vidu | q2 |
| GPT-Image | OG | image2_* / image2.5_sunburst_* / image2.5_flare_* / image2.6_sunburst_* / image2.6_flare_* |
公共请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 可选 | Integer | VOD 应用 ID |
ModelName | 必填 | String | 引擎名称 |
ModelVersion | 可选 | String | 引擎版本 |
Prompt | 可选 | String | 生成提示词。文本输入模式下为必填 |
NegativePrompt | 可选 | String | 负面提示词 |
SceneType | 可选 | String | 3d_panorama(Hunyuan 全景)、image_expand(Kling 扩展)等 |
FileInfos.N | 可选 | Array | 参考图片。通过 ReferenceType=mask 指定蒙版 |
OutputConfig | 可选 | Object | 输出设置 |
ExtInfo | 可选 | String | 引擎专用扩展参数 |
SessionId | 可选 | String | 用于去重的键 |
SessionContext | 可选 | String | 回调透传值。最多 1000 字 |
OutputConfig
| 字段 | 说明 |
|---|---|
Resolution | 1K / 2K / 4K 等。各引擎允许的取值不同 |
AspectRatio | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 等 |
OutputImageCount | 输出张数。各模型允许的范围请参考详细文档 |
OutputFormat | jpeg / png / webp。未指定时使用模型默认值 |
StorageMode | Temporary(7 天) / Permanent |
MediaName | 为 StorageMode=Permanent 时的媒体名称 |
PersonGeneration | AllowAdult / Disallowed。是否允许生成人物 |
InputComplianceCheck | 为 Disabled 时解除受支持引擎的输入审核。Hy Image 除外。使用前请咨询商务对接人 |
OutputComplianceCheck | 为 Disabled 时解除受支持引擎的输出审核。Hy Image 除外。使用前请咨询商务对接人 |
ExtInfo
图片生成与视频一样,使用 2 中的 JSON 编码。
{
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\":\\\"1536x1024\\\"}\"}"
}Video
通过 VOD 路径调用的视频生成。动作为 CreateAigcVideoTask,结果查询为 DescribeTaskDetail。
与 MPS 路径的差异
即使使用相同的引擎名称,填入参数的位置也不同。
| 类别 | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API 版本 | 2018-07-17 | 2019-06-12 |
| 首帧 | FileInfos.N + Usage=FirstFrame | ImageUrl |
| 尾帧 | FileInfos.N + Usage=LastFrame,或 LastFrameUrl | LastImageUrl |
| 多参考图片 | FileInfos.N (Category + Usage) | ImageInfos.N |
| 参考视频 | FileInfos.N + Category=Video | VideoInfos.N |
| 视频时长 | OutputConfig.Duration | 最顶层 Duration |
| 分辨率 / 比例 | OutputConfig.Resolution / OutputConfig.AspectRatio | ExtraParameters.Resolution / ExtraParameters.AspectRatio |
| 音画同生 | OutputConfig.AudioGeneration | ExtraParameters.EnableAudio |
| 引擎专用参数 | ExtInfo = {"AdditionalParameters": "<JSON 字符串>"} (2 中编码) | AdditionalParameters (JSON 字符串,1 中) |
| 结果查询 | DescribeTaskDetail | DescribeAigcVideoTask |
| 状态值 | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
| 结果 URL | Output.FileInfos.FileUrl + ExpireTime | VideoInfos.Url (COS 预签名,12 小时) |
支持的引擎
| 引擎 | ModelName | 代表 ModelVersion |
|---|---|---|
| Vega | wand-vega-video | 1.5-pro / 1.0-pro / 1.0-lite |
| Kling | Kling | 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 |
| Vidu | Vidu | q4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 / 2.0 |
| PixVerse | PixVerse | c1 / v6 / v5.6 |
| Hailuo | Hailuo | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
| GV | ||
| Hunyuan | Hunyuan | 1.5 / 3d_2.0 (SceneType=3d_scene) |
| Wan | Wan | 3.0 / 3.0-prime |
| Mingmou | Mingmou | 1.0 |
| VS | VS | 2.5 / 2.0 / 2.0-fast / 2.0-mini |
| SV | SV | 1.5-pro / 1.0-pro / 1.0-pro-fast |
| Happyhorse | H2 | 1.1 / 1.0 |
公共请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 可选 | Integer | VOD 应用 ID。2023-12-25 之后开通的账号为必填 |
ModelName | 必填 | String | 引擎名称 |
ModelVersion | 可选 | String | 引擎版本。未指定时使用稳定版本 |
Prompt | 可选 | String | 生成提示词。文本输入模式下为必填 |
NegativePrompt | 可选 | String | 负面提示词 |
EnhancePrompt | 可选 | String | Enabled / Disabled。自动增强提示词 |
SceneType | 可选 | String | 各引擎的特殊模式(motion_control / lip_sync / avatar_i2v / template_effect / 3d_scene / image_expand 等) |
FileInfos.N | 可选 | Array | 参考输入(图片、视频、音频) |
SubjectInfos.N | 可选 | Array | 指定已注册的参考对象 |
LastFrameUrl / LastFrameFileId | 可选 | String | 尾帧 |
OutputConfig | 可选 | Object | 输出设置 |
ExtInfo | 可选 | String | 引擎专用扩展参数 |
SessionId | 可选 | String | 用于去重的键。相同取值的重复请求将以已有请求为准处理 |
SessionContext | 可选 | String | 回调透传值。最多 1000 字 |
FileInfos.N
参考输入统一按 FileInfos 一类处理。通过 Category 区分种类,通过 Usage 区分角色。
| 字段 | 说明 |
|---|---|
Type | Url(外部 URL) 或 File(VOD FileId) |
Url | Type=Url 时的地址 |
FileId | Type=File 时的 VOD 媒体文件 ID |
Category | Image / Video / Audio |
Usage | FirstFrame(首帧) / LastFrame(尾帧) / Reference(参考) |
ReferenceType | 参考性质。允许值与组合参见模型详情 |
ObjectId | 用于参考生成的临时参考对象名称 |
Text | 图片名称。在提示词中以 @名称 形式引用 (PixVerse 多图模式) |
Usage 需逐个参考项附加
多参考时必须为所有项指定 Usage。若仅指定部分,其余项可能被忽略。
OutputConfig
| 字段 | 说明 |
|---|---|
Resolution | 480P / 720P / 1080P / 2K / 4K |
Duration | 视频时长(秒)。各引擎与版本的允许范围不同 |
AspectRatio | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 等 |
AudioGeneration | Enabled / Disabled。音画同生 |
StorageMode | Temporary(7 天) / Permanent(发放 FileId) |
MediaName | StorageMode=Permanent 时存储的媒体名称 |
InputComplianceCheck | Disabled 时解除支持引擎的输入审核。Hy Image 除外。使用前请咨询销售负责人 |
OutputComplianceCheck | Disabled 时解除支持引擎的输出审核。Hy Image 除外。使用前请咨询销售负责人 |
ExtInfo
引擎专用参数在 ExtInfo 中以 2 的 JSON 编码指定。ExtInfo 本身是 JSON 字符串,其中的 AdditionalParameters 值也是 JSON 字符串。
{
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true}\"}"
}生成顺序如下。
import json
params = {"multi_shot": True}
inner = json.dumps(params, ensure_ascii=False) # 第一次序列化
ext = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False) # 第二次序列化各服务的扩展参数
MPS 在顶层 AdditionalParameters 中放入 JSON 字符串,VOD 则在 ExtInfo 内编码。
后处理:超分输出
将生成结果保存为 Permanent 以获取 FileId,随后通过 VOD 超分输出模板或工作流进行后处理。
新增说明与调用范围
GV 的 3.1-lite 是需要确认 VOD 详细调用规格的版本。请查看 VOD GV 详情。
Music
这是通过 VOD 路径调用的音频生成。动作为 CreateAigcAudioTask,结果查询为 DescribeTaskDetail。场景分为 sfx(音效) 与 music(音乐) 两种,场景与引擎遵循固定映射。
与 MPS 路径的差异
| 分类 | VOD (vod.intl.tencentcloudapi.com) | MPS (mps.tencentcloudapi.com) |
|---|---|---|
| API 版本 | 2018-07-17 | 2019-06-12 |
| 视频时长 | OutputConfig.Duration | 顶层 Duration |
| 输出格式 | OutputConfig.OutputAudioFormat | OutputConfig.OutputAudioFormat 或顶层 |
| 引擎扩展参数 | 顶层 AdditionalParameters (JSON 字符串,1 层) | 顶层 AdditionalParameters (JSON 字符串,1 层) |
| 结果查询 | DescribeTaskDetail | DescribeAigcAudioTask |
| 状态值 | FINISH + ErrCode=0 | WAIT / RUN / DONE / FAIL |
音频扩展参数
音频扩展参数在 VOD / MPS 中均于顶层 AdditionalParameters 指定。
支持的引擎
场景 (SceneType) | 引擎 (ModelName) | ModelVersion | 备注 |
|---|---|---|---|
sfx | Kling | 使用默认值 | text-to-sfx, video-to-sfx |
music | MiniMaxMusic | 3.0 / 2.6 / 2.5 / 2.0 | 支持歌词输入 |
music | GL (Google Lyria) | 3.0-clip / 3.0-pro | 歌词包含在提示词中 |
music | Tme | 使用默认值 | 生成翻唱音源 |
| 无需填写 | Mureka | song_9.5 / song_9 / song_8 / easy_song_9.5 / instrumental_9.5 | song_* 歌词生歌曲(lyrics);easy_song_9.5 只支持提示词生歌曲;instrumental_9.5 生成器乐曲 |
| 无需填写 | EL (ElevenLabs) | compose_v2.5 / compose_v2 / compose_detailed_v2.5 | 提示词生音乐 |
| 无需填写 | EL (ElevenLabs) | sound_t2s_v3 / sound_t2s_v2 | 文生音效,Duration 为 [1, 30] |
Mureka/EL由ModelVersion区分模式,不使用SceneType。2026-11-16 新增song_9.5/easy_song_9.5/instrumental_9.5与compose_v2.5/compose_detailed_v2.5/sound_t2s_v3。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 可选 | Integer | VOD 应用 ID |
ModelName | 可选 | String | Kling / MiniMaxMusic / GL / Tme / Mureka / EL。默认值 Kling |
ModelVersion | 条件必填 | String | MiniMaxMusic / GL 为可选。Mureka / EL 靠版本区分模式,建议显式指定。指定时仅允许支持的版本 |
SceneType | 可选 | String | sfx / music。Mureka / EL 无需填写 |
Prompt | 可选 | String | 音频描述。文本输入模式下为必填 |
VideoInfos.N | 可选 | Array | 用于 video-to-sfx 的参考视频 |
AudioInfos.N | 可选 | Array | 参考音频 |
OutputConfig | 可选 | Object | 输出设置 |
AdditionalParameters | 可选 | String | 引擎扩展参数 (JSON 字符串) |
OutputConfig
| 字段 | 说明 |
|---|---|
StorageMode | Temporary(7 天) / Permanent |
MediaName | StorageMode=Permanent 时的媒体名称 |
Duration | 时长(秒)。Kling text-to-sfx 为 [3, 10],EL sound_t2s_v2 / sound_t2s_v3 为 [1, 30]。video-to-sfx 与 Mureka / EL compose_* 音乐中不适用 |
OutputAudioFormat | 输出格式。例:mp3 / wav(Mureka 支持 mp3 / wav / flac)。未指定时为模型默认值 |
AdditionalParameters
承载各模型选项的 JSON 字符串。请查看 Kling、MiniMaxMusic、Tme、Mureka(lyrics)的详细字段。
3D
3D 专属模型 / 模式 / 输入输出规格请在 Hy 3D Panorama 与 Hy World Model 中查看。认证 / 任务状态 / 存储策略遵循本文档的通用规范。