Get API Key Get API
Docs

MiniMax-H3 Video Generation

- Async processing mode, returns a task ID for subsequent queries

  • Supports text-to-video, image-to-video (first / last / first+last frame), and multimodal reference-to-video (reference images + videos + audio)
  • Supports 2K / 768P resolution, duration 4 ~ 15 seconds, with audio track
  • Shares the same submit and query APIs as MiniMax-Hailuo-02 / MiniMax-Hailuo-2.3

Request example

curl --request POST \
  --url https://api.openveer.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'

Response example

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

Authorization

Authorization string

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add to the request header:

Authorization: Bearer YOUR_API_KEY

Generation Modes

MiniMax-H3 routes to the matching mode from request fields automatically. You do not need a mode field:

Mode Trigger Capability
Text-to-Video (T2V) Only prompt and common fields Pure text-driven generation
Image-to-Video (I2V) first_frame_image / last_frame_image (or first_frame / last_frame in image_with_roles) First frame, last frame, first+last frame control
Multimodal Reference (R2V) image_urls / video_urls / audio_urls, or reference_image in image_with_roles Reference images + videos + audio
Warning

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.

Warning

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

model string

Fixed value: MiniMax-H3

Warning



model is required and must be sent explicitly. Clients already integrated with Hailuo can switch by setting model to MiniMax-H3.

nsfw_check boolean

Whether to run content moderation before submitting the video task.

  • true: use omni-moderation-latest to review prompts and input images
  • false or omitted: do not send a moderation request, adding no moderation cost or latency (default)
prompt string

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"

duration integer

Output duration (seconds)

  • Range: integer from 4 to 15
  • Default: 5
resolution string

Video resolution

Options:

  • 2K (default)
  • 768P
aspect_ratio 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:16

Behavior by scenario is described in “Aspect Ratio Rules” below.

watermark boolean

Whether to add an AIGC watermark

Default: false

Compatible alias: aigc_watermark

webhook string

URL that receives a push when the task reaches a terminal state (success / failure)

Note



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.

first_frame_image string

First-frame image URL

When provided, this image is used as the starting frame of the video.

last_frame_image string

Last-frame image URL

When provided, this image is used as the ending frame. Combine with first_frame_image for first+last frame control.

Multimodal Reference Fields

image_urls string[]

Array of reference image URLs

Warning



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
video_urls string[]

Array of reference video URLs

  • Count: ≤ 3
  • Format and limits: see “Input Media Limits” below
audio_urls 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)

image_with_roles object[]
Role-tagged image array. Can replace first_frame_image / last_frame_image / image_urls. Each element:
url string

Image URL

role string

Image role. Allowed values:

  * first_frame (also accepts first) — first frame (I2V)
  * last_frame (also accepts last) — last frame (I2V)
  * reference_image (also accepts reference) — reference image (R2V)
Example (first + last frame):
{
  "image_with_roles": [
    {"url": "https://example.com/start.png", "role": "first_frame"},
    {"url": "https://example.com/end.png", "role": "last_frame"}
  ]
}
Example (reference image):
{
  "image_with_roles": [
    {"url": "https://example.com/char.png", "role": "reference_image"}
  ]
}

Aspect Ratio Rules

Scenario aspect_ratio behavior
Text-to-video (prompt only) Must be a concrete ratio; omit or adaptive falls back to 16:9
Image-to-video (first / last frame) Determined by input image; any value is ignored (always adaptive)
Multimodal reference Optional, default adaptive; may also set an explicit ratio

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

Item Limit
Format JPG / JPEG / PNG / WEBP / HEIC / HEIF
Per file ≤ 30 MB
Width / height 256 \~ 5760 px
Aspect ratio (w/h) 0.4 \~ 2.5
Count First frame ≤ 1, last frame ≤ 1, reference images ≤ 9

Video (multimodal reference only)

Item Limit
Format MP4 (.mp4), MOV (.mov)
Codec Video H.264/AVC, H.265/HEVC; audio AAC, MP3
Per file ≤ 50 MB
Count ≤ 3
Duration Per clip 2 \~ 15 s; total duration ≤ 15 s
Size / ratio / FPS 256 \~ 5760 px / 0.4 \~ 2.5 / 23.976 \~ 60

Audio (multimodal reference only)

Item Limit
Format WAV, MP3
Per file ≤ 15 MB
Count ≤ 3
Duration Per clip 2 \~ 15 s; total duration ≤ 15 s

Parameter Constraints

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

Parameter Constraint
prompt Required and non-empty in every scenario, ≤ 7000 characters
duration Integer from 4 to 15 only
resolution 2K (default) or 768P
aspect_ratio See “Aspect Ratio Rules”; T2V falls back to 16:9 when omitted
First/last frame vs reference assets Mutually exclusive, cannot be mixed
audio_urls Cannot be used alone; must pair with reference image or video
Reference images ≤ 9
Reference videos ≤ 3
Reference audio ≤ 3
Reference video probe failure Returns input_video_probe_failed (URL unreachable or corrupt file), not charged

Response

code integer

Response status code, 200 on success

data array
Response data array
status string

Task status; submitted on initial submit

task_id string

Unique task ID for querying status and results

Request Examples

Case 1: Text-to-Video

{
  "model": "MiniMax-H3",
  "prompt": "A boy playing basketball by the sea at dusk, waves crashing, cinematic camera work",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

Case 2: Image-to-Video — First Frame

{
  "model": "MiniMax-H3",
  "prompt": "Pull focus to the people in the background and add more steam to the ramen bowl.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "2K"
}

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

{
  "model": "MiniMax-H3",
  "prompt": "Camera slowly transitions from morning light to sunset",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8
}

Case 4: Multimodal Reference-to-Video

{
  "model": "MiniMax-H3",
  "prompt": "Character speaks: Follow the wind, live free. Leave worries behind, enjoy the moment. Voice references audio 1",
  "image_with_roles": [
    {"url": "https://cdn.example.com/char.png", "role": "reference_image"}
  ],
  "video_urls": ["https://cdn.example.com/ref_motion.mp4"],
  "audio_urls": ["https://cdn.example.com/ref_voice.mp3"],
  "duration": 5,
  "resolution": "2K"
}

Case 5: First + Last Frame via image_with_roles

{
  "model": "MiniMax-H3",
  "prompt": "Camera slowly transitions from morning light to sunset",
  "image_with_roles": [
    {"url": "https://cdn.example.com/morning.png", "role": "first_frame"},
    {"url": "https://cdn.example.com/sunset.png", "role": "last_frame"}
  ],
  "duration": 8
}
Note

Query Task Results

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

This documentation is built and hosted on Mintlify, a developer documentation platform.