Skip to main content
POST

Authorization

string
required
All API endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd to the request header:

Generation Modes

MiniMax-H3 routes to the matching mode from request fields automatically. You do not need a mode field:
Strict mutual exclusion: Image-to-video fields (first_frame_image / last_frame_image, and first_frame / last_frame in image_with_roles) cannot be combined with multimodal reference fields (image_urls, video_urls, audio_urls, and reference_image in image_with_roles). Mixing them returns 400.
Audio alone is not allowed. If you pass audio_urls, you must also provide at least one reference image or reference video.

Request Parameters

Common Fields

string
required
Fixed value: MiniMax-H3
model is required and must be sent explicitly. Clients already integrated with Hailuo can switch by setting model to MiniMax-H3.
string
required
Video content description. Required and non-empty in every scenario, max 7000 characters per request.Describe scene, subject, motion, and style in detail for better results.Example: "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work"
integer
default:"5"
Output duration (seconds)
  • Range: integer from 4 to 15
  • Default: 5
string
default:"2K"
Video resolution
  • Supported value: 2K only (default)
string
Aspect ratio. You may also pass size or ratio with the same effect.Allowed ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16Behavior by scenario is described in “Aspect Ratio Rules” below.
boolean
default:"false"
Whether to add an AIGC watermarkDefault: falseCompatible alias: aigc_watermark
string
URL that receives a push when the task reaches a terminal state (success / failure)
Use webhook. Do not pass the official callback_url. callback_url is reserved for internal use and is not accepted from users.

Image-to-Video Fields

For first / last frame image-to-video, specify roles explicitly. Do not infer from image_urls count.
string
First-frame image URLWhen provided, this image is used as the starting frame of the video.
string
Last-frame image URLWhen provided, this image is used as the ending frame. Combine with first_frame_image for first+last frame control.

Multimodal Reference Fields

string[]
Array of reference image URLs
Every image in image_urls is treated as a reference image (reference_image), regardless of count. They are never auto-mapped to first / first+last frames by length.
  • Count: ≤ 9
string[]
Array of reference video URLs
  • Count: ≤ 3
  • Format and limits: see “Input Media Limits” below
string[]
Array of reference audio URLs
  • Count: ≤ 3
  • Cannot be used alone; must be paired with a reference image or reference video

Shared Image Array (Optional Form)

object[]
Role-tagged image array. Can replace first_frame_image / last_frame_image / image_urls. Each element:Example (first + last frame):
Example (reference image):

Aspect Ratio Rules

Allowed concrete ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.

Input Media Limits

Total request body size ≤ 64 MB. Use public URLs for large files; do not use Base64.

Images

Video (multimodal reference only)

Audio (multimodal reference only)

Parameter Constraints

Violations are rejected with 400 (sensitive content may return 422) and are not billed:

Response

integer
Response status code, 200 on success
array
Response data array

Request Examples

Case 1: Text-to-Video

Case 2: Image-to-Video — First Frame

Case 3: Image-to-Video — First + Last Frame

Case 4: Multimodal Reference-to-Video

Case 5: First + Last Frame via image_with_roles

Query Task ResultsVideo generation is asynchronous and returns a task_id on submit. Use the Get Task Status endpoint to poll progress and results.Recommended poll interval: every 5 ~ 10 seconds. Client timeout: 15 minutes. On success, result.videos[0].url is the mp4 URL. Video URLs expire in about 24 hours — save them promptly. Failed tasks are automatically refunded.