Who this is for
This guide is for developers who want to generate images from text or edit reference images through the API. By the end you should be able to run one text-to-image call and one image edit, set the output size, and know what the API returns when generation fails.
What MiniMax-H3-Image does
MiniMax-H3-Image supports text-to-image and image editing. The output area can reach 20,000,000 pixels. You can set custom width and height, or give an aspect ratio with an area level[1].
The two modes use two endpoints. Text-to-image is POST /v1/images/generations and takes a prompt. Image editing is POST /v1/images/edits and takes a prompt plus 1 to 16 reference images[1]. Both endpoints are synchronous. With stream enabled, each image is pushed as soon as it finishes[1].
For the high-speed version, set model to MiniMax-H3-Image-Highspeed. It takes the same parameters and has the same limits as the standard model[1].
Setup
The examples use the OpenAI SDK with base_url set to https://api.minimax.io/v1. The key is read from the MINIMAX_API_KEY environment variable[1].
Your first image: text-to-image
Call client.images.generate with the model name, the prompt, a size and response_format="url". The returned url can be downloaded directly. For a failed image, url is None[1]:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ.get("MINIMAX_API_KEY"),
timeout=600,
max_retries=0, # not idempotent: disable automatic retries to avoid duplicate generation and charges
)
result = client.images.generate(
model="MiniMax-H3-Image",
prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
size="2720x1536",
response_format="url",
)
for i, item in enumerate(result.data):
print(i, item.url) # url is None for images that failedThe max_retries=0 setting is deliberate. The request is not idempotent, so automatic retries could generate duplicate images and duplicate charges[1].
Control the output size
Set the size in one of two ways, not both. If size is WIDTHxHEIGHT, setting aspect_ratio or area returns 400[1].
The first way is an aspect ratio plus an area level. area accepts 1K, 2K and 4K, with 4K as the default, targeting 1024×1024, 2048×2048 and 4096×4096 pixels. aspect_ratio defaults to auto and can be written as X:Y, with the ratio between 1:3 and 3:1. The server calculates the width and height, so 2K with 16:9 outputs 2720×1536. A setting such as { "aspect_ratio": "16:9", "area": "2K" } is enough[1].
The second way is explicit width and height. The area must be between 655,360 and 20,000,000 pixels, and the ratio must stay between 1:3 and 3:1, with the bounds included. Out-of-range values return 400, and the size is never scaled or rounded[1].
Common sizes are listed by the page. For 16:9, 2K is 2720x1536 and 4K is 5472x3072. For 9:16, 2K is 1536x2720 and 4K is 3072x5472[1].
Prompt enhancement and revised_prompt
Text-to-image enables prompt enhancement by default. If you turn it off with disable_prompt_enhanced: true, you must give width and height or a fixed X:Y ratio, or the request returns 400[1]. Image edits always apply prompt enhancement[1].
The prompt actually used for each image is returned in data[].revised_prompt[1]. To fine-tune, edit that text, send it as the prompt of a new text-to-image request, and set disable_prompt_enhanced: true[1]. To see the enhanced prompt without generating images, call the H3-Image-Context-IR endpoint, which supports only MiniMax-H3-Image[1].
Image edits: how to pass reference images
Reference images go in images[].image_url. The value can be a public URL, a mm_file://{file_id} reference to a file uploaded with purpose set to image_generation_input, or a data:image/<format>;base64,<Base64> data URI[1].
With the OpenAI SDK you can also upload files directly to images.edit as multipart/form-data. The order of the files sets the Picture number, so the first file is image 1 in the prompt[1]:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ.get("MINIMAX_API_KEY"),
timeout=600,
max_retries=0, # not idempotent: disable automatic retries to avoid duplicate generation and charges
)
# Upload reference images as files; list order is the Picture number
result = client.images.edit(
model="MiniMax-H3-Image",
image=[open("cat.jpg", "rb"), open("dog.png", "rb")],
prompt="Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
size="auto",
response_format="url",
)
for i, item in enumerate(result.data):
print(i, item.url) # url is None for images that failedThe reference image limits are[1]:
- Formats: JPG, JPEG, PNG, WEBP, HEIC and HEIF.
- Each file up to 64 MiB. Width and height from 128 to 8192 px. Long-to-short side ratio up to 4:1.
- Between 1 and 16 images.
- The whole request body must stay within 64 MiB. Base64 data is about 4/3 of the file size, so use public URLs or
mm_file://when the body would exceed the limit.
Handle partial and full failures
The request returns 200 as long as at least one image succeeds. data has n items. A failed item, or one withheld by the content safety check, contains only error. The success count is in usage.generated_images[1]:
"data": [
{"url": "https://example.com/h3-image/output-0.jpg", "size": "2720x1536", "revised_prompt": "..."},
{"error": {"code": "1027", "message": "output image failed content safety check"}}
]If every image fails, an error response is returned, with per-image data and usage. The status is 422 if all images failed the content safety check, 402 if all failed due to insufficient balance, and 500 otherwise[1].
Streaming output
With stream: true, each image is pushed over SSE when it completes. Only response_format: "url" is supported. Events arrive in completion order, so use image_index to match each event to its image[1].
The event types are <prefix>.partial_succeeded for one successful image, <prefix>.partial_failed for one failed image, and <prefix>.completed when everything has finished, which carries usage. An error event means no image succeeded. It is not billed, and every usage field is 0. The prefix is image_generation for text-to-image and image_edit for image edits[1].
Limits
- Preview images, masked edits and transparent backgrounds are not supported[1].
- A prompt can be up to 32000 characters. With prompt enhancement disabled, only about the first 4096 tokens take effect[1].
- One request produces 1 to 10 images, with 1 as the default. The default output format is jpeg, and png and webp are also accepted[1].
Next steps
The official reference pages list the text-to-image, image edit and streaming event APIs. Check those for field-level details[1].
Sources
- 1Image Generation GuideMiniMax API docs
Cite this page: Text-to-image and image editing with the MiniMax-H3-Image API. TellWorld, https://www.tellworld.net/practice/practice-minimax-h3-image-api. Updated 2026-11-15