MiniMax H3 Image Generation | ToAPIs Documentation

POST

/v1/images/generations

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

Use minimax-h3-image to generate images, or pass reference images for editing. The API returns a task id first; fetch results via Image task status. For the model overview and billing notes, see the Chinese model guide.

Authorizations

Authorizationstringheaderrequired

Use a platform access token in the format Authorization: Bearer <token>. Tokens are managed in the console of your site.

Body

The request type is application/json. All model options below are passed at the top level of the request body.

modelstringbodyrequireddefault: minimax-h3-image

Fixed to minimax-h3-image.

promptstringbodyrequired

Text description or editing instruction. Must contain 1-32000 Unicode characters after trimming whitespace, and cannot be blank only.

nintegerbodydefault: 1

Number of images to generate, range 1-10. The actual number of successful images may be lower than requested.

sizestringbodydefault: auto

When omitted or set to auto, dimensions are determined by resolution and aspect_ratio. You may also pass explicit pixel dimensions such as 1024x1024: width and height must be positive integers, total pixels in the range 655360-20000000, and the aspect ratio must be between 1:3 and 3:1.

Explicit pixel size cannot be combined with resolution or aspect_ratio, even when they are auto. In this mode the 4K default is not applied.

Ratio notation such as 16:9 is also accepted and is equivalent to aspect_ratio. If both fields specify a ratio, they must match. For resolution tiers use resolution; do not write size: "4K".

aspect_ratiostringbodydefault: auto

Supports auto or a width:height ratio such as 1:1, 4:3, 16:9. Each component is an integer from 1-300 and the ratio must be between 1:3 and 3:1. Cannot be combined with explicit pixel size.

resolutionstringbodydefault: 4K

Only uppercase 1K, 2K, 4K. This is a resolution tier, not fixed dimensions; the actual size is reported in the result's size. Cannot be combined with explicit pixel size.

image_urlsstring[]body

Optional list of reference image URLs, up to 16. Use accessible HTTP(S) URLs; credentials embedded in the URL are not allowed, and Base64 or data URIs are not supported. Requests with reference images are processed as edits and always enable prompt enhancement.

URLs must be reachable by the image processing service; they cannot rely on your local network or browser session. An image that opens in your browser does not guarantee a successful edit; always check the final task status and error fields after submission.

output_formatstringbodydefault: jpeg

Supports jpeg, jpg, png, webp. jpg is equivalent to jpeg.

response_formatstringbodydefault: url

Only url is supported. Image URLs are returned in the task result after completion, not in the submit response.

output_compressionintegerbodydefault: 95

Range 0-100. Higher values mean better quality and usually larger files. Applies to JPEG and WebP only; PNG ignores this option.

disable_prompt_enhancedbooleanbodydefault: false

Whether to disable prompt enhancement. Only pure text-to-image requests may set true, and must also provide explicit pixel size or a fixed ratio. Cannot be true when reference images are passed.

aigc_watermarkbooleanbodydefault: false

Whether to add a visible AIGC watermark. This switch does not control identifiers embedded in image file metadata.

webhookstringbody

Optional task completion callback URL, see Task webhooks.

Unsupported parameters

Do not pass area, mask, mask_url, background, quality, partial_images, preview, previous_task_id, image_size, seed, watermark, prompt_extend, or same-named metadata fields. Use resolution for resolution tiers and aigc_watermark for the visible watermark.

stream=true, Base64 input or output, and multipart file upload are not supported. Do not apply parameters or defaults from other image models.

Request example

curl --request POST \
  --url 'https://toapis.com/v1/images/generations' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "A small house by the sea, watercolor illustration style",
    "n": 1,
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "response_format": "url"
  }'

Explicit pixel size example; no resolution or ratio fields are sent:

{
  "model": "minimax-h3-image",
  "prompt": "A small house by the sea, watercolor illustration style",
  "size": "1536x1024",
  "n": 1,
  "output_format": "webp",
  "output_compression": 90
}

Submit response

The following is an example of the response structure:

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "minimax-h3-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1794355200
}

Keep the id and query via GET /v1/images/generations/{task_id}; GET /v1/tasks/{task_id} also works. Poll at intervals of at least 5-10 seconds with jitter, and respect Retry-After on 429. Stopping your local wait does not cancel the task; keep querying the original task instead of resubmitting.

Results and billing

result.data contains only successful images. Each item's image_index is the zero-based index of the original request, not the index in the success array. size, output_format, and revised_prompt describe that image's actual result.
On partial success, result.failed_images contains the failed items' image_index and error; the field is omitted when all succeed. completed does not guarantee every requested image succeeded.
result.request_id is a tracing identifier and cannot replace the task id for queries.
usage.generated_images reports the number of actually successful images and is returned with settled usage. Charges are calculated on actual text-input, image-input, and image-output tokens respectively, not by multiplying request n by a fixed per-image price.
Check the current price via the console quote of your site and account. The final amount is determined by billing when billing.status=settled. Do not treat the pre-authorized amount or missing usage as final spend.

For the full response and settlement fields see Image task status.