Skip to content

Hailuo โ€‹

Updated

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 โ€‹

ItemValue
ModelNameHailuo
ModelVersionH3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02
DefaultModelVersion=H3 / Resolution=1080P
Disable guardrails supportOnly H3 supported

Version differences โ€‹

VersionResolutionRatioLength
H3Default output: 768P
Upscaled output: 1080P / 2K / 4K
21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:164โ€“15 seconds
H3-MaxDefault output: 480P / 768P
Upscaled output: 1080P / 2K / 4K
16:9 / 9:16 / 4:3 / 3:4 / 1:1 / adaptive5โ€“15 seconds
H3-LiteDefault output: 480P / 768P
Upscaled output: 2K / 4K
Text: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
Image: follows the input image
4โ€“15 seconds
H3-HighspeedDefault output: 480P / 768P
Upscaled output: 2K / 4K
Text: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
Image: follows the input image
4โ€“15 seconds
02 / 2.3See per-version output optionsโ€”6 seconds
10 seconds

Input conditions โ€‹

VersionCondition
H3Input: reference images 9 / video 3 / audio 3, 12 combined; separate from first / last frame mode
H3-MaxInput: text or first / last frame
H3-Lite / H3-HighspeedInput: 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.3Input: the H3 multimodal limits do not apply

The H3-Lite / H3-Highspeed reference limits above come from the official MiniMax V2 API; the VOD integration guide lists the "multimodal reference" capability but gives no counts.

Request parameters โ€‹

ParameterRequiredTypeDescription
ModelNameRequiredStringFixed value Hailuo
ModelVersionOptionalStringH3 / H3-Max / H3-Lite / H3-Highspeed / H3_regen / 2.3 / 2.3-fast / 02
PromptRequiredStringGeneration prompt
FileInfos.NOptionalArrayReference input. Usage is FirstFrame (first frame) / LastFrame (last frame) / Reference (reference)
OutputConfig.ResolutionOptionalStringSee the per-version specification
OutputConfig.DurationOptionalIntegerVideo length (seconds)
OutputConfig.AspectRatioOptionalString16:9 / 9:16 / 1:1, etc.
OutputConfig.
InputComplianceCheck
OptionalStringPassing Disabled explicitly disables input moderation. Contact your sales representative before use
OutputConfig.
OutputComplianceCheck
OptionalStringPassing Disabled explicitly disables output moderation. Contact your sales representative before use

Request example โ€‹

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

Response example โ€‹

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

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.

VersionTextFirst frameLast frameFirst and lastMultimodal referenceRegeneration
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.

ItemSpec
Generation modesText to video; first frame / last frame / first-and-last frame to video; multimodal reference
Prompt lengthUp to 7000 characters (required, must not be empty)
First / last frame images0, 1 or 2; width and height [256, 5760]; aspect ratio 0.4~2.5. Without images it runs as text to video
Reference assetsImages โ‰ค 9 / video โ‰ค 3 / audio โ‰ค 3; limits under Multimodal reference
Aspect ratioText: 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)
Resolution480P / 768P; upscaled output 2K / 4K
Duration4~15 seconds

Text to video

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

First frame to video: one image in FileInfos with 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"
}

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:

json
"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.

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

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).

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

This example adapts the official MiniMax reference-to-video sample (reference video + reference audio, voice timbre following the audio) to this page's FileInfos syntax. Category=Audio follows the generic VOD FileInfos structure; 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

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

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)

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 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.

ParameterDisable valueApplies to
OutputConfig.InputComplianceCheckDisabledDisables input moderation
OutputConfig.OutputComplianceCheckDisabledDisables output moderation

Merge the following settings into an existing generation request. To disable both input and output moderation, pass both fields together.

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

H3 family comparison โ€‹

ItemH3H3-MaxH3-LiteH3-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 resolution768P / 2K480P / 768P480P / 768P480P / 768P
Official positioningHigh-quality creationFast generationLightweightBalances quality and speed
Video length4~15 seconds5~15 seconds4~15 seconds4~15 seconds
Resolution768P / 1080P / 2K / 4K768P / 1080P / 2K / 4K480P / 768P / 2K / 4K480P / 768P / 2K / 4K
Prompt lengthUp to 7000 charactersUp to 7000 charactersUp to 7000 charactersUp to 7000 characters
Disable guardrailsโœ…โ€”โ€”โ€”

The multimodal reference row is updated from the official MiniMax V2 API: H3-Lite / H3-Highspeed share the same reference asset limits as H3. โš ๏ธ The official API also says H3-Max supports 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.

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

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).

InputLimit
ImagesUp to 9. JPG / JPEG / PNG / WEBP / HEIC / HEIF; โ‰ค 30MB each; width and height [256, 5760]; aspect ratio 0.4~2.5
VideoUp 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
AudioUp to 3. WAV / MP3; โ‰ค 15MB each; 2~15 seconds each, 15 seconds or less overall. Must be provided together with an image or video
OverallUp to 12 files combined (VOD guide); upstream request body โ‰ค 64MB in total โ€” use URLs for large files
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"
}

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.

MethodHow to specify
Task ID basedThe previous task ID in ExtInfo.AdditionalParameters.RegenSourceTaskId
Source video basedIn 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"
}

Source video specification โ€‹

Prepare the source video to the specification below and check the processing result with DescribeTaskDetail.

ItemCondition
Audio trackRequired
ResolutionWidth and height both multiples of 32
Frame count107 + 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 โ€‹

ItemLimit
Video file50MB or less each; MP4 / MOV (H.264 / H.265)
Image file30MB or less each; JPG / JPEG / PNG / WEBP / HEIC / HEIF
Audio file15MB 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 fieldValuesVOD equivalent
modelMiniMax-H3 / MiniMax-H3-Highspeed / MiniMax-H3-Lite / MiniMax-H3-MaxModelVersion = H3 / H3-Highspeed / H3-Lite / H3-Max
content[].type=textRequired, up to 7000 characters per itemPrompt
content[].role=first_frame / last_frameImages, at most 1 eachFileInfos.N.Usage = FirstFrame / LastFrame
content[].role=reference_image / reference_video / reference_audioImages โ‰ค 9 / video โ‰ค 3 / audio โ‰ค 3FileInfos.N.Usage=Reference (Category sets the type)
resolutionH3: 768P / 2K; others: 480P / 768POutputConfig.Resolution (VOD adds upscaled tiers)
duration4~15 (Max: 5~15)OutputConfig.Duration
ratioadaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16OutputConfig.AspectRatio
extra.prompt_expansion_modeH3-Max only: disabled / balanced (default) / qualityโš ๏ธ No equivalent field in the VOD integration guide
callback_urlStatus queued / running / succeeded / failed / cancelledVOD uses its own task query / event notification

Ratio rules (upstream)

Scenarioratio rule
Text to videoRequired; cannot be adaptive
First / last frame to videoAlways follows the input image (adaptive); other values are ignored without error
ReferenceOptional, 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).

Built with VitePress ยท Deployed on Tencent EdgeOne Pages