MiniMax H3 Image 画像生成 | ToAPIs Documentation

POST

/v1/images/generations

中国本土のユーザー向け： 中国本土のユーザーは https://toapis.cn を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では https://toapis.com を https://toapis.cn に置き換えてください。

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

Authorizationstringヘッダー必須

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.

modelstringボディ必須デフォルト: minimax-h3-image

Fixed to minimax-h3-image.

promptstringボディ必須

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

nintegerボディデフォルト: 1

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

sizestringボディデフォルト: 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_ratiostringボディデフォルト: 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.

resolutionstringボディデフォルト: 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[]ボディ

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_formatstringボディデフォルト: jpeg

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

response_formatstringボディデフォルト: url

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

output_compressionintegerボディデフォルト: 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_enhancedbooleanボディデフォルト: 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_watermarkbooleanボディデフォルト: false

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

webhookstringボディ

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.