How to Use MiniMax H3 (Hailuo 03) in Claude Code and Cursor?

To use MiniMax H3 (Hailuo 03) in Claude Code or Cursor, connect the Makernice MCP server and ask for a clip: the agent prices it with estimate_cost, you approve, and generate starts the job with that amount as max_cost_usd, so the charge can't go over. MiniMax H3 defaults to 2k, and a 5-second clip at that tier is $0.78 on price list v15 (November 12, 2026).

How do I generate MiniMax H3 (Hailuo 03) videos in Claude Code through an MCP server?

MiniMax H3 comes with the Makernice MCP server, which you install once per editor. In a terminal, run claude mcp add --transport http --scope user makernice with the address from the Claude Code instructions, then type /mcp in Claude Code and sign in. The Cursor instructions offer a one-click install or a block for ~/.cursor/mcp.json, followed by a sign-in from Cursor's MCP settings.

Both editors then see the same tools. Ask for list_models with the MiniMax H3 id if you want the agent to read the accepted modes, tiers, ratios and per-second prices straight from Makernice before it writes a request.

MiniMax H3 runs in Claude and ChatGPT chats once Makernice is added as a custom connector; only the setup differs from Claude Code. Every client makes the same calls: an estimate_cost quote that informs you but locks nothing, a generate call capped by max_cost_usd, then check_job until the clip is ready.

• In Claude, open Customize, then Connectors, and choose Add custom connector; paste the MCP URL and connect with your Makernice login. Team and Enterprise workspaces need an owner to add it first. Full steps: Claude connect page.
• In ChatGPT on the web, open Plugins and add a custom MCP server with OAuth, pasting the ChatGPT-specific address; your plan or workspace must allow this. Mention Makernice with @ in a new chat to use it. Full steps: ChatGPT connect page.

How do I write a MiniMax H3 text-to-video request, and which settings matter?

A MiniMax H3 text-to-video request needs mode t2v and a prompt of up to 4,000 characters; the settings that change the result and the price are duration (5 to 15 whole seconds, default 5), resolution (480p, 768p, 2k, 4k, default 2k) and aspect_ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16). Here is the whole exchange in Claude Code:

You: I need an ultrawide establishing shot of a lighthouse in a storm for the intro. Use MiniMax H3 and tell me the cost first.

Claude Code builds the request at the default tier and prices it:

{
  "name": "estimate_cost",
  "arguments": {
    "input": {
      "model": "minimax-h3",
      "mode": "t2v",
      "prompt": "A lighthouse on a rocky point during a storm, waves burst against the rocks, the beam sweeps through rain, aerial shot slowly circling",
      "duration": 5,
      "resolution": "2k",
      "aspect_ratio": "21:9"
    }
  }
}

Claude Code: 5 seconds of MiniMax H3 at 2k is $0.78 (price list v15). No charge so far. Should I generate it?

You: Yes.

The agent passes the same input to generate, along with the amount you approved and a request_id that identifies this attempt:

{
  "name": "generate",
  "arguments": {
    "input": {
      "model": "minimax-h3",
      "mode": "t2v",
      "prompt": "A lighthouse on a rocky point during a storm, waves burst against the rocks, the beam sweeps through rain, aerial shot slowly circling",
      "duration": 5,
      "resolution": "2k",
      "aspect_ratio": "21:9"
    },
    "max_cost_usd": "0.78",
    "request_id": "storm-lighthouse-2k-a"
  }
}

On arrival, generate takes a fresh quote. The job is created and charged that quote only if it is no higher than max_cost_usd and fits the connection's per-job limit; otherwise the call is refused and nothing exists to pay for. A retry with the same request_id and the same input hands back the original job, so a dropped connection never leads to two charges.

The agent follows up with check_job, passing wait_s of up to 55 seconds so it waits for the clip. When the job has succeeded, the MP4 is behind outputs[0].url, a signed link that lasts 24 hours, and console_url points to the run in the Makernice console. Prefer a push to polling? Set an account webhook; it fires for MCP jobs too.

Can MiniMax H3 output 1080p or 4K, and is that upscaled?

MiniMax H3 outputs 480p, 768p, 2k, 4k. A resolution value outside those tiers is refused as invalid parameters without a charge. Only 480p and 768p are native; the 2k default and 4k are upscaled from 768p by the model, and Makernice has no separate upscale mode, so you pick the tier when you generate. For 1080p from the same vendor, MiniMax H3 Max offers a 1080p tier refined from 768p.

MiniMax H3 per-second prices on price list v15 (November 12, 2026) are $0.06 at 480p, $0.072 at 768p, $0.156 at 2k and $0.192 at 4k. Multiply by the clip length, or have the agent price the exact request. The MiniMax H3 model page lists the full specification, and the MiniMax H3 Max vs MiniMax H3 comparison sets it beside the Max variant.

How do I use images with MiniMax H3 (Hailuo 03): image-to-video, first and last frame, and reference images?

MiniMax H3 turns an image into a video with mode i2v: send the still as image_url, describe the motion in prompt, and keep duration and resolution as for text-to-video. Image-to-video on MiniMax H3 has no aspect_ratio field, so the clip follows the shape of the still, and a request that adds one is refused. The image has to be a public https link to a JPEG, PNG or WebP file of at most 10 MB; a path on your disk can't be read over MCP.

Makernice measures every MiniMax H3 input image when the job is created: shorter side at least 256 px, longer side at most 5760 px, and width divided by height between 0.4 and 2.5. An image outside those limits is refused as invalid parameters before anything is held, so crop a tall phone screenshot or a wide panorama first.

First and last frame. MiniMax H3 uses first and last frame images in mode flf: image_url is the opening frame, last_image_url is the closing frame, and the prompt describes what happens in between. Both images follow the same size limits as image-to-video, and the clip still runs 5 to 15 seconds. Here the agent prices a storm-to-dawn transition at native 768p:

{
  "name": "estimate_cost",
  "arguments": {
    "input": {
      "model": "minimax-h3",
      "mode": "flf",
      "prompt": "The storm clears as the camera pulls back from the lighthouse, the sea calms and dawn light spreads",
      "image_url": "https://example.com/frames/lighthouse-storm.jpg",
      "last_image_url": "https://example.com/frames/lighthouse-dawn.jpg",
      "duration": 5,
      "resolution": "768p"
    }
  }
}

Reference images. MiniMax H3 takes 1 to 5 reference images in mode r2v, sent as public https links in reference_images, with 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 as aspect ratios. Reference videos are not supported: the Makernice request has no video input field for MiniMax H3, so a character or style has to come from stills. Keep each reference inside the same pixel and ratio limits as a first frame, and name in the prompt who or what each reference shows.

How do I call the MiniMax H3 API from Python, and where are the docs?

MiniMax H3 is called from Python through the Makernice REST API with an API key: request a quote, then create the generation with that quote id and an Idempotency-Key header. The quote locks the price for 12 minutes. The API docs cover authentication, statuses and errors, and the quickstart has a complete script that also polls and downloads the file.

import os, uuid, requests

API = "https://api.makernice.com/v1"
H = {"Authorization": f"Bearer {os.environ['MAKERNICE_API_KEY']}"}
job = {"model": "minimax-h3", "mode": "t2v", "duration": 5, "resolution": "2k",
       "aspect_ratio": "21:9", "prompt": "A lighthouse on a rocky point during a storm, waves burst against the rocks, the beam sweeps through rain, aerial shot slowly circling"}

# 1. Quote: exact amount in micro-USD, locked for 12 minutes
quote = requests.post(f"{API}/generations/quote", json=job, headers=H, timeout=30).json()
print(quote["amount"], "micro-USD, valid until", quote["expires_at"])

# 2. Create with the quote id; the same Idempotency-Key never creates a second job
gen = requests.post(f"{API}/generations", json={"quote_id": quote["id"], "input": job},
                    headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30).json()
print(gen["id"], gen["status"])  # poll GET /generations/{id} until succeeded or failed

Instead of polling, you can set an account webhook. The same model id, minimax-h3, works in the REST API, the MCP tools and the Create area of the Makernice console.

Why is my MiniMax H3 (Hailuo 03) video stuck in queue, and how long does it take?

A MiniMax H3 job waits in queued until a slot is free, then moves through generating and output moderation to succeeded; Makernice does not publish a typical MiniMax H3 render time. Each account runs 2 jobs at a time by default, so a third job waits, and over MCP a new request may be refused until one finishes. A job that is still queued can be canceled with cancel_job, which releases the held amount in full; once generating has started, it can't be canceled.

Why did my MiniMax H3 (Hailuo 03) generation fail, and is a failed task charged?

A failed MiniMax H3 generation is not charged: check_job shows status failed with an error object and billing released, and the held money returns to your balance. The common causes are a prompt or input image rejected by moderation, an image that can't be fetched or used, a run that times out, or a failure at the model provider. One exception applies: a finished output blocked by output moderation is still charged, and support can review it manually. What is charged in each case is listed on failed generations.

Refused calls are a separate case: they come back over MCP as readable sentences and have created and charged nothing. Below, the first column is the server-side name of each refusal and the second is the beginning of the text the tool returns.

Where can I use MiniMax H3 (Hailuo 03), and can I run it locally?

MiniMax H3 can be self-hosted, because MiniMax publishes open weights: the H3-Base checkpoints are on Hugging Face under the MiniMax H3 Community License Agreement (checked 2026-11-12). The model card lists the H3-Regenerate-2K module as not yet open-sourced and available only through MiniMax's API. Makernice runs MiniMax H3 as a hosted model only, so it doesn't run on your own machine through Makernice.

On Makernice, MiniMax H3 works through the REST API, the MCP server in Claude Code, Cursor, Claude and ChatGPT, and the Create area of the console, at the same price. For other hosted platforms that list a US-dollar price for MiniMax H3, see Best MiniMax H3 alternatives.