Workflows · verified 2026-11-13
Three MiniMax H3-Image workflows, and where each one breaks
Short answer
H3-Image has two request shapes and one shared prompt pipeline. Text-to-image takes a prompt and a size; editing takes the same prompt plus one to sixteen ordered reference images. Both can return up to 10 images in one request, and both can succeed partially. The workflow that fits depends less on the model than on whether your input is a sentence or a set of pictures that already define the answer.
Released 2026-11-11 MiniMax API guide → Local examples →
- 2request shapesgenerations and edits
- 16reference imagesorder is part of the prompt
- 10images per requesteach can fail independently
- 6sampling stepsno CFG and no negative prompt
The shape of the whole API
- Text-to-image sends a prompt and optional size to
/v1/images/generations. - Editing sends a prompt and ordered image files to
/v1/images/edits. - Prompt enhancement runs by default for text-to-image and always for edits; the revised prompt comes back in the response.
Three routes through one model
Text to image: use the returned prompt, not only yours
A text-to-image request sends a prompt and a size policy. MiniMax applies prompt enhancement
by default, which means the string that actually reaches the model is usually longer and
more specific than the one you sent. The response includes revised_prompt for
each image. Keep it. If a result is good, the revised prompt is the reproducible input; if
it is bad, the revised prompt is where the failure can be diagnosed.
curl https://api.minimax.io/v1/images/generations \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3-Image",
"prompt": "A quiet research library carved into a cliff at dusk",
"aspect_ratio": "16:9",
"area": "4K",
"n": 4,
"response_format": "url"
}' Set enhancement to false only when you already have a detailed prompt and need a fixed canvas. In that mode the API requires a width and height, or a fixed aspect ratio, and only roughly the first 4,096 tokens of the prompt take effect. The nominal ceiling is 32,000 characters, but the effective ceiling is shorter once enhancement is off.
MiniMax API guide, read 2026-11-13 Request shown for structure; replace the key and validate against your account's limits
Editing: the upload order is the prompt vocabulary
An edit request can carry one to sixteen reference images. Their order defines
<Picture 1>, <Picture 2> and so on in the prompt. That
sounds like a technicality until you write the instruction. “Replace the cat in Picture 1
with the dog in Picture 2” is only unambiguous if the calls match the upload order.
The body limit is 64 MiB and the image formats are JPG, PNG, WEBP, HEIC and HEIF. Each image may be up to 64 MiB on its own, but the whole request cannot exceed the total. Base64 inflates the payload by roughly a third, so a set of large references should use public URLs or MiniMax file IDs rather than inline data URIs.
Editing always applies prompt enhancement. There is no mask input, no transparent background and no preview-image option. If the workflow needs a strict cutout or an exact local repaint, that is a downstream segmentation or compositing job rather than something this endpoint exposes.
Batches are not all-or-nothing
One request can ask for up to 10 images. With streaming off, the
request returns HTTP 200 as long as at least one image succeeds; a failed item contains only
an error object, and usage.generated_images carries the success
count. That changes the client contract: iterate over the returned data and treat each item
as its own result.
With streaming on, each image arrives as soon as it is complete, in completion order rather
than request order. Use image_index to map it back. A partial failure is an
event, not a transport error. If every image fails, the endpoint returns an error response:
422 for an all-safety failure, 402 for insufficient balance, or 500 for the other cases.
The API is synchronous and non-idempotent. MiniMax's own examples disable SDK retries so a timeout does not quietly generate and charge for a second batch. That is a useful default for any image workflow: retry only after you can identify whether the first request completed.
Which workflow should you build?
Use text-to-image when the output is the subject: concept art, a hero image, a social card, a product scene with no reference. Use editing when the input already contains the identity that must survive: a room and its furniture, a game map and its viewpoint, a character and a new setting. Use a batch when the variants are genuinely independent and the UI can show partial results.
The model is fast enough to invite iteration, but the durable product is the prompt and reference contract around it. Store the original prompt, the revised prompt, the model variant, the size, the seed where available, and the per-image outcome. Without those five fields, a good result is difficult to reproduce and a bad one is difficult to explain.