Skip to content

MiniMax Image ​

Updated

Request domain (international site): tokenhub-intl.tencentcloudmaas.com (Singapore) Endpoints: POST /v1/wand/minimax-image/generation (text-to-image), POST /v1/wand/minimax-image/edits (image editing) Authentication: Tokenhub API Key / Bearer

MiniMax H3-Image is MiniMax's image generation model family. Requests follow an OpenAI Images–style protocol and support text-to-image, multi-image reference editing (1–16 images), custom size / aspect ratio / area tier, and output format control.

Synchronous Call

This API is synchronous: a single request returns the generated result directly β€” no task submission or polling. The server runs inference asynchronously internally, waits for the final state, then returns the vendor's final image as-is. A single request therefore takes noticeably longer than a typical API call; give your client a generous request timeout.

Prerequisites ​

  1. You have a Tencent Cloud account with the TokenHub service activated.
  2. You have an API Key β€” see Get an API Key.
  3. In the console under Online Inference - Vision Models, search for minimax-image-h3 / minimax-image-h3-highspeed and enable pay-as-you-go for the model.

Replace YOUR_API_KEY in every example below with your own API Key. Authentication uses the request header Authorization: Bearer YOUR_API_KEY.

Basic Information ​

ItemValue
Call pathTokenhub API
Request domain (international site)tokenhub-intl.tencentcloudmaas.com (Singapore)
AuthenticationAuthorization: Bearer <API_KEY>
Result deliverySynchronous; the result is in the response body
Supported tasksText-to-image, image editing (single / multi-image reference)
Reference images1–16 on the edits endpoint
Images per request n1–10
Area tier area1K / 2K / 4K, default 4K
Output formatsjpeg (default) / png / webp

Model List ​

Model namemodel valueCapabilitiesDescription
MiniMax H3-Imageminimax-image-h3Text-to-image / image editing (sync)Standard quality; text-to-image and multi-image reference editing with well-balanced overall results
MiniMax H3-Image Highspeedminimax-image-h3-highspeedText-to-image / image editing (sync)High-speed version with faster generation, suited to latency-sensitive scenarios

Both models share the same endpoints and parameters; only the model value differs.

Text-to-Image ​

1. Description ​

Describe the target image with a text prompt and generate images synchronously. Output size, aspect ratio, output format and more can be specified.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation

2. Input Parameters ​

ParameterRequiredTypeDescription
modelYesstringModel ID: minimax-image-h3 or minimax-image-h3-highspeed. Must not be empty
promptNostringText description of the image, up to 32000 characters (counted as Unicode characters, excluding leading/trailing whitespace). Empty or whitespace-only returns 400. When Prompt enhancement is off (disable_prompt_enhanced=true), the model reads only about the first 4096 tokens; the rest has no effect
nNointegerNumber of images, range [1, 10], default 1
sizeNostringOutput size in ${width}x${height} format (e.g. 2720x1536); width and height are positive integers. Area (width Γ— height) must be within 655,360 – 20,000,000 pixels and the aspect ratio within 1:3 – 3:1 (both inclusive); otherwise 400 is returned β€” no automatic scaling or rounding. When explicit dimensions are given, aspect_ratio and area must not be passed. You may also pass auto to let the model pick the size from the prompt's semantics; if omitted, the model likewise decides
aspect_ratioNostringOutput aspect ratio, default auto. Only allowed when size is omitted or auto. auto: decided by Prompt enhancement based on the reference images and content; X:Y: X and Y are integers from 1 to 300, with the ratio within 1:3 – 3:1 (inclusive), e.g. 16:9, 3:4, 21:9, 3:1
areaNostringOutput area tier: 1K / 2K / 4K, default 4K. Only allowed when size is omitted or auto; passing it with explicit size dimensions returns 400. The target areas are 1024Γ—1024, 2048Γ—2048 and 4096Γ—4096 pixels respectively; the server computes width and height from the aspect ratio β€” e.g. 2K with 16:9 outputs 2720Γ—1536. The actual dimensions of each image are in data[].size of the response
output_formatNostringOutput image format: jpeg / png / webp, default jpeg
response_formatNostringHow images are returned: url (image URL, default) or b64_json (Base64-encoded)
output_compressionNointegerOutput compression quality, range [0, 100], default 95; higher means better quality. Only applies to jpeg / webp
aigc_watermarkNobooleanWhether to overlay a visible AIGC watermark. false: no watermark (default); true: add watermark
disable_prompt_enhancedNobooleanWhether to disable Prompt enhancement (model-side automatic prompt optimization). false: enhancement on (default); true: enhancement off, generate strictly from the original prompt

Pick One of Three Ways to Control Size

  • Exact size: pass only size (e.g. 2720x1536); aspect_ratio / area must not be passed.
  • Ratio + area tier: omit size (or pass auto) and combine aspect_ratio + area; the server computes the dimensions.
  • Fully automatic: pass none of the three and let the model decide based on the prompt.

3. Request Examples ​

Text-to-image (basic)

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-image-h3",
  "prompt": "An orange cat lying on a windowsill basking in the sun, blurred city street in the background, warm tones, photorealistic"
}'

Text-to-image (explicit size and format)

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-image-h3",
  "prompt": "Cyberpunk city at night, neon lights reflected on rain-soaked streets",
  "size": "2720x1536",
  "output_format": "jpeg",
  "response_format": "url"
}'

Text-to-image (Highspeed, explicit aspect ratio)

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-image-h3-highspeed",
  "prompt": "Minimalist product poster, white background, a bottle of perfume in the center",
  "aspect_ratio": "9:16",
  "output_format": "png"
}'

Image Editing ​

1. Description ​

Describe the editing intent with a text prompt, provide one or more reference images, and generate the edited image synchronously. Supports background replacement, style transfer, local modification, multi-image fusion and more.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/edits

2. Input Parameters ​

In addition to the text-to-image parameters, the following is supported:

ParameterRequiredTypeDescription
imagesNoarray[object]Reference image list, 1–16 images. Each element is {"image_url": "..."} or {"url": "..."} (both field names are accepted). Supports public http(s) URLs or data:image/...;base64,.... With multiple images, the model edits by combining all references

All other parameters (model, prompt, n, size, aspect_ratio, area, output_format, etc.) are identical to the text-to-image API β€” see the table above.

3. Request Examples ​

Single-image reference editing

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-image-h3",
  "prompt": "Keep the person unchanged and replace the background with a beach at sunset",
  "images": [
    {"image_url": "https://your-domain/portrait.jpg"}
  ],
  "response_format": "url"
}'

Output Parameters ​

The text-to-image and image editing APIs share the same response structure β€” MiniMax's original response passed through as-is.

ParameterTypeDescription
createdintegerUnix timestamp in seconds
dataarrayResult list. Each element contains url (when response_format=url) or b64_json (when response_format=b64_json), plus the actual dimensions size and the Prompt-enhanced revised_prompt
output_formatstringActual output image format
tokenhub_usageobjectUsage; tokenhub_usage.total_tokens is the number of tokens consumed by this task, used for billing / reconciliation
request_idstringRequest ID; include it when troubleshooting

Response Example ​

Successful response

json
{
  "created": 1794385455,
  "data": [
    {
      "revised_prompt": "The image is a realistic ......",
      "size": "3552x4736",
      "url": "https://xxx.png"
    }
  ],
  "output_format": "jpeg",
  "request_id": "6e44b701-e024-426a-bb00-839553cb58c9",
  "tokenhub_usage": {
    "total_tokens": 44547
  }
}

Error Codes ​

An error code is returned when a request fails. For common error codes, see Appendix: Unified Error Codes. Parameter validation errors (e.g. size out of range, size passed together with aspect_ratio / area, empty prompt) return HTTP 400.

FAQ ​

Yes. Results are temporary URLs β€” download them and save to your own storage as soon as generation succeeds; do not reference the link long-term. To skip the download step, set response_format=b64_json and take the Base64 directly.

2. Standard or Highspeed? ​

Both share identical parameters and endpoints. Choose minimax-image-h3 for the best overall results; choose minimax-image-h3-highspeed for latency-sensitive use (interactive previews, batch drafts).

3. Why does passing both size and aspect_ratio return 400? ​

Explicit size dimensions already fix the output size; aspect_ratio and area only take effect when size is omitted or auto, so passing both is treated as a conflict.

DocumentDescription
Get an API KeyApplying for and managing TokenHub API Keys
MiniMax Video Generation (Tokenhub)Video generation API from the same vendor

Built with VitePress Β· Deployed on Tencent EdgeOne Pages