> Markdown copy of https://makernice.com/blog/how-to-use-minimax-h3-image-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-Image for Pictures and Edits in Claude Code?

Makernice Team · 2026-11-11 · Updated 2026-11-12

Prices as of November 12, 2026 (price list v15).

## Key takeaways

-   MiniMax H3-Image is an image model with the id minimax-h3-image; it is separate from the MiniMax H3 video model, and an agent must use the image id to get pictures.
-   Text-to-image on MiniMax H3-Image offers 13 aspect ratios at 1k or 2k.
-   Edits take up to 16 reference images, have no aspect ratio setting, and add a fixed charge for every reference image.
-   The Makernice MCP server lets Claude Code and Cursor quote each image with estimate\_cost and create it with generate under an approved cap.

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-image-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3-Image+for+Pictures+and+Edits+in+Claude+Code%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-image-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3-Image+for+Pictures+and+Edits+in+Claude+Code%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-image-in-claude-code-and-cursor%2F+and+summarize+what+it+says+about+How+to+Use+MiniMax+H3-Image+for+Pictures+and+Edits+in+Claude+Code%3F.+Quote+the+page+for+prices+and+limits.)

To use MiniMax H3-Image in Claude Code or Cursor, connect the Makernice MCP server and ask for a picture from text or an edit built on up to 16 reference photos. The agent requests a quote with `estimate_cost`, gets your approval and then calls `generate`. A 1k image from text is $0.036 at price list v15 (November 12, 2026).

## Connection steps for Claude Code and Cursor

Claude Code: go to the [Claude Code setup](https://makernice.com/mcp/connect/claude-code/), copy the `claude mcp add --transport http --scope user makernice` line including the server address, and run it. Start a session, enter `/mcp`, select makernice and log in to Makernice when the browser opens.

Cursor: the [Cursor setup](https://makernice.com/mcp/connect/cursor/) installs the server with one click or gives you the `~/.cursor/mcp.json` entry. Then log in next to makernice in Cursor's MCP settings. Once connected, `get_balance` reports your balance, the connection's per-job limit and any daily cap.

## MiniMax H3-Image without an editor: Claude and ChatGPT connectors

If you would rather ask for MiniMax H3-Image in a chat window than in an IDE, Claude and ChatGPT can reach the same Makernice tools. Claude takes the server as a custom connector ([how to add it](https://makernice.com/mcp/connect/claude/)). ChatGPT on the web takes it as a custom MCP server with OAuth sign-in, on plans or workspaces that permit those, and points at its own server address ([how to add it](https://makernice.com/mcp/connect/chatgpt/)); that version leaves out `get_topup_link`. Nothing else changes for MiniMax H3-Image: the assistant gets a quote from `estimate_cost`, which does not reserve the amount, passes the figure you approve to `generate` as `max_cost_usd`, and fetches the finished image with `check_job`.

## Can MiniMax H3-Image turn an image into a video?

No, image-to-video is not supported on MiniMax H3-Image: the model makes still images only. To animate a MiniMax H3-Image picture, pass its link as `image_url` to [MiniMax H3](https://makernice.com/models/minimax-h3/) or [MiniMax H3 Max](https://makernice.com/models/minimax-h3-max/) in `mode` i2v; the [MiniMax H3 guide](https://makernice.com/blog/how-to-use-minimax-h3-in-claude-code-and-cursor/) walks through that request.

The two names are close, so watch the model id: MiniMax H3 is a video model whose id is minimax-h3. Tell the agent you want a still image, or name the id minimax-h3-image outright. The video id won't accept an image mode, and an image request needs `mode` t2i or i2i. If in doubt, the agent can call `list_models` without arguments and read the `type` field, which says video or image for every model.

## A 21:9 banner from MiniMax H3-Image, estimate first

**You:** We need an ultra-wide homepage banner of an alpine lake at dawn with room on the left for a headline. 2k. Price?

**Cursor** sets the shape and size and calls:

```
{
  "name": "estimate_cost",
  "arguments": {
    "input": {
      "model": "minimax-h3-image",
      "mode": "t2i",
      "prompt": "Ultra-wide hero banner: a calm alpine lake at first light, pine forest on the right edge, empty sky on the left half for a headline, crisp photographic detail",
      "resolution": "2k",
      "aspect_ratio": "21:9"
    }
  }
}
```

**Cursor:** One 2k image from MiniMax H3-Image is $0.036 (price list v15). Nothing is created by this estimate. Go ahead?

**You:** Go ahead.

```
{
  "name": "generate",
  "arguments": {
    "input": {
      "model": "minimax-h3-image",
      "mode": "t2i",
      "prompt": "Ultra-wide hero banner: a calm alpine lake at first light, pine forest on the right edge, empty sky on the left half for a headline, crisp photographic detail",
      "resolution": "2k",
      "aspect_ratio": "21:9"
    },
    "max_cost_usd": "0.036",
    "request_id": "alpine-lake-hero-21x9"
  }
}
```

When `generate` is called, Makernice quotes the input once more. A quote above `max_cost_usd` or the connection's per-job limit ends the call with a refusal and no job; otherwise the job is created and billed at that quote, and the response includes its `job_id`. If the agent repeats the call with the same `request_id` and input, it receives the existing job.

```
{
  "name": "check_job",
  "arguments": {
    "job_id": "gen_...",
    "wait_s": 45
  }
}
```

`check_job` returns once the image is done or the wait expires (at most 55 seconds). The image sits at `outputs[0].url` as a signed link that lasts 24 hours; call `check_job` again for a new link, or open `console_url` to find it in your console. An account [webhook](https://makernice.com/docs/#webhooks) also covers jobs started over MCP.

The full set of text-to-image shapes is 1:1, 1:2, 2:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9. Leave `resolution` out and you get 1k. More on the model is on the [MiniMax H3-Image model page](https://makernice.com/models/minimax-h3-image/).

## How do I edit images with MiniMax H3-Image, and does it support layers or inpainting?

MiniMax H3-Image edits images in `mode` i2i: send 1 to 16 public https links in `reference_images` and write the change you want in `prompt`. Layers and inpainting are not supported, because the Makernice request has no mask or layer field, so describe the area to change in words instead.

References for MiniMax H3-Image are JPEG, PNG or WebP files of up to 10 MB. Edits have no `aspect_ratio` field; the result follows the reference images. The price is a base amount, $0.036 at 1k or $0.036 at 2k, plus $0.0096 for each reference image, the first one included. Edits with different numbers of references therefore get different quotes, so the agent should estimate after settling the list. MiniMax's guide sets each reference at 128 to 8192 px per side with a long-to-short ratio of at most 4:1, as listed on the [image limits page](https://makernice.com/docs/image-limits/); Makernice doesn't measure MiniMax H3-Image references before the job starts.

Here the agent prices a 1k group shot assembled from four portraits:

```
{
  "name": "estimate_cost",
  "arguments": {
    "input": {
      "model": "minimax-h3-image",
      "mode": "i2i",
      "prompt": "Make a team photo: place the four people from the references side by side on the lake shore from the banner, same morning light",
      "reference_images": [
        "https://example.com/team/ana.jpg",
        "https://example.com/team/ben.jpg",
        "https://example.com/team/chen.jpg",
        "https://example.com/team/dora.jpg"
      ],
      "resolution": "1k"
    }
  }
}
```

## Why did my MiniMax H3-Image generation fail, and is a failed task charged?

A failed MiniMax H3-Image generation is not charged: `check_job` shows `status` failed with an `error` object, `billing` moves to released and the hold is returned. Typical causes are a prompt or reference rejected by moderation, a reference link that redirects or can't be fetched, a reference outside the pixel or ratio limits, or a failure at the model provider. A finished image blocked by output moderation is still charged; the rules are on [failed generations](https://makernice.com/pricing/failed-generations/).

Refusals before a job exists are a separate case. Refusals reach the agent as readable text, and the call leaves no job and no charge. Column one is the name Makernice's server code uses for the refusal; column two, the beginning of the returned text.

| Refusal | What the tool returns | What to do |
| --- | --- | --- |
| `invalid_request` | "Invalid parameters" | The text names the field, for example more than 16 references |
| `price_unavailable` | "This model, mode and resolution combination is not available right now." | That model, mode and resolution can't be ordered right now; check the id and mode with `list_models` |
| `price_exceeds_max_cost` | "which exceeds max\_cost\_usd" | References were added after the estimate; quote again and approve the new figure |
| `per_job_limit_exceeded` | "which exceeds this connection's per-job limit" | Trim the reference list or use 1k, or raise the connection's per-job limit |
| `insufficient_balance` | "Insufficient balance for this job. Nothing was charged." | Top up and resend with the same `request_id` |

## Frequently asked questions

#### Is MiniMax H3-Image the same model as MiniMax H3?

No. minimax-h3-image makes still images, while minimax-h3 is a video model. Use the image id for t2i and i2i requests.

#### How many reference images can MiniMax H3-Image use, and does it take reference videos?

MiniMax H3-Image takes 1 to 16 reference images in edit mode, sent as public https links. Reference videos are not supported, and text-to-image takes no references.

#### Can I set an aspect ratio when editing with MiniMax H3-Image?

No. Only text-to-image takes aspect\_ratio; an edit follows its reference images.

#### How is a MiniMax H3-Image edit with many references priced?

A base price per output image plus a fixed amount for every reference image, so estimate\_cost should be run on the final reference list.

#### Which MiniMax H3-Image resolutions can Cursor request?

1k and 2k, with 1k used when the request leaves resolution out.

## Models in this post

Image

### MiniMax H3-Image

MiniMax H3-Image: generate images in 13 aspect ratios or edit with up to 16 reference images, at 1K or 2K.

By MiniMaxFrom $0.036/img

https://makernice.com/models/minimax-h3-image/