MiniMax Image β
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 β
- You have a Tencent Cloud account with the TokenHub service activated.
- You have an API Key β see Get an API Key.
- In the console under Online Inference - Vision Models, search for
minimax-image-h3/minimax-image-h3-highspeedand 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 β
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Request domain (international site) | tokenhub-intl.tencentcloudmaas.com (Singapore) |
| Authentication | Authorization: Bearer <API_KEY> |
| Result delivery | Synchronous; the result is in the response body |
| Supported tasks | Text-to-image, image editing (single / multi-image reference) |
| Reference images | 1β16 on the edits endpoint |
Images per request n | 1β10 |
Area tier area | 1K / 2K / 4K, default 4K |
| Output formats | jpeg (default) / png / webp |
Model List β
| Model name | model value | Capabilities | Description |
|---|---|---|---|
| MiniMax H3-Image | minimax-image-h3 | Text-to-image / image editing (sync) | Standard quality; text-to-image and multi-image reference editing with well-balanced overall results |
| MiniMax H3-Image Highspeed | minimax-image-h3-highspeed | Text-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 β
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Yes | string | Model ID: minimax-image-h3 or minimax-image-h3-highspeed. Must not be empty |
prompt | No | string | Text 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 |
n | No | integer | Number of images, range [1, 10], default 1 |
size | No | string | Output 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_ratio | No | string | Output 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 |
area | No | string | Output 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_format | No | string | Output image format: jpeg / png / webp, default jpeg |
response_format | No | string | How images are returned: url (image URL, default) or b64_json (Base64-encoded) |
output_compression | No | integer | Output compression quality, range [0, 100], default 95; higher means better quality. Only applies to jpeg / webp |
aigc_watermark | No | boolean | Whether to overlay a visible AIGC watermark. false: no watermark (default); true: add watermark |
disable_prompt_enhanced | No | boolean | Whether 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/areamust not be passed. - Ratio + area tier: omit
size(or passauto) and combineaspect_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)
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)
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)
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:
| Parameter | Required | Type | Description |
|---|---|---|---|
images | No | array[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
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.
| Parameter | Type | Description |
|---|---|---|
created | integer | Unix timestamp in seconds |
data | array | Result 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_format | string | Actual output image format |
tokenhub_usage | object | Usage; tokenhub_usage.total_tokens is the number of tokens consumed by this task, used for billing / reconciliation |
request_id | string | Request ID; include it when troubleshooting |
Response Example β
Successful response
{
"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 β
1. Do the generated image links expire? β
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.
Related Documents β
| Document | Description |
|---|---|
| Get an API Key | Applying for and managing TokenHub API Keys |
| MiniMax Video Generation (Tokenhub) | Video generation API from the same vendor |