跳到内容

API Reference ​

更新时间

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

调用规范 ​

项目取值
请求POST https://vod.intl.tencentcloudapi.com
API 版本2018-07-17
认证TC3-HMAC-SHA256 / SecretId / SecretKey
Content-Typeapplication/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。

bash
python3 tencent-api.py vod CreateAigcImageTask request.json
bash
python3 tencent-api.py vod CreateAigcVideoTask request.json
bash
python3 tencent-api.py vod CreateAigcAudioTask request.json
http
POST / 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可选IntegerVOD Application ID。新建 Application 需指定实际 ID。
ModelName必填String引擎名称
ModelVersion可选String引擎版本。省略时使用默认版本
Prompt必填String生成提示词
SceneType可选String指定特殊模式
FileInfos.N可选Array参考输入。Type / Category / Usage / Url
OutputConfig可选ObjectResolution / 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。

bash
python3 tencent-api.py vod DescribeTaskDetail query.json

query.json:

json
{
  "SubAppId": 0,
  "TaskId": "<task-id>"
}
Status处理方式
WAITING / PROCESSING继续轮询
FINISH为 ErrCode=0 即成功。出错时请确认 Message
类型状态结果 URL
ImageAigcImageTask.StatusAigcImageTask.Output.FileInfos.FileUrl
VideoAigcVideoTask.StatusAigcVideoTask.Output.FileInfos.FileUrl
MusicAigcAudioTask.StatusAigcAudioTask.Output.AudioInfos.FileUrl

受理响应 ​

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

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

响应示例 ​

json
{
  "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"
          }
        }
      ]
    }
  }
}
json
{
  "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
          }
        }
      ]
    }
  }
}
json
{
  "AigcAudioTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Output": {
      "AudioInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcAudioGenFile.mp3"
        }
      ]
    }
  }
}

错误与调用限制 ​

请同时确认响应的 HTTP 状态、错误码及请求标识符。认证与权限类错误请在确认配置后重新发起请求;若任务或资源已创建,请在重新提交前先查询当前状态。各 API 的限制与错误码请参考下方相关文档。

请求示例 ​

请使用所调用模型或协议的请求示例。请勿在同一个请求中混用不同路径的认证方式与请求字段。请同时查阅下方引擎文档与各协议的参数说明。

结果与资源管理 ​

结果存储 ​

StorageMode有效期
Temporary7 天
Permanent永久。注册为 VOD 媒体资源

比 MPS 路径的 12 小时 更长,使用 Permanent 则可直接按 VOD 媒体进行管理。

json
{
  "OutputConfig": {
    "StorageMode": "Permanent"
  }
}

解除内容护栏 ​

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

如需使用解除内容护栏参数,须先联系商务对接人确认使用权限。即使在受支持的引擎上,也仅在显式传入该参数时才会解除内容护栏。省略参数则不会解除。

参数解除值适用对象
OutputConfig.InputComplianceCheckDisabled解除输入审核
OutputConfig.OutputComplianceCheckDisabled解除输出审核

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

json
{
  "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-172019-06-12
参考图片FileInfos.N (Type + Url)ImageInfos.N (ImageUrl)
分辨率 / 比例OutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
输出张数OutputConfig.OutputImageCountOutputImageCount (最顶层)
引擎专用参数ExtInfo = {"AdditionalParameters": "<JSON 字符串>"} (2 中编码)AdditionalParameters (JSON 字符串,1 中)
结果查询DescribeTaskDetailDescribeAigcImageTask
状态值FINISH + ErrCode=0WAIT / RUN / DONE / FAIL
结果 URLOutput.FileInfos.FileUrl + ExpireTimeImageInfos.Url (COS 预签名,12 小时)

支持的引擎 ​

引擎ModelNameModelVersion
Nano BananaGEM3.6 / 3.1 / 3.1-lite / 3.0 / 2.5
HunyuanHunyuan3.5-preview / 3.0
WAND-Vega-Imagewand-vega-image1.0-pro / 1.0-flash / 1.0-lite
QwenQwen0925
Seedream 5.xSI5.5 / 5.0-flash / 5.0-pro
SeedreamSeedream5.0-lite / 4.5 / 4.0
KlingKling4.0 / 4.0-long / 3.0-Omni / 3.0 / O1 / 2.1
JimengJimeng4.0
MidjourneyMJv8.2 / v8.1 / v7 / niji_7
ViduViduq2
GPT-ImageOGimage2_* / image2.5_sunburst_* / image2.5_flare_* / image2.6_sunburst_* / image2.6_flare_*

公共请求参数 ​

参数必填类型说明
SubAppId可选IntegerVOD 应用 ID
ModelName必填String引擎名称
ModelVersion可选String引擎版本
Prompt可选String生成提示词。文本输入模式下为必填
NegativePrompt可选String负面提示词
SceneType可选String3d_panorama(Hunyuan 全景)、image_expand(Kling 扩展)等
FileInfos.N可选Array参考图片。通过 ReferenceType=mask 指定蒙版
OutputConfig可选Object输出设置
ExtInfo可选String引擎专用扩展参数
SessionId可选String用于去重的键
SessionContext可选String回调透传值。最多 1000 字
OutputConfig ​
字段说明
Resolution1K / 2K / 4K 等。各引擎允许的取值不同
AspectRatio1:1 / 16:9 / 9:16 / 4:3 / 3:4 等
OutputImageCount输出张数。各模型允许的范围请参考详细文档
OutputFormatjpeg / png / webp。未指定时使用模型默认值
StorageModeTemporary(7 天) / Permanent
MediaName为 StorageMode=Permanent 时的媒体名称
PersonGenerationAllowAdult / Disallowed。是否允许生成人物
InputComplianceCheck为 Disabled 时解除受支持引擎的输入审核。Hy Image 除外。使用前请咨询商务对接人
OutputComplianceCheck为 Disabled 时解除受支持引擎的输出审核。Hy Image 除外。使用前请咨询商务对接人
ExtInfo ​

图片生成与视频一样,使用 2 中的 JSON 编码。

json
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\":\\\"1536x1024\\\"}\"}"
}

Video ​

通过 VOD 路径调用的视频生成。动作为 CreateAigcVideoTask,结果查询为 DescribeTaskDetail。

与 MPS 路径的差异 ​

即使使用相同的引擎名称,填入参数的位置也不同。

类别VOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API 版本2018-07-172019-06-12
首帧FileInfos.N + Usage=FirstFrameImageUrl
尾帧FileInfos.N + Usage=LastFrame,或 LastFrameUrlLastImageUrl
多参考图片FileInfos.N (Category + Usage)ImageInfos.N
参考视频FileInfos.N + Category=VideoVideoInfos.N
视频时长OutputConfig.Duration最顶层 Duration
分辨率 / 比例OutputConfig.Resolution / OutputConfig.AspectRatioExtraParameters.Resolution / ExtraParameters.AspectRatio
音画同生OutputConfig.AudioGenerationExtraParameters.EnableAudio
引擎专用参数ExtInfo = {"AdditionalParameters": "<JSON 字符串>"} (2 中编码)AdditionalParameters (JSON 字符串,1 中)
结果查询DescribeTaskDetailDescribeAigcVideoTask
状态值FINISH + ErrCode=0WAIT / RUN / DONE / FAIL
结果 URLOutput.FileInfos.FileUrl + ExpireTimeVideoInfos.Url (COS 预签名,12 小时)

支持的引擎 ​

引擎ModelName代表 ModelVersion
Vegawand-vega-video1.5-pro / 1.0-pro / 1.0-lite
KlingKling3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6
ViduViduq4-preview / q3-ad / q3-drama / q3-mix / q3-turbo / q3-pro / q3 / q2-pro / q2 / 2.0
PixVersePixVersec1 / v6 / v5.6
HailuoHailuoH3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02
GV
HunyuanHunyuan1.5 / 3d_2.0 (SceneType=3d_scene)
WanWan3.0 / 3.0-prime
MingmouMingmou1.0
VSVS2.5 / 2.0 / 2.0-fast / 2.0-mini
SVSV1.5-pro / 1.0-pro / 1.0-pro-fast
HappyhorseH21.1 / 1.0

公共请求参数 ​

参数必填类型说明
SubAppId可选IntegerVOD 应用 ID。2023-12-25 之后开通的账号为必填
ModelName必填String引擎名称
ModelVersion可选String引擎版本。未指定时使用稳定版本
Prompt可选String生成提示词。文本输入模式下为必填
NegativePrompt可选String负面提示词
EnhancePrompt可选StringEnabled / 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 区分角色。

字段说明
TypeUrl(外部 URL) 或 File(VOD FileId)
UrlType=Url 时的地址
FileIdType=File 时的 VOD 媒体文件 ID
CategoryImage / Video / Audio
UsageFirstFrame(首帧) / LastFrame(尾帧) / Reference(参考)
ReferenceType参考性质。允许值与组合参见模型详情
ObjectId用于参考生成的临时参考对象名称
Text图片名称。在提示词中以 @名称 形式引用 (PixVerse 多图模式)

Usage 需逐个参考项附加

多参考时必须为所有项指定 Usage。若仅指定部分,其余项可能被忽略。

OutputConfig ​
字段说明
Resolution480P / 720P / 1080P / 2K / 4K
Duration视频时长(秒)。各引擎与版本的允许范围不同
AspectRatio16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 等
AudioGenerationEnabled / Disabled。音画同生
StorageModeTemporary(7 天) / Permanent(发放 FileId)
MediaNameStorageMode=Permanent 时存储的媒体名称
InputComplianceCheckDisabled 时解除支持引擎的输入审核。Hy Image 除外。使用前请咨询销售负责人
OutputComplianceCheckDisabled 时解除支持引擎的输出审核。Hy Image 除外。使用前请咨询销售负责人
ExtInfo ​

引擎专用参数在 ExtInfo 中以 2 的 JSON 编码指定。ExtInfo 本身是 JSON 字符串,其中的 AdditionalParameters 值也是 JSON 字符串。

json
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true}\"}"
}

生成顺序如下。

python
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 ​

Mureka / EL 音乐 / 音效

这是通过 VOD 路径调用的音频生成。动作为 CreateAigcAudioTask,结果查询为 DescribeTaskDetail。场景分为 sfx(音效) 与 music(音乐) 两种,场景与引擎遵循固定映射。

与 MPS 路径的差异 ​

分类VOD (vod.intl.tencentcloudapi.com)MPS (mps.tencentcloudapi.com)
API 版本2018-07-172019-06-12
视频时长OutputConfig.Duration顶层 Duration
输出格式OutputConfig.OutputAudioFormatOutputConfig.OutputAudioFormat 或顶层
引擎扩展参数顶层 AdditionalParameters (JSON 字符串,1 层)顶层 AdditionalParameters (JSON 字符串,1 层)
结果查询DescribeTaskDetailDescribeAigcAudioTask
状态值FINISH + ErrCode=0WAIT / RUN / DONE / FAIL

音频扩展参数

音频扩展参数在 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歌词包含在提示词中
musicTme使用默认值生成翻唱音源
无需填写Murekasong_9.5 / song_9 / song_8 / easy_song_9.5 / instrumental_9.5song_* 歌词生歌曲(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可选IntegerVOD 应用 ID
ModelName可选StringKling / MiniMaxMusic / GL / Tme / Mureka / EL。默认值 Kling
ModelVersion条件必填StringMiniMaxMusic / GL 为可选。Mureka / EL 靠版本区分模式,建议显式指定。指定时仅允许支持的版本
SceneType可选Stringsfx / music。Mureka / EL 无需填写
Prompt可选String音频描述。文本输入模式下为必填
VideoInfos.N可选Array用于 video-to-sfx 的参考视频
AudioInfos.N可选Array参考音频
OutputConfig可选Object输出设置
AdditionalParameters可选String引擎扩展参数 (JSON 字符串)
OutputConfig ​
字段说明
StorageModeTemporary(7 天) / Permanent
MediaNameStorageMode=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 中查看。认证 / 任务状态 / 存储策略遵循本文档的通用规范。

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