MiniMax H3 API

ReachAPI exposes MiniMax Hailuo-03 through the public model ID minimax-h3 and the unified asynchronous video task API.

Create task: POST /v1/vids/create
Query task: GET /v1/tasks/{task_id}
Execution: asynchronous; poll the task endpoint or provide callback_url
Model ID: minimax-h3

Authentication

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

Capabilities and pricing

Duration	Resolution	Aspect ratio	Input modes
Integer from `4` to `15` seconds	`2K`, `768P`	`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`	Text, first frame, first/last frames, multimodal reference

input.content is required and must include at least one non-empty text item. Legacy fields such as prompt, image_url, and image_urls are not converted into content automatically.

Meter	2K	768P
Output video	$0.13 / second	$0.08 / second
Reference video input	$0.13 / second	$0.08 / second
Input images	First 5 free; $0.04 each from the 6th	First 5 free; $0.04 each from the 6th
Input audio	Free	Free

Successful tasks are settled from actual usage. Reference video input uses the requested output-resolution rate.

Create a task

{
  "model": "minimax-h3",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A paper boat drifts through a rainy street at night"
      }
    ],
    "duration_seconds": 6,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}

Top-level parameters

Field	Type	Required	Description
`model`	string	Yes	Must be `minimax-h3`
`callback_url`	string	No	HTTPS URL for terminal task states; maximum 2048 characters; private-network targets are rejected
`input`	object	Yes	Video generation parameters

`input` parameters

Field	Type	Required	Description
`content`	array of object	Yes	Non-empty explicit input with at least one non-empty text item
`resolution`	string	Yes	`2K` or `768P`
`duration_seconds`	integer	Yes	Integer from `4` through `15`
`aspect_ratio`	string	Conditional	Required for text-only requests; see below

Bitrate, frame rate, video codec, and audio codec are selected by the platform and cannot be configured. The complete request body must not exceed 64 MB.

Aspect-ratio rules

Input mode	Rule
Text only	Required and cannot be `adaptive`; use one of the six fixed ratios
First frame or first and last frames	The output always follows the input image aspect ratio; any supplied `aspect_ratio` value is ignored
Multimodal reference	Optional; a fixed ratio takes effect, while omission or `adaptive` follows the reference material

`input.content`

Type	Role	Limit	Description
`text`	None	—	At least one non-empty text item; each text item is limited to 7000 characters
`image_url`	`first_frame`	1	Starting frame; a single role-less image is treated as the first frame
`image_url`	`last_frame`	1	Ending frame
`image_url`	`reference_image`	9	Subject or style reference
`video_url`	`reference_video`	3	Motion or camera reference
`audio_url`	`reference_audio`	3	Audio reference

URL fields are nested as image_url.url, video_url.url, or audio_url.url. Video items must use reference_video; audio items must use reference_audio.

First/last-frame inputs cannot be mixed with reference_image, reference_video, or reference_audio in the same request.

Supported modes:

Text to video: text
First-frame image to video: text + first_frame
First and last frames: text + first_frame + last_frame
Multimodal reference: text + one or more reference_* items

For multiple assets, refer to them in array order as Image 1, Image 2, Video 1, and Audio 1. Do not use Seedance-style @ references.

Input media requirements

Input	Formats	Size	Other constraints
Image	JPG, JPEG, PNG, WEBP, HEIC, HEIF	Up to 30 MB each	256–5760 px per side; aspect ratio 0.4–2.5
Reference video	MP4, MOV	Up to 50 MB each	Width and height 256–5760 px; aspect ratio 0.4–2.5; H.264/H.265; AAC/MP3; 2–15 s each; 15 s total; 23.976–60 fps
Reference audio	WAV, MP3	Up to 15 MB each	2–15 s each; 15 s total

Media URLs must be fetchable by the upstream service. Base64, data: URIs, and mm_file:// handles are not supported.

Request examples

First-frame image

{
  "model": "minimax-h3",
  "input": {
    "content": [
      { "type": "text", "text": "The camera slowly pulls back" },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

First and last frames

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A smooth transition from close-up to wide shot"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://cdn.example.com/end.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "768P",
    "aspect_ratio": "adaptive"
  }
}

Multimodal reference

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "Replace the person in Video 1 with Image 1 and synchronize the action to Audio 1"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://cdn.example.com/person.png" }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "https://cdn.example.com/motion.mp4" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://cdn.example.com/beat.mp3" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

Responses and polling

Submission response:

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

Poll GET /v1/tasks/task_xxx until status is success or failed.

{
  "code": 200,
  "status": "success",
  "task_id": "task_xxx",
  "data": [{ "url": "https://cdn.example.com/generated/video-1.mp4" }],
  "cost": { "spend": 0.52 },
  "billing": [
    {
      "metric": "VIDEO_SECONDS",
      "quantity": 4,
      "unit": 1,
      "price": 130000,
      "amount": 520000,
      "conditions": { "resolution": "2K" }
    }
  ]
}

cost.spend is shown in USD; billing contains credit-meter details. Store result files promptly because result URLs may expire. A 5-second 2K text-to-video task typically takes about three minutes; configure polling accordingly.

Errors

Code	Meaning
400	Missing/invalid fields, conflicting modes, or media limits exceeded
401	Invalid API key
402	Insufficient credits
422	Content-safety rejection
429	Rate limited; retry with backoff
500 / 502	Model or upstream service temporarily unavailable

A failed task includes status: "failed", an error_code, and cost.spend: 0 when no charge was made.

MiniMax H3 API

On this page