Hailuo
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Hailuo 是视频生成模型,支持文生视频、首帧 / 首尾帧生视频。H3 支持图片、视频、音频混合输入的多模态参考生成(图片 9 张 / 视频 3 个 / 音频 3 个,合计 12 个),H3-Max 面向文本与首尾帧的高规格生成,H3-Lite / H3-Highspeed(2026-11-12 上线)是轻量 / 兼顾速度与质量的版本,同样支持文生、首尾帧与多模态参考,H3_regen 用于对已有视频重新生成。默认输出 768P,可超分至 4K,时长 4~15 秒。
H3 系列共有 5 个 ModelVersion,规格差异见版本差异,各版本的调用写法见按版本调用。
基本信息
| 项目 | 值 |
|---|---|
| ModelName | Hailuo |
| ModelVersion | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
| 默认值 | ModelVersion=H3 / Resolution=1080P |
| 支持解除护栏 | 仅支持 H3 |
版本差异
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
H3 | 默认输出:768P超分输出: 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 4–15 秒 |
H3-Max | 默认输出:480P / 768P超分输出: 1080P / 2K / 4K | 16:9 / 9:16 / 4:3 / 3:4 / 1:1 / adaptive | 5–15 秒 |
H3-Lite | 默认输出:480P / 768P超分输出: 2K / 4K | 文生:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16图生:跟随输入图片 | 4–15 秒 |
H3-Highspeed | 默认输出:480P / 768P超分输出: 2K / 4K | 文生:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16图生:跟随输入图片 | 4–15 秒 |
02 / 2.3 | 参见各版本输出选项 | — | 6 秒10 秒 |
输入条件
| 版本 | 条件 |
|---|---|
H3 | 输入:参考图片 9 张 / 视频 3 个 / 音频 3 个,合计 12 个;与首 / 尾帧模式分开 |
H3-Max | 输入:文本或首 / 尾帧 |
H3-Lite / H3-Highspeed | 输入:文本;或首 / 尾帧图片 0~2 张(宽高 [256, 5760],宽高比 0.4~2.5,即 2:5 ~ 5:2);或参考图片 9 张 / 视频 3 个 / 音频 3 个,与首 / 尾帧模式二选一 |
02 / 2.3 | 输入:不套用 H3 多模态限制 |
上表中
H3-Lite/H3-Highspeed的参考素材上限取自 MiniMax 官方 V2 接口,VOD 接入指南只列出了「多模态参考」能力、没有给出数量。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
ModelName | 必填 | String | 固定值 Hailuo |
ModelVersion | 可选 | String | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
Prompt | 必填 | String | 生成提示词 |
FileInfos.N | 可选 | Array | 参考输入。Usage 为 FirstFrame(首帧)/ LastFrame(尾帧)/ Reference(参考) |
OutputConfig.Resolution | 可选 | String | 参见各版本规格 |
OutputConfig.Duration | 可选 | Integer | 视频时长(秒) |
OutputConfig.AspectRatio | 可选 | String | 16:9 / 9:16 / 1:1 等 |
OutputConfig.InputComplianceCheck | 可选 | String | 显式传递 Disabled 则解除输入审核。使用前请咨询商务负责人 |
OutputConfig.OutputComplianceCheck | 可选 | String | 显式传递 Disabled 则解除输出审核。使用前请咨询商务负责人 |
请求示例
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3",
"Prompt": "a calm sunset over the ocean, cinematic",
"OutputConfig": {
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}响应示例
{
"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
}
}
]
}
}
}按版本调用
H3 系列的请求结构完全一致,切换版本只需改 ModelVersion。下面按版本列出调用写法:H3 的首尾帧与多模态参考见「特殊设置」,H3-Lite / H3-Highspeed 见本节,H3_regen 见视频重新生成。
| 版本 | 文生 | 首帧 | 尾帧 | 首尾帧 | 多模态参考 | 重新生成 |
|---|---|---|---|---|---|---|
H3 | ✅ | ✅ | ✅ | ✅ | ✅ | — |
H3-Max | ✅ | ✅ | ✅ | ✅ | ⚠️ 上游支持,VOD 指南未列 | — |
H3-Lite | ✅ | ✅ | ✅ | ✅ | ✅(示例) | — |
H3-Highspeed | ✅ | ✅ | ✅ | ✅ | ✅ | — |
H3_regen | — | — | — | — | — | ✅ |
H3-Lite
2026-11-12 上线。ModelName=Hailuo,ModelVersion=H3-Lite。
| 项目 | 规格 |
|---|---|
| 生成模式 | 文生视频;首帧 / 尾帧 / 首尾帧生视频;多模态参考生成 |
| 提示词长度 | 最多 7000 字符(必填,不能为空) |
| 首 / 尾帧图片 | 0、1、2 张;宽高 [256, 5760];宽高比 0.4~2.5。无图片时按文生视频运行 |
| 参考素材 | 图片 ≤ 9 / 视频 ≤ 3 / 音频 ≤ 3,限制见多模态参考 |
| 比例 | 文生:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16,必须指定。图生:跟随输入图片,传入其他合理值不报错,但会被忽略并按 adaptive 处理。参考生成:必须显式指定具体比例(Lite 暂不支持 adaptive) |
| 分辨率 | 480P / 768P;超分输出 2K / 4K |
| 时长 | 4~15 秒 |
文生视频
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Lite",
"Prompt": "a princess in a castle room looks at the closed door, turns around, opens the window and gazes into the distance, her expression shifting from worry to relief",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "job-001"
}首帧生视频:FileInfos 放一张图,Usage=FirstFrame。
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Lite",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/first.png",
"Usage": "FirstFrame"
}
],
"Prompt": "she opens the window, looks into the distance, then runs out of the castle and rides away",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "job-001"
}尾帧生视频:只传一张 Usage=LastFrame 的图片,视频会以这张图作为结束画面。把上例的 Usage 改为 LastFrame 即可:
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/last.jpg",
"Usage": "LastFrame"
}
]首尾帧生视频:两张图分别声明 FirstFrame 与 LastFrame。
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Lite",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/first.png",
"Usage": "FirstFrame"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/last.jpg",
"Usage": "LastFrame"
}
],
"Prompt": "she opens the window, looks into the distance, then runs out of the castle and rides away",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "job-001"
}尾帧的两种旧写法仍兼容
推荐用 FileInfos.N.Usage=LastFrame 声明尾帧。历史写法——首帧放 FileInfos、尾帧用 LastFrameFileId / LastFrameUrl 指定——仍然兼容,但不推荐新接入使用。
多模态参考生成(H3-Lite)
FileInfos 中的素材全部声明 Usage=Reference,用 Category 区分图片 / 视频 / 音频。AspectRatio 必须写具体比例:官方接口说明 H3-Lite 在参考模式下暂不支持 adaptive(H3 / H3-Highspeed 不受此限)。
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Lite",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/ref-video.mp4",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Audio",
"Url": "https://<cos>/ref-voice.mp3",
"Usage": "Reference"
}
],
"Prompt": "the character says: follow the wind, live free. Voice timbre follows reference audio 1",
"OutputConfig": {
"Duration": 5,
"Resolution": "768P",
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}本例是把 MiniMax 官方「参考生成」示例(参考视频 + 参考音频,台词音色跟随音频)按本页的
FileInfos写法改写的。Category=Audio的写法沿用 VOD 通用FileInfos结构,接入指南没有给出 Lite 的参考示例,首次接入建议先小量实测。
H3-Highspeed
2026-11-12 上线。ModelName=Hailuo,ModelVersion=H3-Highspeed。
接入规格与 H3-Lite 基本一致(生成模式、提示词长度、首尾帧与参考素材限制、分辨率、时长均相同),请求只需把 ModelVersion 换成 H3-Highspeed。唯一差别:参考生成时 H3-Highspeed 支持 adaptive 比例,可不传 AspectRatio。官方定位是「兼顾生成质量与速度」,Lite 是「轻量版」;价格以《AIGC 价格指南(客户)》为准,两者都没有公开生成耗时对比。
文生视频
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Highspeed",
"Prompt": "a princess in a castle room looks at the closed door, turns around, opens the window and gazes into the distance, her expression shifting from worry to relief",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "job-001"
}首尾帧生视频(只传首帧或只传尾帧时,保留对应的一项即可;参考生成把 ModelVersion 换掉即可复用 H3-Lite 参考示例,写法同 H3-Lite)
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3-Highspeed",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/first.png",
"Usage": "FirstFrame"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/last.jpg",
"Usage": "LastFrame"
}
],
"Prompt": "she opens the window, looks into the distance, then runs out of the castle and rides away",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"SessionContext": "job-001"
}H3-Lite / H3-Highspeed 没有 1080P 档
接入指南给出的分辨率只有 480P / 768P(原生)与 2K / 4K(超分),没有 1080P。从 H3 切过来时,如果原请求写的是 Resolution=1080P,请改为上述取值之一。MiniMax 官方接口也写明这两版原生不支持 2K,所以 VOD 上的 2K / 4K 是超分产物,不是原生出图。
特殊设置
解除护栏
Hailuo 仅在 ModelVersion=H3 中支持解除护栏。请勿对其他版本同样套用。
要使用护栏解除参数,请先联系商务负责人确认使用权限。即使在支持的引擎中,也只有显式传递该参数时才会应用护栏解除。省略参数则不会解除。
| 参数 | 解除值 | 适用对象 |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | 解除输入审核 |
OutputConfig.OutputComplianceCheck | Disabled | 解除输出审核 |
将以下设置合并到现有生成请求中。要同时解除输入与输出审核,请一并传递两个字段。
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}H3 系列版本对比
| 项目 | H3 | H3-Max | H3-Lite | H3-Highspeed |
|---|---|---|---|---|
| 文本生成视频 | ✅ | ✅ | ✅ | ✅ |
| 首帧 / 尾帧 / 首尾帧 | ✅ | ✅ | ✅ | ✅ |
| 多模态参考(图片 / 视频 / 音频) | ✅ | ⚠️ 上游支持,VOD 指南未列 | ✅ | ✅ |
| 参考生成可用 adaptive 比例 | ✅ | — | ❌ 须指定比例 | ✅ |
| 上游原生分辨率 | 768P / 2K | 480P / 768P | 480P / 768P | 480P / 768P |
| 官方定位 | 高质量创作 | 快速生成 | 轻量版 | 兼顾质量与速度 |
| 视频时长 | 4~15 秒 | 5~15 秒 | 4~15 秒 | 4~15 秒 |
| 分辨率 | 768P / 1080P / 2K / 4K | 768P / 1080P / 2K / 4K | 480P / 768P / 2K / 4K | 480P / 768P / 2K / 4K |
| 提示词长度 | 最多 7000 字符 | 最多 7000 字符 | 最多 7000 字符 | 最多 7000 字符 |
| 解除护栏 | ✅ | — | — | — |
多模态参考一行据 MiniMax 官方 V2 接口更新:
H3-Lite/H3-Highspeed与H3共用同一套参考素材限制。⚠️ 官方接口同样写明H3-Max支持参考生成,但 VOD 接入指南只给 Max 列了「文本或首 / 尾帧」,经 VOD 调用 Max 做参考生成前请先与产品确认。
参考生成模型选择
追求质量用 H3;需要更快 / 更省时用 H3-Highspeed;H3-Lite 也可用,但必须显式指定比例。
首 / 尾帧(H3)
用 FileInfos.N.Usage 指定 FirstFrame / LastFrame。图片可从 0 张、1 张、2 张 中选择,宽高须在 [256, 5760] 范围内,比例须在 5:2 ~ 2:5 之间。若无图片则按文本生成视频运行。
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/first.png",
"Usage": "FirstFrame"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/last.jpg",
"Usage": "LastFrame"
}
],
"Prompt": "she opens the window, looks into the distance, then runs out of the castle and rides away",
"OutputConfig": {
"Duration": 10,
"Resolution": "2K",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled",
"StorageMode": "Permanent"
},
"SessionContext": "job-001"
}图片生成视频的宽高比遵循输入图片
图片输入模式的输出宽高比遵循输入图片的比例。
多模态参考(H3 / H3-Lite / H3-Highspeed)
将图片、视频、音频一并指定为参考。音频不能单独输入,必须与图片或视频一起输入。以下限制三个版本通用(格式、编码、帧率据 MiniMax 官方接口补充)。
| 输入 | 限制 |
|---|---|
| 图片 | 最多 9 张。JPG / JPEG / PNG / WEBP / HEIC / HEIF;单个 ≤ 30MB;宽高 [256, 5760];宽高比 0.4~2.5 |
| 视频 | 最多 3 个。MP4 / MOV;视频编码 H.264 / H.265,音频编码 AAC / MP3;单个 ≤ 50MB;单个 2~15 秒,整体 15 秒 以下;宽高 [256, 5760],比例 5:2 ~ 2:5;帧率 23.976~60 |
| 音频 | 最多 3 个。WAV / MP3;单个 ≤ 15MB;单个 2~15 秒,整体 15 秒 以下。必须与图片或视频一起输入 |
| 整体 | 文件合计最多 12 个(VOD 接入指南口径);上游请求体合计 ≤ 64MB,大文件请用 URL |
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/ref1.png",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/ref2.jpg",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/ref3.mp4",
"Usage": "Reference"
}
],
"Prompt": "the figure in image 1 takes the hand of the figure in image 2 and runs out onto the meadow",
"EnhancePrompt": "Enabled",
"OutputConfig": {
"Resolution": "2K",
"AspectRatio": "9:16",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}首 / 尾帧与参考模式
请在首 / 尾帧(FirstFrame / LastFrame)或参考(Reference)中选择其中一种模式。两者互斥:只要出现任一 Reference 素材,就不能再带 FirstFrame / LastFrame,反之亦然。
参考模式的比例:默认 adaptive(按输入自动选比例),也可显式指定 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;H3-Lite 必须显式指定。
视频重新生成(H3_regen)
以已生成的视频为基准重新生成。使用 ModelVersion=H3_regen,并将基准任务 ID 通过 ExtInfo 传递,或直接指定源视频。
| 方式 | 指定方法 |
|---|---|
| 基于任务 ID | 在 ExtInfo.AdditionalParameters.RegenSourceTaskId 中填入此前的任务 ID |
| 基于源视频 | 在 FileInfos 中填入 Category=Video / ReferenceType=base_video |
{
"SubAppId": 123456789,
"ModelName": "Hailuo",
"ModelVersion": "H3_regen",
"Prompt": "she turns her head, opens the window and looks into the distance, then smiles",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "2K"
},
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"RegenSourceTaskId\\\": \\\"<previous-task-id>\\\"}\"}",
"SessionContext": "job-001"
}源视频规格
请按下述规格准备源视频,并用 DescribeTaskDetail 确认处理结果。
| 项目 | 条件 |
|---|---|
| 音轨 | 必填 |
| 分辨率 | 宽与高均为 32 的倍数 |
| 帧数 | 107 + 17 × n(n = 0~15) |
107 + 17 × n 是从 107 / 124 / 141 到 362 的 16 个 值,以 24fps 为准约相当于 4.5 秒 到 15 秒 区间。
源视频的分辨率
请使用 1280x704 / 1920x1088 / 2560x1440 这类宽与高均为 32 倍数的规格。
重新生成仅限 24 小时 以内的任务
RegenSourceTaskId 请指定生成后 24 小时 以内的任务。
输入规格
| 项目 | 限制 |
|---|---|
| 视频文件 | 单个 50MB 以下;MP4 / MOV(H.264 / H.265) |
| 图片文件 | 单个 30MB 以下;JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| 音频文件 | 单个 15MB 以下;WAV / MP3 |
文件大小按单个文件适用。
附加选项
H3 原生多模态
H3 可输入参考图片最多 9 张 / 视频 3 个 / 音频 3 个,或首 / 尾帧各 1 张。支持指定宽高比与同时生成语音。02/2.3 为 6 秒 / 10 秒,H3 为 4~15 秒。
H3-Lite / H3-Highspeed
支持文生、首 / 尾帧(图片 0~2 张)与多模态参考(图片 9 / 视频 3 / 音频 3),时长 4~15 秒,分辨率 480P / 768P,可超分至 2K / 4K。H3-Lite 参考生成须显式指定比例。
MiniMax 官方接口对照
Hailuo 的上游是 MiniMax 视频生成 V2 接口(POST https://api.minimax.io/v2/video_generation)。经 VOD 调用时不需要直接对接它,下表用于对照上游文档排查参数含义。
| MiniMax V2 字段 | 取值 | VOD 对应 |
|---|---|---|
model | MiniMax-H3 / MiniMax-H3-Highspeed / MiniMax-H3-Lite / MiniMax-H3-Max | ModelVersion = H3 / H3-Highspeed / H3-Lite / H3-Max |
content[].type=text | 必填,单条最多 7000 字符 | Prompt |
content[].role=first_frame / last_frame | 图片,各最多 1 张 | FileInfos.N.Usage = FirstFrame / LastFrame |
content[].role=reference_image / reference_video / reference_audio | 图片 ≤ 9 / 视频 ≤ 3 / 音频 ≤ 3 | FileInfos.N.Usage=Reference(Category 区分类型) |
resolution | H3:768P / 2K;其余:480P / 768P | OutputConfig.Resolution(VOD 另提供超分档) |
duration | 4~15(Max:5~15) | OutputConfig.Duration |
ratio | adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | OutputConfig.AspectRatio |
extra.prompt_expansion_mode | 仅 H3-Max:disabled / balanced(默认)/ quality | ⚠️ VOD 接入指南未给出对应字段 |
callback_url | 状态 queued / running / succeeded / failed / cancelled | VOD 走自身的任务查询 / 事件通知 |
比例规则(上游)
| 场景 | ratio 规则 |
|---|---|
| 文生视频 | 必填,不能为 adaptive |
| 首 / 尾帧生视频 | 固定按输入图片(adaptive),传其他值不报错但被忽略 |
| 参考生成 | 可选,默认 adaptive;H3-Lite 暂不支持 adaptive |
上游文档自身的一处不一致
官方接口在「输入组合」里列出了「仅尾帧(last_frame)+ 文本」的生成方式,但 role 字段说明又写 last_frame「必须与 first_frame 配对」。VOD 接入指南支持只传尾帧;如遇报错,请改为首尾帧同传。
上游常见错误(直连 MiniMax 时的 HTTP 状态码,经 VOD 调用时以 VOD 返回的 ErrCode 为准):400 参数错误(如缺少非空 prompt,内部码 2013)、401 鉴权失败(1004)、402 余额不足(1008)、422 输入含敏感内容(1026)、429 限流(1002)、500 服务端错误(1000)。