跳到内容

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,规格差异见版本差异,各版本的调用写法见按版本调用。

基本信息 ​

项目值
ModelNameHailuo
ModelVersionH3 / 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:164–15 秒
H3-Max默认输出:480P / 768P
超分输出:1080P / 2K / 4K
16:9 / 9:16 / 4:3 / 3:4 / 1:1 / adaptive5–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可选StringH3 / 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可选String16:9 / 9:16 / 1:1 等
OutputConfig.
InputComplianceCheck
可选String显式传递 Disabled 则解除输入审核。使用前请咨询商务负责人
OutputConfig.
OutputComplianceCheck
可选String显式传递 Disabled 则解除输出审核。使用前请咨询商务负责人

请求示例 ​

json
{
  "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"
}

响应示例 ​

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
          }
        }
      ]
    }
  }
}

按版本调用 ​

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 秒

文生视频

json
{
  "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。

json
{
  "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 即可:

json
"FileInfos": [
  {
    "Type": "Url",
    "Category": "Image",
    "Url": "https://<cos>/last.jpg",
    "Usage": "LastFrame"
  }
]

首尾帧生视频:两张图分别声明 FirstFrame 与 LastFrame。

json
{
  "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 不受此限)。

json
{
  "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 价格指南(客户)》为准,两者都没有公开生成耗时对比。

文生视频

json
{
  "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)

json
{
  "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.InputComplianceCheckDisabled解除输入审核
OutputConfig.OutputComplianceCheckDisabled解除输出审核

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

json
{
  "OutputConfig": {
    "InputComplianceCheck": "Disabled",
    "OutputComplianceCheck": "Disabled"
  }
}

H3 系列版本对比 ​

项目H3H3-MaxH3-LiteH3-Highspeed
文本生成视频✅✅✅✅
首帧 / 尾帧 / 首尾帧✅✅✅✅
多模态参考(图片 / 视频 / 音频)✅⚠️ 上游支持,VOD 指南未列✅✅
参考生成可用 adaptive 比例✅—❌ 须指定比例✅
上游原生分辨率768P / 2K480P / 768P480P / 768P480P / 768P
官方定位高质量创作快速生成轻量版兼顾质量与速度
视频时长4~15 秒5~15 秒4~15 秒4~15 秒
分辨率768P / 1080P / 2K / 4K768P / 1080P / 2K / 4K480P / 768P / 2K / 4K480P / 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 之间。若无图片则按文本生成视频运行。

json
{
  "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
json
{
  "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
json
{
  "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 对应
modelMiniMax-H3 / MiniMax-H3-Highspeed / MiniMax-H3-Lite / MiniMax-H3-MaxModelVersion = 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 / 音频 ≤ 3FileInfos.N.Usage=Reference(Category 区分类型)
resolutionH3:768P / 2K;其余:480P / 768POutputConfig.Resolution(VOD 另提供超分档)
duration4~15(Max:5~15)OutputConfig.Duration
ratioadaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16OutputConfig.AspectRatio
extra.prompt_expansion_mode仅 H3-Max:disabled / balanced(默认)/ quality⚠️ VOD 接入指南未给出对应字段
callback_url状态 queued / running / succeeded / failed / cancelledVOD 走自身的任务查询 / 事件通知

比例规则(上游)

场景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)。

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