MiniMax Hailuo H3 video API

Text, image, and multimodal-reference video generation with MiniMax-H3 — 4-15s clips at 768P or 2K, billed only on completed output.

HopBase exposes MiniMax Hailuo H3 through the official MiniMax v2 contract. It is an asynchronous API: submit a task, then poll the HopBase task ID. Use a key that has the MiniMax group enabled and confirm availability with GET /v1/models before sending paid work.

Endpoints

Method	Path	Purpose
POST	`/v1/video/generate`	Submit a MiniMax H3 video task
GET	`/v1/video/tasks/{task_id}`	Query one task
GET	`/v1/video/tasks`	List the current user's tasks

All requests use Authorization: Bearer sk-your-key and Content-Type: application/json. The body mirrors MiniMax's official POST /v2/video_generation request and is decoded strictly: unknown fields and a second JSON value are rejected before the upstream is called.

Model

Model ID	Duration	Resolution	Reference input
`MiniMax-H3`	integer 4-15 s	`768P` / `2K`	up to 9 images, 3 video clips, 3 audio tracks

Use the exact ID MiniMax-H3. No aliases are registered; unknown model names are rejected.

Request contract

content is a multimodal array. It must contain exactly one non-empty text element (the prompt, up to 7,000 characters). Media elements declare their role explicitly:

Element	Roles	Limit
`image_url`	`first_frame` (default when omitted), `last_frame`, `reference_image`	1 first + 1 last frame, or up to 9 reference images
`video_url`	`reference_video` (required, explicit)	up to 3 clips
`audio_url`	`reference_audio` (required, explicit)	up to 3 tracks

First/last-frame elements and reference_* elements are mutually exclusive in one request.

Audio references must be accompanied by at least one image or video reference — audio-only reference input is rejected. Mixed reference input is capped at 12 files in total.

Media url values accept an absolute public http(s) URL or a data: URI (base64 embed). mm_file:// locators are rejected — the file would belong to your own MiniMax account, which the gateway cannot access. callback_url is not supported; poll the task instead.

Input and output specs

Output: 24 FPS; every clip ships with native stereo audio — dialogue and voice-over are generated in-model, with TTS covering 11 languages (Chinese, English, Japanese, Korean, French, German, Spanish and more). 2K means a 1440-pixel short side for ratios between 16:9 and 9:16 (wider ratios keep ≈3.7M total pixels, e.g. 21:9 → 2976×1248); 768P follows the same rule at 768 px / ≈1M pixels.
Images: JPG / JPEG / PNG / WEBP / HEIC / HEIF, ≤30 MB each, 256-5760 px per side, aspect between 5:2 and 2:5.
Video references: H.264 / H.265, ≤50 MB each, 2-15 s per clip and ≤15 s combined.
Audio references: WAV / MP3, ≤15 MB each, 2-15 s per track and ≤15 s combined.
Size limits are per asset; the whole request body is capped at 64 MB, so prefer URL references over data: embeds for large media.

Aspect ratio

Text-to-video: ratio is required and cannot be adaptive — choose 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
Image-to-video (first / last frame): the output always follows the input image. Any legal ratio value is accepted and normalized to adaptive, matching official behavior. To get a specific ratio, crop the frame image first.
Multimodal reference: ratio is optional and defaults to adaptive.

Example — text-to-video

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{ "type": "text", "text": "Aerial drone shot over snow mountains above a sea of clouds at sunrise" }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

The submission responds with 202 and a HopBase task ID:

{ "id": "mmt60x430684635582774", "object": "video.generation.task", "model": "MiniMax-H3", "status": "queued", "billing_bucket": "2k" }

Example — image-to-video

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "The camera slowly pushes in, light drifting across the scene" },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." }, "role": "first_frame" }
  ],
  "resolution": "768P",
  "duration": 4
}

Use stable media hosting or data: embeds

Reference media is downloaded by the upstream, not by HopBase. Image hosts that block datacenter IPs (many free image CDNs do) cause the task to fail minutes after submission. Prefer data: embeds or your own OSS / CDN.

Task lifecycle

Poll GET /v1/video/tasks/{task_id}. Status moves queued → processing → completed | failed. A typical clip completes in 1.5-3 minutes. On completion the response carries stable HopBase relay URLs (upstream download links expire; the relay refreshes them transparently):

{
  "id": "mmt60x430684635582774",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/relay/..."],
  "usage": { "bucket": "2k", "billed_seconds": 4, "input_seconds": 0, "extra_input_images": 0 }
}

Billing

Billing happens only when the task succeeds, from upstream-reported usage:

Output seconds and reference-video input seconds are billed at the resolution tier (768P or 2K).
The first 5 input images are free; each additional image is billed per image.
Reference audio is free. Failed or safety-filtered generations are never billed.

See the pricing page for official list prices; your effective rate is shown in the signed-in model catalog.

On this page