MiniMax H3 API Integration Guide

Last verified: September 15, 2026

1. Validate user input.
2. Create the H3 generation task.
3. Store the returned task_id.
4. Poll the task-status endpoint.
5. Handle pending, success and failure states.
6. Read the completed video URL.
7. Copy completed output to application-controlled storage if needed.

user request
    → validate media
    → POST /v2/video_generation
    → task_id
    → poll task status
    → success / failure
    → video URL

MiniMax API requests use an API key passed through the Authorization header.

Authorization: Bearer YOUR_API_KEY

Do not expose API keys in browser-side JavaScript, public repositories, mobile application bundles, URLs, or analytics events. Production applications should call MiniMax from a trusted backend or secured server environment.

The shortest H3 integration has three steps: create a task, save the returned task ID, then query that task until the result is ready.

Step 1 — Store your API key

export MINIMAX_API_KEY="your-server-side-api-key"

Step 2 — Create a MiniMax H3 task

curl --request POST \
  --url https://api.minimax.io/v2/video_generation \
  --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cinematic tracking shot of a red sports car driving through rain at night."
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

The create response contains the identifier your application should persist immediately:

{
  "task_id": "YOUR_TASK_ID"
}

Step 3 — Query the task

curl --request GET \
  --url "https://api.minimax.io/v2/query/video_generation/${TASK_ID}" \
  --header "Authorization: Bearer ${MINIMAX_API_KEY}"

When the task reaches succeeded, read the generated video location from task.content.url. Save the result to storage you control instead of assuming a provider URL remains available indefinitely.

MiniMax H3 uses the same MiniMax-H3 model identifier across several generation workflows. The generation mode is determined primarily by the items and roles supplied inside the content[] array rather than by switching to a different H3 model name.

MiniMax H3 Text-to-Video API

For text-to-video, the prompt describes scene and motion while duration, resolution, and the required concrete ratio define the output. See the MiniMax H3 text-to-video guide for prompt construction.

curl --request POST \
  --url https://api.minimax.io/v2/video_generation \
  --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cinematic tracking shot of a red sports car driving through rain at night."
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

MiniMax H3 Image-to-Video and First/Last Frame API

Use first_frame, last_frame, or both to condition the shot boundaries. In this mode the image determines aspect ratio, so the API treats ratio as adaptive. Learn the creative workflow in the MiniMax H3 image-to-video guide.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "The sketch gradually becomes a polished product render while the camera slowly pushes forward."
    },
    {
      "type": "image_url",
      "image_url": { "url": "FIRST_FRAME_URL" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "LAST_FRAME_URL" },
      "role": "last_frame"
    }
  ],
  "resolution": "2K",
  "duration": 8
}

MiniMax H3 Reference-to-Video API

Reference-to-Video is useful when a generation must reuse information from supplied images, videos, or audio instead of relying only on text. Assign clear roles so H3 can distinguish visual, motion, and audio references. The official schema permits any combination of reference images, videos, and audio with the required text item.

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "Preserve the product identity, follow the reference camera motion, and use the supplied ambience."
    },
    {
      "type": "image_url",
      "image_url": { "url": "REFERENCE_IMAGE_URL" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "REFERENCE_VIDEO_URL" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "REFERENCE_AUDIO_URL" },
      "role": "reference_audio"
    }
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "16:9"
}

See the MiniMax H3 reference-to-video guide for role planning and input preparation.

MiniMax H3 API Python Example

This server-side example reads the key from the environment, submits and records a task ID, polls roughly every ten seconds with an overall timeout, handles terminal states, returns task.content.url, and downloads the MP4.

import os
import time
from pathlib import Path
import requests

API_KEY = os.environ["MINIMAX_API_KEY"]
BASE_URL = "https://api.minimax.io"
POLL_SECONDS = 10
TIMEOUT_SECONDS = 20 * 60

def create_task():
    response = requests.post(
        f"{BASE_URL}/v2/video_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "MiniMax-H3",
            "content": [{
                "type": "text",
                "text": "A slow aerial reveal of a lighthouse in a storm."
            }],
            "resolution": "768P",
            "duration": 5,
            "ratio": "16:9",
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

def wait_for_result(task_id):
    deadline = time.monotonic() + TIMEOUT_SECONDS
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/v2/query/video_generation/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["task"]
        status = task["status"]
        if status == "succeeded":
            return task["content"]["url"]
        if status in {"failed", "cancelled", "expired"}:
            raise RuntimeError(f"Task {task_id} ended with status {status}")
        if status not in {"queued", "running"}:
            raise RuntimeError(f"Unknown task status: {status}")
        time.sleep(POLL_SECONDS)
    raise TimeoutError(f"Task {task_id} exceeded the polling timeout")

def download(url, output_path="minimax-h3.mp4"):
    with requests.get(url, stream=True, timeout=120) as response:
        response.raise_for_status()
        with Path(output_path).open("wb") as output:
            for chunk in response.iter_content(1024 * 1024):
                output.write(chunk)
    return output_path

task_id = create_task()
video_url = wait_for_result(task_id)
print(download(video_url))

MiniMax H3 API Node.js Example

Use native server-side fetch. Keep process.env.MINIMAX_API_KEY in Node.js or another backend runtime—not in a client-side React component.

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const API_KEY = process.env.MINIMAX_API_KEY;
if (!API_KEY) throw new Error("MINIMAX_API_KEY is required");
const BASE_URL = "https://api.minimax.io";

async function api(path, init = {}) {
  const response = await fetch(BASE_URL + path, {
    ...init,
    headers: { Authorization: `Bearer ${API_KEY}`, ...init.headers },
  });
  if (!response.ok) throw new Error(`MiniMax ${response.status}: ${await response.text()}`);
  return response;
}

async function createTask() {
  const response = await api("/v2/video_generation", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "MiniMax-H3",
      content: [{ type: "text", text: "A macro shot of frost forming on glass." }],
      resolution: "768P",
      duration: 5,
      ratio: "16:9",
    }),
  });
  return (await response.json()).task_id;
}

async function waitForResult(taskId, timeoutMs = 20 * 60_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await api(`/v2/query/video_generation/${taskId}`);
    const task = (await response.json()).task;
    if (task.status === "succeeded") return task.content.url;
    if (["failed", "cancelled", "expired"].includes(task.status)) {
      throw new Error(`Task ended with status ${task.status}`);
    }
    if (!["queued", "running"].includes(task.status)) {
      throw new Error(`Unknown task status ${task.status}`);
    }
    await new Promise(resolve => setTimeout(resolve, 10_000));
  }
  throw new Error("Task polling timed out");
}

const taskId = await createTask();
const videoUrl = await waitForResult(taskId);
const download = await fetch(videoUrl);
if (!download.ok || !download.body) throw new Error("Download failed");
await pipeline(Readable.fromWeb(download.body), createWriteStream("minimax-h3.mp4"));

Supported concrete ratios are 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16. Reference mode can also use adaptive. The current official schema caps total request bodies at 64 MB and recommends public URLs for large inputs.

Verified input limits that affect request design

For production uploads, validate media before task creation so a rejected request never reaches your job queue. The current V2 schema accepts JPG, JPEG, PNG, WEBP, HEIC, and HEIF images. Each image can be up to 30 MB, with width and height from 256 to 5,760 pixels and an aspect ratio from 0.4 to 2.5. A frame-conditioned request accepts at most one first frame and one last frame; a reference request accepts up to nine reference images.

Reference videos may be MP4 or MOV with H.264/AVC or H.265/HEVC video. Each file can be up to 50 MB and 2–15 seconds long. A request can contain up to three reference videos, but their combined duration cannot exceed 15 seconds. Supported input frame rates run from 23.976 to 60 FPS. Reference audio may be WAV or MP3, up to 15 MB per file, with the same 2–15 second per-clip range and 15-second combined-duration ceiling.

These are input-media constraints, not output guarantees. Keep your validation rules versioned with the verification date, return specific validation messages to users, and recheck the official schema before changing accepted file types or limits. For large media, upload to controlled object storage and send a time-limited public URL instead of embedding Base64 in JSON.

Before calling the MiniMax API, validate MIME type, file size, media duration, reference count, URL accessibility, role combinations, supported resolution, and the required first/last-frame relationship.

Production applications should reject obviously invalid requests before sending them to MiniMax. This reduces avoidable API errors, failed tasks, unnecessary billing attempts, and poor user experience.

MiniMax currently lists H3 pay-as-you-go base output pricing at:

Additional input materials or regeneration can create separate charges. Current MiniMax pricing also lists input audio as free; the first five input images as free; additional images at $0.04 each; reference video billed by input duration and selected resolution; and 768P → 2K regeneration at $0.05 per regenerated second.

Pricing last verified: September 15, 2026

For full duration examples and cost calculation, see the MiniMax H3 pricing & cost calculator.

H3 Context-IR is a separate H3 processing step for interpreting and restructuring multimodal context before video generation. It should not be described as the video-generation endpoint itself.

MiniMax currently lists H3 Context-IR pricing separately from generated video: $0.90 per million input tokens and $3.60 per million output tokens.

MiniMax H3 768P to 2K Video Regeneration

MiniMax lists video regeneration separately from normal H3 generation. Its V2 regeneration workflow takes a compatible 768P H3 result and generates a 2K output. The current output regeneration price is $0.05 per second.

Direct 2K generation and 768P→2K regeneration are different billing paths. Applications exposing both should calculate and label the costs separately.

The API is asynchronous. Creating a task does not return the finished video. Create the task, store its task_id, poll the query endpoint, detect success or failure, and extract task.content.url.

task = create_h3_task()

while true:
    status = query(task.id)

    if status == success:
        return status.video_url

    if status == failed:
        raise generation_error

    wait(backoff)

Production Polling Strategy

Implementation guidance, not a MiniMax requirement: do not poll continuously without delay. Use bounded polling, progressive or exponential backoff, maximum wait limits, task-state persistence, and separate retries for network failures versus model-task failures. A practical client might make its first poll after 2–5 seconds and gradually increase the interval.

Also make task creation idempotent in your own product: store an internal request key before calling MiniMax, then associate the returned task ID with it. Log the API request ID on failures, alert on unusual completion times, and separate local polling timeouts from task failure—the task may still be queryable later.

Use the API when H3 must become part of a product or automated workflow. Use an online generator to test prompts without code. Use local H3 or MiniMax H3 ComfyUI when infrastructure control and experimentation matter more than deployment simplicity.

This guide separates MiniMax's official API/model facts from MiniMax3.org implementation recommendations. Endpoint, model, pricing, and capability facts should be rechecked against MiniMax's current official documentation whenever this page is updated.

• MiniMax Open Platform — H3 V2 create documentation
• MiniMax Open Platform — task query documentation
• MiniMax Open Platform — API pricing
• MiniMax official MiniMax-H3 repository and model documentation

Continue with MiniMax H3