Skip to main content
POST
Supported models: MiniMax-H3-Image, MiniMax-H3-Image-Highspeed; both take the same parameters and limits. Image edits always apply prompt enhancement; see data[].revised_prompt for the enhanced prompt.
The server waits up to 600 seconds; set the client timeout to at least 600 seconds. This endpoint is not idempotent: once a request is sent, the server finishes generation and charges for successful images even if the client times out or disconnects, and a retry generates and charges again. With the OpenAI SDK, set max_retries=0 to turn off its default automatic retries.

Authorizations

​
Authorization
string
header
required

HTTP: Bearer Auth

  • Security Scheme Type: http
  • HTTP Authorization Scheme: Bearer API_key, used to verify account information, can be found in Account Management>API Keys.

Body

Two formats are supported: application/json, or multipart/form-data compatible with the OpenAI SDK images.edit.

​
model
enum<string>
required

Model name. Supported values: MiniMax-H3-Image, MiniMax-H3-Image-Highspeed; both take the same parameters and limits

Available options:
MiniMax-H3-Image,
MiniMax-H3-Image-Highspeed
​
prompt
string
required

Text description of the edit, up to 32000 characters (counted as Unicode characters, excluding leading and trailing whitespace); an empty or whitespace-only prompt returns 400.

Maximum string length: 32000
​
images
object[]
required

Reference images, 1 to 16.

Reference image limits (total request body ≤ 64 MiB; Base64-encoded data is about 4/3 of the original file size; if the request body would exceed the limit, use public URLs or mm_file://)

Required array length: 1 - 16 elements
​
n
integer
default:1

Number of images, range [1, 10], default 1.

Required range: 1 <= x <= 10
​
size
string
default:auto

Output image size, default auto; see Output Size. Use one of two forms:

  • WIDTHxHEIGHT: set the width and height directly, e.g. 2720x1536; both are positive integers. The area (width × height) must be between 655,360 and 20,000,000 pixels and the aspect ratio between 1:3 and 3:1, bounds inclusive; otherwise 400 is returned, and the size is never scaled or rounded. In this form, do not set aspect_ratio or area (not even to auto); otherwise 400 is returned
  • auto or omitted: width and height are determined by aspect_ratio (default auto) and area (default 4K); either can be set on its own
​
aspect_ratio
string
default:auto

Output aspect ratio, default auto. Can only be set when size is omitted or auto; setting it while size is WIDTHxHEIGHT returns 400.

  • auto: decided by prompt enhancement based on the reference images and content
  • X:Y: X and Y are integers from 1 to 300 and the ratio is between 1:3 and 3:1 (bounds inclusive), e.g. 16:9, 3:4, 21:9, 3:1
Example:

"16:9"

​
area
enum<string>
default:4K

Output area level, default 4K. Can only be set when size is omitted or auto; setting it while size is WIDTHxHEIGHT returns 400.

1K, 2K and 4K target areas of 1024 × 1024, 2048 × 2048 and 4096 × 4096 pixels. The server calculates width and height from the aspect ratio; for example, 2K with 16:9 outputs 2720 × 1536. See data[].size for each image's actual width and height.

Available options:
1K,
2K,
4K
​
output_format
enum<string>
default:jpeg

Output image format, default jpeg. Available values: png, jpeg, jpg, webp. jpg is equivalent to jpeg; output_format in the response is returned as jpeg.

Available options:
png,
jpeg,
jpg,
webp
​
response_format
enum<string>
default:url

Return format, default url.

  • url: image URL. Download the image and store it yourself; the URL is not guaranteed to remain available
  • b64_json: Base64-encoded image data, not supported with streaming

Total output area (n × width × height) limits for b64_json; exceeding returns 400 (with size = auto, each image counts as its area level, e.g. 4096 × 4096 for 4K):

Available options:
url,
b64_json
​
stream
boolean
default:false

Whether to stream results, default false. When enabled, the response is text/event-stream (SSE), and only response_format = url is supported:

  • One event is pushed as each image finishes: image_edit.partial_succeeded on success, image_edit.partial_failed on failure. Events are pushed in completion order; use image_index to match images
  • image_edit.completed is pushed after all images finish, with usage and request_id
  • After the response headers are sent, an error event is pushed if all images fail or the request fails before generation is submitted
  • Errors before the response headers are sent (invalid parameters, authentication, rate limiting, insufficient balance, etc.) are returned as regular HTTP errors, the same as non-streaming calls; check the HTTP status code before parsing SSE

See Streaming Events for event structures.

​
output_compression
integer
default:95

Compression quality, range [0, 100], default 95; higher values give better quality and larger files. Only applies to jpeg / webp and is ignored for png; values outside the range return 400.

Required range: 0 <= x <= 100

Response

Returns application/json when stream is false (default). When stream is true, returns text/event-stream (SSE); the data of each event is JSON, defined under the text/event-stream response. See Streaming Events for event details and a full example.

​
created
integer

Time the response was generated, as a Unix timestamp in seconds.

​
data
object[]

Images, always n items in image order (matching image_index in streaming events). Successful items contain url (or b64_json), size and revised_prompt; failed items, including those withheld by the content safety check, contain only error.

If at least one image succeeds, the HTTP status is 200, so check data[].error for every item; if all images fail, a 402, 422 or 500 error response is returned. Only successful images are charged.

​
output_format
enum<string>

Format of the generated images.

Available options:
png,
jpeg,
webp
​
usage
object

Token usage of this request, counting successful images only; billing is based on it. total_tokens is the sum of input_tokens and output_tokens.

​
request_id
string

Request ID (the trace ID). Provide it when reporting an issue.