> Markdown copy of https://makernice.com/blog/how-to-use-minimax-h3-in-claude-code-and-cursor/ for AI tools. The HTML page is the canonical version. [← All posts](https://makernice.com/blog/) Guides # How to Use MiniMax H3 (Hailuo 03) in Claude Code and Cursor? Makernice Team · 2026-11-11 · Updated 2026-11-12 Prices as of November 12, 2026 (price list v15). ## Key takeaways - MiniMax H3 defaults to 2k; a 5-second 2k clip is $0.78 at price list v15 (November 12, 2026). - MiniMax H3 renders 480p and 768p natively; its 2k and 4k tiers are upscaled from 768p, and 1080p is not one of its tiers. - MiniMax H3 takes text, one start image, a first and last frame, or up to 5 reference images; reference videos are not supported. - MiniMax H3 output always includes an audio track, and no request field turns it off. - MiniMax publishes open weights for MiniMax H3 on Hugging Face (checked 2026-11-12); Makernice runs it as a hosted API only. Ask an AI assistant about this page[Ask ChatGPT](https://chatgpt.com/?q=Read+https%3A%2F%2Fmakernice.com%2Fblog%2Fhow-to-use-minimax-h3-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3+%28Hailuo+03%29+in+Claude+Code+and+Cursor%3F.+Quote+the+page+for+prices+and+limits.)[Ask Claude](https://claude.ai/new?q=Read+https%3A%2F%2Fmakernice.com%2Fblog%2Fhow-to-use-minimax-h3-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3+%28Hailuo+03%29+in+Claude+Code+and+Cursor%3F.+Quote+the+page+for+prices+and+limits.)[Ask Perplexity](https://www.perplexity.ai/search?q=Read+https%3A%2F%2Fmakernice.com%2Fblog%2Fhow-to-use-minimax-h3-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3+%28Hailuo+03%29+in+Claude+Code+and+Cursor%3F.+Quote+the+page+for+prices+and+limits.) 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](https://makernice.com/mcp/connect/claude-code/), then type `/mcp` in Claude Code and sign in. The [Cursor instructions](https://makernice.com/mcp/connect/cursor/) 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](https://makernice.com/mcp/connect/claude/). - 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](https://makernice.com/mcp/connect/chatgpt/). ## 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](https://makernice.com/docs/#webhooks); 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](https://makernice.com/models/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](https://makernice.com/models/minimax-h3/) lists the full specification, and the [MiniMax H3 Max vs MiniMax H3 comparison](https://makernice.com/blog/minimax-h3-max-vs-minimax-h3/) sets it beside the Max variant. | You type | Request field | | --- | --- | | Native resolution, please | `resolution` 768p or 480p | | The sharpest version you have | `resolution` 4k (upscaled from 768p) | | Cinema-wide framing | `aspect_ratio` 21:9 | | Animate this still | `mode` i2v with `image_url` | | Go from this frame to that one | `mode` flf with `image_url` and `last_image_url` | | Keep these characters on screen | `mode` r2v, up to 5 `reference_images` | ## 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](https://makernice.com/docs/) cover authentication, statuses and errors, and the [quickstart](https://makernice.com/docs/#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](https://makernice.com/docs/#webhooks). 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](https://makernice.com/pricing/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. | Refusal | What the tool returns | What to do | | --- | --- | --- | | `invalid_request` | "Invalid parameters" | A tier outside 480p, 768p, 2k, 4k, a length outside 5 to 15 seconds or an image outside the size limits | | `price_exceeds_max_cost` | "which exceeds max\_cost\_usd" | Moving from 768p to 2k or 4k raises the price; estimate again and approve the new amount | | `per_job_limit_exceeded` | "which exceeds this connection's per-job limit" | Use a native tier or a shorter clip, or raise the per-job limit for this connection | | `concurrency_limit_reached` | "Too many jobs are running for this account right now." | Wait for a running MiniMax H3 job to finish, then resend | | `not_cancelable` | "This job has already started generating and can no longer be canceled." | Let it finish; only queued jobs can be canceled | | `insufficient_balance` | "Insufficient balance for this job. Nothing was charged." | Top up and resend with the same request\_id | ## 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](https://huggingface.co/MiniMaxAI/MiniMax-H3) 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](https://makernice.com/blog/best-minimax-h3-alternatives/). ## Frequently asked questions #### Does MiniMax H3 (Hailuo 03) generate audio, and can I control it? MiniMax H3 generates audio with every clip: the output includes a soundtrack, and no request field turns it on, off or swaps it. Makernice documents no separate voice, music or sound-effect controls for MiniMax H3, and Makernice has no music or voice models, so replace the track in your own editor if you need a specific score or voice-over. #### Is there a free MiniMax H3 (Hailuo 03) API? Makernice has no free credits for MiniMax H3; the balance is prepaid in US dollars and never expires. estimate\_cost returns a price without creating a job or charging your balance, and a failed run is not charged, though an output blocked by output moderation is. #### Is there a cheaper MiniMax H3 API than Makernice? Per-second MiniMax H3 prices from other platforms sit next to the Makernice price for each tier in the third-party price table on the MiniMax H3 model page (checked 2026-11-11). Makernice bills per second of requested duration from a prepaid balance with no subscription. #### Are unlimited MiniMax H3 (Hailuo 03) plans really unlimited? Makernice has no unlimited or subscription plan for MiniMax H3, so the cost of a clip is its per-second price times its length. This page doesn't assess the plans on MiniMax's own apps. #### Why was my MiniMax H3 generation blocked by content moderation? Makernice moderates prompts and input images before a MiniMax H3 run and checks finished outputs afterwards; the Acceptable Use Policy bans sexual content, graphic violence, hate speech, content that endangers minors, deepfakes or impersonation of real people, and copyright or trademark infringement. A prompt or image rejected before generation is not charged. A finished output blocked by output moderation is still charged, and support can review it manually. #### Why did MiniMax H3 return a video shorter than I requested? MiniMax H3 uses the default of 5 seconds when a request leaves duration out, which is the usual reason a clip comes back shorter. Send duration as a whole number from 5 to 15; the price is the per-second rate times the requested seconds. #### How do I control camera movement in MiniMax H3? MiniMax H3 has no camera-control field on Makernice, so describe the move in the prompt, for example a slow push-in, a pan to the left or an aerial shot circling the subject. #### Can MiniMax H3 edit images? No, image editing is not supported on MiniMax H3, which is a video model. Use MiniMax H3-Image, the image model, whose edit mode takes up to 16 reference images. ## Models in this post Video ### MiniMax H3 \-25% MiniMax's H3 with a 2K default and a 4K option — 5–15 second clips from text, a still, first and last frames, or up to 5 references. By MiniMaxFrom $0.06/s https://makernice.com/models/minimax-h3/