MiniMax H3 APIMiniMax-H3 · Video generation API · minimaxh3.video

MiniMax H3 API for production video generation

Build text-to-video, first/last-frame control, and omni-reference workflows on the MiniMax H3 API. One asynchronous contract returns a task ID, then a downloadable content URL.

Open the generator Read the prompt guide

POST /api/v1/video_generation200 · task_id

curl --request POST \
  --url https://minimaxh3.video/api/v1/video_generation \
  --header "Authorization: Bearer $MINIMAX_H3_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cyclist crosses a rain-lit city street at night, neon reflections on wet asphalt, camera tracking beside the bicycle."
      }
    ],
    "duration": 5,
    "resolution": "2K",
    "ratio": "16:9"
  }'

Endpoint: POST /api/v1/video_generation

Model ID: MiniMax-H3

Workflow: Asynchronous task

Output: 2K · 4–15s

Auth: Bearer API key

Prompt limit: 7,000 characters

Public contract

One MiniMax H3 endpoint, three creative modes.

MiniMax-H3 uses a multimodal content array. The roles you attach decide whether the request is text-to-video, first/last-frame image-to-video, or reference-to-video.

01content: text

Text to video (t2va)

Send a required text item and invent the full shot. For pure text generation, ratio is required and cannot be adaptive.

02content: text + images

First / last frame (i2va)

Add image_url items with role first_frame and optional last_frame to control the opening and ending composition.

03content: text + refs

Reference generation (r2va)

Guide character, motion, camera, style, or voice with reference images, videos, and audio—without mixing first/last-frame roles.

What the API exposes

Control the scene, references, and output contract.

MiniMax H3 is documented as an open, general-purpose multimodal video model. The V2 surface is built for product backends, not one-off playgrounds.

Multimodal input

Text, image, video, and audio in one request

Each content element is typed and can carry a role. Audio references must travel with image or video input.

Output window

Native 2K for 4–15 seconds

Duration accepts integer seconds from 4 to 15. Common aspect ratios are supported; adaptive is allowed when media defines geometry.

Prompt budget

Up to 7,000 characters of direction

Use the budget for shot structure, motion, camera path, dialogue intent, and reference mapping—not keyword spam.

Role safety

First/last frame and references are mutually exclusive

If any reference_* role appears, first_frame and last_frame must not. Designing validation around that rule prevents avoidable 400s.

Async result

task_id → status → content.url

Successful tasks return a time-limited download URL directly on the query response. Persist identifiers and store the file if durability matters.

Task hygiene

List, cancel, and expire windows

V2 documents list, cancel/delete, and a short query window for recent tasks—treat generation as a managed job, not a single long HTTP call.

Product fit

What teams build with the MiniMax H3 API

Use the same async workflow for single creative assets, creator tools, or batch pipelines.

Creator products

In-app shot generation

Let users submit a prompt or first frame, show queue state, and deliver a 2K clip when the task succeeds.

Brand systems

Reference-guided campaigns

Carry character, product, motion, or voice references across short shots without rebuilding identity every time.

Editorial tools

First-to-last transitions

Direct a controlled opening and ending frame when storyboard continuity matters more than pure improvisation.

Social pipelines

Vertical and cinematic ratios

Generate 9:16 hooks or 16:9 master shots from one integration surface and branch only on ratio and duration.

Agent backends

Queued multimodal jobs

Agents can assemble content arrays, poll status, and hand content.url to storage, moderation, or edit steps.

Prototype studios

Fast direction tests

Explore camera, performance, and reference combinations before committing to a full production pipeline.

Asynchronous workflow

From API key to a downloadable MiniMax H3 video

Generation never needs to keep one HTTP request open. Store identifiers and move through the documented V2 steps.

Create

Submit a generation task

POST model MiniMax-H3, a content array, duration, resolution, and ratio when required. A successful response returns task_id.

POST /api/v1/video_generation

Observe

Poll task status

Query the task until it reaches a terminal state. Treat queued and running as healthy intermediate states.

GET /api/v1/video_generation/{task_id}

Retrieve

Download content.url

On succeeded, the response includes content.url. The URL is time-limited—copy the file into storage you control if it must remain durable.

content.url · mp4

Request design

The fields that shape a dependable MiniMax-H3 request

Keep the public request explicit and validate mode-specific combinations before a task is submitted.

Required

model

Use the exact documented identifier MiniMax-H3. Do not invent product nicknames as model IDs.

Required multimodal body

content[]

At least one type=text item. Add image_url, video_url, or audio_url items with roles for controlled modes.

4–15 integer seconds

duration

Pick a single integer window. Longer is not always better if the shot only needs one clear action.

Documented output

resolution

MiniMax H3 is documented for 2K output. Confirm current enum values against the live API reference before shipping.

Geometry control

ratio

Required for pure text-to-video and must not be adaptive in that mode. Image-led workflows can follow source geometry.

Optional media roles

first_frame · last_frame · reference_*

Roles change the creative contract. Validate mutual exclusion and per-asset size limits at upload time.

Task state

Treat status as a state machine

Polling clients should tolerate intermediate states and stop only on documented terminal outcomes.

Status	Meaning	Recommended application behavior
queued	Waiting for capacity	Persist task_id and back off between polls
running	Generation is in progress	Keep the job visible; avoid duplicate submits
succeeded	Video is ready	Read content.url and store the asset
failed	Generation did not complete	Surface error code/message and allow deliberate retry
cancelled	Task was cancelled	Close the job UI and keep an audit trail
expired	Task is no longer available	Do not poll forever; re-create if needed

Only recent tasks remain queryable. Confirm the official retention window before designing long-lived recovery flows.

Input boundaries

Validate media before it reaches MiniMax H3

The documented limits are simple enough to enforce at upload time, preventing avoidable task failures.

Images

JPG, JPEG, PNG, WEBP, HEIC, HEIF · ≤ 30 MB

Width/height in [256, 5760]; aspect ratio between 2:5 and 5:2. First frame ≤ 1, last frame ≤ 1, reference images ≤ 9.

Videos

MP4/MOV with H.264/H.265 · ≤ 50 MB each

Up to 3 reference clips, each 2–15s, total ≤ 15s. In-video audio may be AAC or MP3.

Audio

WAV or MP3 · ≤ 15 MB each

Up to 3 clips, each 2–15s, total ≤ 15s. Audio cannot be sent alone—pair it with image or video references.

Mixed refs

At most 12 media files in one request

Request body should stay ≤ 64 MB. Prefer public URLs for large assets instead of Base64.

Mode exclusion

Do not mix first/last frames with reference roles

Choose either composition control (first/last) or omni reference generation—not both in one content array.

Prompt

Keep direction under 7,000 characters

Map references in the text when identity, voice, or motion must follow a specific asset.

Pricing stays on the pricing page

Credit rates and plan limits can change. Link to the live MiniMax H3 pricing page instead of hard-coding a number into your integration.

Design fit

A good fit for asynchronous MiniMax H3 generation

Choose the V2 API when your product can create a job and wait for a generated asset.

Good fit

Backend services and creator tools

Queued generation, durable storage, and status UIs map cleanly to task_id workflows.

Good fit

Multimodal creative control

Shots that combine prompt direction with first frames, last frames, or reference media.

Boundary

Not a real-time streaming video socket

Design for polling or internal job workers rather than keeping a live generation connection open.

Boundary

Design for jobs, not open sockets

Keep long-running generation in your backend queue and surface status in the product UI.

API questions

MiniMax H3 API questions

Practical answers before you wire the first production request.

Is MiniMax-H3 the model ID for this API?

Yes. Send model MiniMax-H3 on the MiniMax H3 video generation endpoint when creating a task.

Which endpoint should I call?

Create tasks with POST https://minimaxh3.video/api/v1/video_generation, then query GET https://minimaxh3.video/api/v1/video_generation/{task_id}. On success, download the mp4 from content.url.

How is MiniMax H3 different from Hailuo 2.3 integration?

H3 is the current general-purpose multimodal model with a content[] contract, documented 2K output, 4–15s duration, and omni references. Hailuo 2.3 remains an earlier model family with different request patterns.

Can I combine first-frame control with reference audio?

Not in the same request. First/last-frame roles and reference_* roles are mutually exclusive. Choose the mode that matches the control you need.

How do I authenticate?

Send a Bearer API key in the Authorization header. Create and manage keys from your MiniMax H3 account settings after you have access.

Where should I confirm current prices?

Use the site pricing page for product plans and credits. API usage follows the same credit wallet rules published there.

Ready to integrate MiniMax H3

Prototype the shot. Ship the API request.

Shape creative direction in the generator, then call the MiniMax H3 API on minimaxh3.video with your key.

Open the generator Read the prompt guide