Hailuo โ
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Hailuo is a video generation model that supports text-to-video and first-frame / first-and-last-frame video generation. H3 supports multimodal reference generation that mixes images, video, and audio (up to 9 images / 3 videos / 3 audio clips, 12 in total), H3-Max targets high-spec generation from text or first and last frames, H3-Lite / H3-Highspeed (launched 2026-11-12) are the lightweight and the quality-and-speed-balanced versions, also supporting text, first / last frame and multimodal reference generation, and H3_regen regenerates an existing video. Output defaults to 768P and can be upscaled to 4K, with durations of 4โ15 seconds.
The H3 family has five ModelVersion values. See Version differences for specs and Calling by version for request examples.
Basic information โ
| Item | Value |
|---|---|
| ModelName | Hailuo |
| ModelVersion | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
| Default | ModelVersion=H3 / Resolution=1080P |
| Disable guardrails support | Only H3 supported |
Version differences โ
| Version | Resolution | Ratio | Length |
|---|---|---|---|
H3 | Default output: 768PUpscaled output: 1080P / 2K / 4K | 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 | 4โ15 seconds |
H3-Max | Default output: 480P / 768PUpscaled output: 1080P / 2K / 4K | 16:9 / 9:16 / 4:3 / 3:4 / 1:1 / adaptive | 5โ15 seconds |
H3-Lite | Default output: 480P / 768PUpscaled output: 2K / 4K | Text: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16Image: follows the input image | 4โ15 seconds |
H3-Highspeed | Default output: 480P / 768PUpscaled output: 2K / 4K | Text: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16Image: follows the input image | 4โ15 seconds |
02 / 2.3 | See per-version output options | โ | 6 seconds10 seconds |
Input conditions โ
| Version | Condition |
|---|---|
H3 | Input: reference images 9 / video 3 / audio 3, 12 combined; separate from first / last frame mode |
H3-Max | Input: text or first / last frame |
H3-Lite / H3-Highspeed | Input: text; or 0~2 first / last frame images (width and height [256, 5760], aspect ratio 0.4~2.5, i.e. 2:5 to 5:2); or reference images 9 / video 3 / audio 3, mutually exclusive with first / last frame mode |
02 / 2.3 | Input: the H3 multimodal limits do not apply |
The
H3-Lite/H3-Highspeedreference limits above come from the official MiniMax V2 API; the VOD integration guide lists the "multimodal reference" capability but gives no counts.
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ModelName | Required | String | Fixed value Hailuo |
ModelVersion | Optional | String | H3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02 |
Prompt | Required | String | Generation prompt |
FileInfos.N | Optional | Array | Reference input. Usage is FirstFrame (first frame) / LastFrame (last frame) / Reference (reference) |
OutputConfig.Resolution | Optional | String | See the per-version specification |
OutputConfig.Duration | Optional | Integer | Video length (seconds) |
OutputConfig.AspectRatio | Optional | String | 16:9 / 9:16 / 1:1, etc. |
OutputConfig.InputComplianceCheck | Optional | String | Passing Disabled explicitly disables input moderation. Contact your sales representative before use |
OutputConfig.OutputComplianceCheck | Optional | String | Passing Disabled explicitly disables output moderation. Contact your sales representative before use |
Request example โ
{
"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"
}Response example โ
{
"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
}
}
]
}
}
}Calling by version โ
All H3 versions share the same request structure โ switching versions only changes ModelVersion. H3 first / last frame and multimodal reference are under "Special settings", H3-Lite / H3-Highspeed are in this section, and H3_regen is under Video regeneration.
| Version | Text | First frame | Last frame | First and last | Multimodal reference | Regeneration |
|---|---|---|---|---|---|---|
H3 | โ | โ | โ | โ | โ | โ |
H3-Max | โ | โ | โ | โ | โ ๏ธ Supported upstream, not listed in the VOD guide | โ |
H3-Lite | โ | โ | โ | โ | โ (example) | โ |
H3-Highspeed | โ | โ | โ | โ | โ | โ |
H3_regen | โ | โ | โ | โ | โ | โ |
H3-Lite โ
Launched 2026-11-12. ModelName=Hailuo, ModelVersion=H3-Lite.
| Item | Spec |
|---|---|
| Generation modes | Text to video; first frame / last frame / first-and-last frame to video; multimodal reference |
| Prompt length | Up to 7000 characters (required, must not be empty) |
| First / last frame images | 0, 1 or 2; width and height [256, 5760]; aspect ratio 0.4~2.5. Without images it runs as text to video |
| Reference assets | Images โค 9 / video โค 3 / audio โค 3; limits under Multimodal reference |
| Aspect ratio | Text: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16, required. Image: follows the input image โ other reasonable values do not raise an error but are ignored and treated as adaptive. Reference: a concrete ratio is required (Lite does not support adaptive yet) |
| Resolution | 480P / 768P; upscaled output 2K / 4K |
| Duration | 4~15 seconds |
Text to video
{
"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"
}First frame to video: one image in FileInfos with 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"
}Last frame to video: pass a single image with Usage=LastFrame; the video ends on that image. Just change Usage in the example above to LastFrame:
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/last.jpg",
"Usage": "LastFrame"
}
]First and last frame to video: declare the two images as FirstFrame and 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"
}The legacy last-frame syntax is still accepted
Declaring the last frame with FileInfos.N.Usage=LastFrame is recommended. The legacy form โ first frame in FileInfos, last frame via LastFrameFileId / LastFrameUrl โ still works but is not recommended for new integrations.
Multimodal reference (H3-Lite) โ
Declare every asset in FileInfos with Usage=Reference and use Category to tell images / video / audio apart. AspectRatio must be a concrete ratio: the official API states that H3-Lite does not yet support adaptive in reference mode (H3 / H3-Highspeed are not affected).
{
"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"
}This example adapts the official MiniMax reference-to-video sample (reference video + reference audio, voice timbre following the audio) to this page's
FileInfossyntax.Category=Audiofollows the generic VODFileInfosstructure; the integration guide has no Lite reference example, so test with a small batch first.
H3-Highspeed โ
Launched 2026-11-12. ModelName=Hailuo, ModelVersion=H3-Highspeed.
Its integration spec is essentially the same as H3-Lite (generation modes, prompt length, first / last frame and reference asset limits, resolution and duration are the same); just set ModelVersion to H3-Highspeed. The one difference: in reference mode H3-Highspeed does support the adaptive ratio, so AspectRatio can be omitted. Officially Highspeed "balances generation quality and speed" while Lite is "the lightweight variant"; pricing follows the AIGC Pricing Guide (Customer), and neither source publishes a generation-time comparison.
Text to video
{
"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"
}First and last frame to video (for first-frame-only or last-frame-only, keep just the corresponding item, same as H3-Lite; for reference generation reuse the H3-Lite reference example with ModelVersion changed)
{
"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 have no 1080P tier
The integration guide lists only 480P / 768P (native) and 2K / 4K (upscaled) โ no 1080P. If you switch from H3 with Resolution=1080P, change it to one of these values. The official MiniMax API also states that these two versions do not support 2K natively, so 2K / 4K on VOD are upscaled output, not native.
Special settings โ
Disable guardrails โ
Hailuo supports disabling guardrails only on ModelVersion=H3. Do not apply the same to other versions.
To use the guardrail-disable parameters, first contact your sales representative to confirm usage permission. Even on supported engines, guardrails are disabled only when the parameter is passed explicitly. If the parameter is omitted, they are not disabled.
| Parameter | Disable value | Applies to |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | Disables input moderation |
OutputConfig.OutputComplianceCheck | Disabled | Disables output moderation |
Merge the following settings into an existing generation request. To disable both input and output moderation, pass both fields together.
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}H3 family comparison โ
| Item | H3 | H3-Max | H3-Lite | H3-Highspeed |
|---|---|---|---|---|
| Text to video | โ | โ | โ | โ |
| First / last / first-and-last frame | โ | โ | โ | โ |
| Multimodal reference (image / video / audio) | โ | โ ๏ธ Supported upstream, not listed in the VOD guide | โ | โ |
| Adaptive ratio in reference mode | โ | โ | โ concrete ratio required | โ |
| Upstream native resolution | 768P / 2K | 480P / 768P | 480P / 768P | 480P / 768P |
| Official positioning | High-quality creation | Fast generation | Lightweight | Balances quality and speed |
| Video length | 4~15 seconds | 5~15 seconds | 4~15 seconds | 4~15 seconds |
| Resolution | 768P / 1080P / 2K / 4K | 768P / 1080P / 2K / 4K | 480P / 768P / 2K / 4K | 480P / 768P / 2K / 4K |
| Prompt length | Up to 7000 characters | Up to 7000 characters | Up to 7000 characters | Up to 7000 characters |
| Disable guardrails | โ | โ | โ | โ |
The multimodal reference row is updated from the official MiniMax V2 API:
H3-Lite/H3-Highspeedshare the same reference asset limits asH3. โ ๏ธ The official API also saysH3-Maxsupports reference generation, but the VOD integration guide lists only "text or first / last frame" for Max โ check with the product team before using Max for reference generation via VOD.
Choosing the reference generation model
Use H3 for quality, H3-Highspeed when speed matters; H3-Lite also works but needs an explicit ratio.
First / last frame (H3) โ
With FileInfos.N.Usage, specify FirstFrame / LastFrame. The image is one of 0, 1, or 2; width and height must be within the [256, 5760] range, and the ratio must be between 5:2 and 2:5. Without an image, it runs as text to video.
{
"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"
}The aspect ratio of image-to-video follows the input image
In image input mode, the output aspect ratio follows the ratio of the input image.
Multimodal reference (H3 / H3-Lite / H3-Highspeed) โ
Specify images, video, and audio together as references. Audio cannot be provided alone; it must be included together with an image or video. The limits below apply to all three versions (formats, codecs and frame rate added from the official MiniMax API).
| Input | Limit |
|---|---|
| Images | Up to 9. JPG / JPEG / PNG / WEBP / HEIC / HEIF; โค 30MB each; width and height [256, 5760]; aspect ratio 0.4~2.5 |
| Video | Up to 3. MP4 / MOV; video codec H.264 / H.265, audio codec AAC / MP3; โค 50MB each; 2~15 seconds each, 15 seconds or less overall; width and height [256, 5760], ratio 5:2 to 2:5; frame rate 23.976~60 |
| Audio | Up to 3. WAV / MP3; โค 15MB each; 2~15 seconds each, 15 seconds or less overall. Must be provided together with an image or video |
| Overall | Up to 12 files combined (VOD guide); upstream request body โค 64MB in total โ use URLs for large files |
{
"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"
}First / last frame and reference modes
Choose one of the modes: first / last frame (FirstFrame / LastFrame) or reference (Reference). They are mutually exclusive: once any Reference asset is present, FirstFrame / LastFrame must not appear, and vice versa.
Ratio in reference mode: defaults to adaptive (chosen automatically from the input); you can also set 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 explicitly. H3-Lite requires an explicit value.
Video regeneration (H3_regen) โ
Regenerates based on an already created video. Use ModelVersion=H3_regen and pass the base task ID via ExtInfo, or specify the source video directly.
| Method | How to specify |
|---|---|
| Task ID based | The previous task ID in ExtInfo.AdditionalParameters.RegenSourceTaskId |
| Source video based | In 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"
}Source video specification โ
Prepare the source video to the specification below and check the processing result with DescribeTaskDetail.
| Item | Condition |
|---|---|
| Audio track | Required |
| Resolution | Width and height both multiples of 32 |
| Frame count | 107 + 17 ร n (n = 0~15) |
107 + 17 ร n runs from 107 / 124 / 141 to 362 as 16 values, and on a 24fps basis corresponds to roughly the 4.5 seconds to 15 seconds range.
Source video resolution
Use a specification such as 1280x704 / 1920x1088 / 2560x1440 where width and height are both multiples of 32.
Regeneration is possible only for tasks within 24 hours
RegenSourceTaskId specifies a task created within 24 hours.
Input specification โ
| Item | Limit |
|---|---|
| Video file | 50MB or less each; MP4 / MOV (H.264 / H.265) |
| Image file | 30MB or less each; JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| Audio file | 15MB or less each; WAV / MP3 |
File size applies per individual file.
Additional options โ
H3 native multimodal
H3 takes up to 9 reference images / 3 video / 3 audio, or 1 each for the first and last frames. It supports specifying the aspect ratio and generating audio at the same time. 02/2.3 are 6 seconds / 10 seconds, and H3 is 4~15 seconds.
H3-Lite / H3-Highspeed
Supports text, first / last frame (0~2 images) and multimodal reference (images 9 / video 3 / audio 3), 4~15 seconds, 480P / 768P, upscalable to 2K / 4K. H3-Lite needs an explicit ratio for reference generation.
Official MiniMax API mapping โ
Hailuo is backed upstream by the MiniMax Video Generation V2 API (POST https://api.minimax.io/v2/video_generation). You do not need to integrate it directly when calling through VOD โ use this table to map parameters when reading the upstream docs.
| MiniMax V2 field | Values | VOD equivalent |
|---|---|---|
model | MiniMax-H3 / MiniMax-H3-Highspeed / MiniMax-H3-Lite / MiniMax-H3-Max | ModelVersion = H3 / H3-Highspeed / H3-Lite / H3-Max |
content[].type=text | Required, up to 7000 characters per item | Prompt |
content[].role=first_frame / last_frame | Images, at most 1 each | FileInfos.N.Usage = FirstFrame / LastFrame |
content[].role=reference_image / reference_video / reference_audio | Images โค 9 / video โค 3 / audio โค 3 | FileInfos.N.Usage=Reference (Category sets the type) |
resolution | H3: 768P / 2K; others: 480P / 768P | OutputConfig.Resolution (VOD adds upscaled tiers) |
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 only: disabled / balanced (default) / quality | โ ๏ธ No equivalent field in the VOD integration guide |
callback_url | Status queued / running / succeeded / failed / cancelled | VOD uses its own task query / event notification |
Ratio rules (upstream)
| Scenario | ratio rule |
|---|---|
| Text to video | Required; cannot be adaptive |
| First / last frame to video | Always follows the input image (adaptive); other values are ignored without error |
| Reference | Optional, defaults to adaptive; H3-Lite does not support adaptive yet |
An inconsistency in the upstream docs
The official API lists "last frame (last_frame) + text only" as an input combination, yet the role description says last_frame "must be paired with first_frame". The VOD integration guide supports last-frame-only; if you hit an error, send both first and last frames.
Common upstream errors (HTTP status when calling MiniMax directly; through VOD, rely on the ErrCode VOD returns): 400 invalid parameters (e.g. missing non-empty prompt, internal code 2013), 401 authentication failed (1004), 402 insufficient balance (1008), 422 sensitive input (1026), 429 rate limited (1002), 500 server error (1000).