MiniMax H3 Image API Tutorial: Generate and Edit Images

You have a brief for a wide food photograph. First you need a frame with bread and vegetables on a wooden table. Then you want a version with a different napkin color while keeping the dishes where they are.

The MiniMax H3 Image API handles those jobs with two endpoints. Send a text prompt to POST /v1/images/generations, then pass the resulting image URL and an edit instruction to POST /v1/images/edits. Both examples below use the global MiniMax API and save a PNG you can inspect. MiniMax image generation guide

1. Set up your MiniMax API key

Open the MiniMax API Platform and create a pay-as-you-go API key. You'll need curl, jq, and an account balance for the requests. Run the commands from the same Bash or Zsh session. Paste the key when the first command waits for input, then press Enter.

read -rs MINIMAX_API_KEY
export MINIMAX_API_KEY

Keep the key in your server environment if you turn the example into a web app. Have your backend send the bearer token to MiniMax.

2. Generate an image from a text prompt

Start with one 2K landscape frame. The prompt names the objects, the camera angle, and the piece of blue linen you'll change in the next step. This request uses the text-to-image endpoint.

curl --silent --show-error --fail-with-body \
  --max-time 600 \
  --request POST https://api.minimax.io/v1/images/generations \
  --header "Authorization: Bearer ${MINIMAX_API_KEY:?Set your MiniMax API key}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3-Image",
    "prompt": "Overhead editorial food photograph of a loaf of sourdough, sliced pears, and roasted carrots on a weathered oak table. Place a folded blue linen napkin in the lower right. Use soft window light and leave a strip of bare wood along the top.",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "output_format": "png",
    "response_format": "url"
  }' \
  --output h3-generation.json

With streaming off, the request waits for the result. Read data[0].url to download the file, and check data[0].size for its dimensions. The JSON also includes the expanded prompt in data[0].revised_prompt.

jq -r '.data[0].size' h3-generation.json
image_url="$(jq -er '.data[0].url | strings | select(length > 0)' h3-generation.json)" &&
  curl --fail --silent --show-error --location "$image_url" --output h3-generation.png

The expected dimensions are 2720x1536. Open h3-generation.png and check for the blue napkin before continuing. Save the image bytes to your own storage for any workflow that needs the file later.

The two renders show a similar overhead food brief. The right-hand image is an API sample from a separate prompt.

3. Edit the image with a reference

Reuse the URL from the generation response. The edit prompt names the change and the parts of the frame to preserve. Set the same output size for an easier side-by-side comparison. MiniMax image edit endpoint

reference_url="$(jq -er '.data[0].url | strings | select(length > 0)' h3-generation.json)" &&
  curl --silent --show-error --fail-with-body \
    --max-time 600 \
    --request POST https://api.minimax.io/v1/images/edits \
    --header "Authorization: Bearer ${MINIMAX_API_KEY:?Set your MiniMax API key}" \
    --header 'Content-Type: application/json' \
    --data "$(jq -n --arg ref "$reference_url" '{
      model: "MiniMax-H3-Image",
      prompt: "In image 1, change the blue linen napkin to sage green. Preserve its fold and position. Keep the food, the framing, and the direction of the window light.",
      images: [{image_url: $ref}],
      size: "2720x1536",
      n: 1,
      output_format: "png",
      response_format: "url"
    }')" \
    --output h3-edit.json

edited_url="$(jq -er '.data[0].url | strings | select(length > 0)' h3-edit.json)" &&
  curl --fail --silent --show-error --location "$edited_url" --output h3-edit.png

Compare the two PNGs at the same scale. Check the napkin color first, then the food placement, shadows, and crop. If the original render omitted the napkin, pick another visible object and name it in the edit prompt.

In this separate edit example, the image on the left is the reference. The API result on the right changes the hosts' pose and removes the headphones while retaining the podcast set.

The edit endpoint accepts one to 16 reference images. For a multi-image request, list the base image first and explain what each additional image supplies. Each image_url can be a publicly fetchable URL, a Base64 data URI, or an mm_file:// ID from a MiniMax file upload. If the original download URL stops working, use the saved PNG through one of those input methods.

The empty room defines the space. The furniture references define the pieces to bring into it. Give each reference a role in your prompt so the model knows what to carry over.

4. Choose 2K, 4K, or exact dimensions

MiniMax uses area to set a target pixel count. The aspect ratio then determines the width and height.

If a video timeline or design template expects exactly 3840 × 2160, send "size": "3840x2160" and remove aspect_ratio and area from the request. Exact sizes must fit within 655,360 to 20,000,000 pixels and a 1:3 to 3:1 width-to-height ratio. If you use area-based sizing, keep area explicit while testing because its default is 4K.

What does the API cost?

Both endpoints accept the same two model IDs. Use MiniMax-H3-Image for the examples above or change the model to MiniMax-H3-Image-Highspeed to try the faster tier with the same request fields. MiniMax bills for text input, image input when present, and image output. Its published examples for a square 2K text-to-image request are about $0.023 for Standard and $0.036 for Highspeed as of November 11, 2026. Those figures are estimates. Prompt enhancement and reference images affect actual usage. MiniMax image API pricing

Troubleshoot the first request

Once you have both PNGs, try the same edit with a reference of your own. If you'd like to refine the prompt in a browser before adding it to your app, open the AI H3 Image generator and editor and use Image to Image for the second pass.