MiniMax H3 Video Generation

Call MiniMax H3 (MiniMax-H3) video generation through EasyRouter's unified interface — text-to-video, image-to-video, and reference-to-video, billed precisely by upstream usage.

MiniMax H3 (MiniMax-H3) is MiniMax's next-generation video model. EasyRouter wraps its v2 async task API into the unified /v1/video/generations interface. A single model name covers text-to-video, image-to-video, and reference-to-video — the generation mode is inferred automatically from the media you send.

MiniMax H3 is an async task API: submitting returns a task_id immediately; poll the task status and download the video from data.result_url once it succeeds.

1. Model & Capabilities

There is a single model name: MiniMax-H3. The mode is decided by what media the request carries:

Mode	Trigger	Media input
Text-to-video (t2v)	`prompt` only	none
Image-to-video (i2v)	first frame (optional last frame)	`input_reference` / `images`
Reference-to-video (r2v)	reference image / video / audio	top-level `media[]`

prompt (text) is always required, regardless of mode.

2. Billing (Important)

MiniMax H3 is billed on the actual usage returned by upstream:

cost(USD) = total_billed_seconds × resolution_rate + billed_reference_images × $0.04
where: total_billed_seconds = input reference video seconds + generated video seconds

Resolution	Rate
2K	$0.13 / second
768P	$0.09 / second (not yet callable)

Key points:

Input reference video is billed too: in r2v, the reference video's billed seconds are counted at the output video's per-second rate.
Reference images are extra: $0.04 per billed reference image.
Pre-charged on submit, settled on completion by real usage: a pre-charge based on output duration is taken on submit; once the task succeeds, EasyRouter recomputes precisely from the upstream usage and settles the difference. So t2v/i2v are exact at submit time, while r2v (with input video) is finalized from the real usage on completion.
Consistent with MiniMax's official list price.

The v2 resolution currently accepts only 2K. The 768P rate is configured and will become callable once upstream enables it.

3. Submit a Task

POST /v1/video/generations

Headers

Header	Required	Value
`Authorization`	✓	`Bearer sk-YourAPIKey`
`Content-Type`	✓	`application/json`

Body fields

Field	Type	Required	Description
`model`	string	✓	Always `MiniMax-H3`
`prompt`	string	✓	Text prompt
`resolution`	string	—	Resolution, currently only `2K` (default `2K`)
`duration`	int	—	Generated video length in seconds, `4~15`, default `6`
`ratio`	string	—	Aspect ratio, e.g. `16:9` / `9:16` / `1:1` / `adaptive`. Default `16:9` for t2v; `adaptive` for i2v (follows the first frame)
`input_reference`	string	i2v	First-frame image URL (public / base64)
`images`	string[]	i2v	Image array: 1st = first frame, 2nd = last frame
`media`	object[]	r2v	Structured media input, see below

`media[]` element

For reference-to-video, to pin each reference asset's role:

`type`	Mapped role	Purpose
`reference_image`	reference image	Reference image (multiple allowed)
`reference_video`	reference video	Reference video (its seconds count toward billing)
`reference_audio`	reference audio	Reference audio
`first_frame` / `last_frame`	first / last frame	First/last frame for i2v

{
  "media": [
    { "type": "reference_image", "url": "https://.../ref.jpg" },
    { "type": "reference_video", "url": "https://.../ref.mp4" },
    { "type": "reference_audio", "url": "https://.../ref.mp3" }
  ]
}

Without structured media, EasyRouter infers roles from images / input_reference by extension and order: video → reference video, audio → reference audio, 1st image → first frame, 2nd image → last frame. Use media[] when you need precise role control.

Reference audio (reference_audio) is currently limited by upstream support: in testing the upstream returns a task failure (EasyRouter auto-refunds in full). If you need audio input, please confirm availability with us first. Text-to-video, image-to-video (first / first+last frame), and reference-image / reference-video generation all work normally.

Response

{
  "id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
  "task_id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1778250615
}

id / task_id is the EasyRouter public ID (task_ prefix) used for subsequent queries — not the upstream MiniMax task_id.

4. Query Task Status

GET /v1/video/generations/{task_id}

The response uses EasyRouter's unified {code, message, data} envelope.

Response (SUCCESS)

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
    "status": "SUCCESS",
    "result_url": "https://.../output.mp4",
    "progress": "100%",
    "quota": 390000,
    "properties": {
      "upstream_model_name": "MiniMax-H3",
      "origin_model_name": "MiniMax-H3"
    },
    "data": {
      "task": {
        "status": "succeeded",
        "content": { "url": "https://.../output.mp4" },
        "resolution": "2K",
        "duration": 6,
        "ratio": "16:9",
        "usage": {
          "total_seconds": 6,
          "input_seconds": 0,
          "output_seconds": 6,
          "input_image_count": 0
        }
      }
    }
  }
}

Status enum

Unified status	MiniMax status	Meaning
`QUEUED`	`queued` / `preparing`	Queued
`IN_PROGRESS`	`running`	Generating
`SUCCESS`	`succeeded`	Done, `result_url` is the video
`FAILURE`	`failed` / `cancelled` / `expired`	Failed, see `fail_reason`

Key fields

Field	Description
`data.result_url`	Video result URL (non-empty only on `SUCCESS`)
`data.quota`	Final charged quota (already settled by real usage on completion)
`data.data.task.usage`	Upstream precise usage — the billing basis

The video URL is a temporary signed link with limited validity; download or re-store it promptly.

5. Full Examples

# Step 1: submit
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-YourAPIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "A cat naps in the sun, fur swaying gently in the breeze",
    "resolution": "2K",
    "duration": 6,
    "ratio": "16:9"
  }'

# Step 2: poll (every 10-15s)
curl https://easyrouter.io/v1/video/generations/task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o \
  -H "Authorization: Bearer sk-YourAPIKey"

# Step 3: once data.status == "SUCCESS", download from data.result_url

# i2v: input_reference for the first frame; for last-frame interpolation use images with two URLs
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-YourAPIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "Camera slowly pushes in as the scene comes alive",
    "resolution": "2K",
    "duration": 6,
    "input_reference": "https://example.com/first.jpg"
  }'

i2v defaults to adaptive aspect ratio (follows the first frame). For first+last frame interpolation, use "images": ["firstURL", "lastURL"].

# r2v: pass reference image / video / audio via the top-level media[]
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-YourAPIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "Generate a coherent video referencing the given assets",
    "resolution": "2K",
    "duration": 6,
    "media": [
      { "type": "reference_image", "url": "https://example.com/ref.jpg" },
      { "type": "reference_video", "url": "https://example.com/ref.mp4" },
      { "type": "reference_audio", "url": "https://example.com/ref.mp3" }
    ]
  }'

When a reference video is included, its duration counts toward the billed seconds; the final cost follows the real usage returned when the task succeeds.

6. Polling Tips

Item	Recommendation
Interval	Every 10-15s, not below 5s to avoid rate limits
Terminal check	`data.status == "SUCCESS"` or `"FAILURE"`
Overall timeout	5-10 minutes
URL validity	Limited; download or re-store promptly

7. Error Handling

Case	Description
Missing `prompt`	HTTP 400, `prompt is required` (rejected before submit, no charge)
`401 / 403`	Invalid API Key / no access to this model
`402`	Insufficient balance (`insufficient user quota`), please top up
Task `FAILURE`	Upstream generation failed, see `data.fail_reason`; EasyRouter auto-refunds