> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # MiniMax H3 Image > The MiniMax H3 Image API generates an image from a prompt or edits up to 16 reference images. It supports 1K, 2K, and 4K output, ten aspect ratios, and custom sizes up to 20 megapixels. > [!TIP] > > 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`. > 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint. Use `minimax-h3-image` to create posters, product shots, concept art, and other images from a prompt, or to edit and combine up to 16 reference images with the same model ID. MiniMax H3 Image is MiniMax's image generation and editing model, built on the MiniMax H3 architecture and released on November 10, 2026. ## Models * **minimax-h3-image** — Text-to-image when `image_urls` is omitted; image editing with 1 to 16 reference images when `image_urls` is provided ## Features * Text-to-image generation from prompts of up to 5,000 characters. * On-image text rendering for titles, labels, and captions written in quotes in the prompt. * Image editing and multi-reference composition with up to 16 reference images, referenced in the prompt as ``, ``, and so on. * Ten aspect ratios at `1K`, `2K`, or `4K` (up to 6272×2688 at `21:9`), plus custom `WIDTHxHEIGHT` sizes from 655,360 to 20,000,000 pixels. * Prompt expansion that rewrites a short prompt in any language into a detailed description of the whole image. * PNG or JPEG output. ## Input modes * **Text-to-image** — Omit `image_urls`. `size` defaults to `1:1`, and `enable_prompt_expansion` controls whether the prompt is expanded. * **Image editing** — Pass 1 to 16 URLs in `image_urls`. The first URL is ``, the second is ``, and so on; use these tags in the prompt to say which image to change and which images to take content from. `size` defaults to `auto`, which follows the aspect ratio of ``. Image editing requests always expand the prompt. ## Required parameters * `prompt` (string): Description of the image or the requested edit, 1–5,000 characters. Must contain non-whitespace text. Put exact on-image text in quotes and state where it goes. ## Optional parameters * `image_urls` (array of strings): 1 to 16 publicly accessible HTTP(S) reference image URLs (JPEG, PNG, or WEBP, up to 20 MB each, 128 to 8192 pixels per side). Selects image editing mode. Refer to the images in the prompt by their order: `` for the first URL, `` for the second, and so on. * `size` (string): `1:1`, `5:4`, `4:5`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `21:9`, `auto`, or a custom `WIDTHxHEIGHT`. Defaults to `1:1` for text-to-image and `auto` for image editing. `auto` applies to image editing. See [Size](#size). * `resolution` (string): `1K`, `2K`, or `4K`. Default is `2K`. Sets the pixel tier for aspect-ratio sizes and `auto`. A custom `WIDTHxHEIGHT` size sets the exact output pixels. * `enable_prompt_expansion` (boolean): Expand the prompt into a detailed description of the whole image before generating. Default is `true`. Applies to text-to-image requests. Image editing requests always expand the prompt. * `output_format` (string): `png` or `jpeg`. Default is `png`. ## Size Each aspect ratio maps to fixed pixel dimensions at the selected `resolution`: | `size` | `1K` | `2K` | `4K` | | - | - | - | - | | `1:1` | 1024×1024 | 2048×2048 | 4096×4096 | | `5:4` | 1152×928 | 2304×1824 | 4576×3648 | | `4:5` | 928×1152 | 1824×2304 | 3648×4576 | | `4:3` | 1184×896 | 2368×1760 | 4736×3552 | | `3:4` | 896×1184 | 1760×2368 | 3552×4736 | | `3:2` | 1248×832 | 2496×1664 | 5024×3360 | | `2:3` | 832×1248 | 1664×2496 | 3360×5024 | | `16:9` | 1376×768 | 2720×1536 | 5472×3072 | | `9:16` | 768×1376 | 1536×2720 | 3072×5472 | | `21:9` | 1568×672 | 3136×1344 | 6272×2688 | * `auto` (image editing): The output follows the aspect ratio of `` at about the pixel area of the selected tier (1024×1024, 2048×2048, or 4096×4096). Width and height are multiples of 32, and the aspect ratio stays within 1:3 to 3:1. * Custom `WIDTHxHEIGHT`: Integer width and height with total pixels from 655,360 to 20,000,000 and an aspect ratio between 1:3 and 3:1 (for example `2560x1440` or `1920x1080`). The output image has exactly the requested width and height. ## Examples ### Text To Image A 2K 16:9 poster (2720×1536) with a title and subtitle: ```json theme={"dark"} { "model": "minimax-h3-image", "input": { "prompt": "A vintage travel poster for Kyoto, headline text 'KYOTO' in large bold serif letters and subtitle 'City of a Thousand Gates' below, red torii gates receding up a mossy hill, autumn maple leaves, 1960s screen-print style", "size": "16:9", "resolution": "2K" } } ``` ### Multi-Reference Edit Combine several reference images, referring to each one by its position in `image_urls`: ```json theme={"dark"} { "model": "minimax-h3-image", "input": { "prompt": "Place the sofa from and the floor lamp from in the empty living room in . Keep the walls, windows, and daylight of unchanged.", "image_urls": [ "https://example.com/empty-room.png", "https://example.com/sofa.png", "https://example.com/floor-lamp.png" ], "resolution": "2K" } } ``` ### Custom Size An exact 1920×1080 slide background in JPEG, using the prompt as written: ```json theme={"dark"} { "model": "minimax-h3-image", "input": { "prompt": "Minimal presentation background, soft gradient from deep navy to teal, subtle geometric lines in the lower right, large empty area on the left for text", "size": "1920x1080", "enable_prompt_expansion": false, "output_format": "jpeg" } } ``` ## Notes * Each request generates one image. * `image_urls` must be an array, even for one image. * Reference images are numbered by their order in `image_urls`. For best results, give each image a role in the prompt and say what changes and what stays the same. * A request usually finishes in about 10 to 25 seconds. 4K output and edits with several reference images take longer. ## OpenAPI ````yaml api-manual/image-series/minimax-h3-image.json POST /api/generate/submit openapi: 3.0.0 info: title: PoYo AI - MiniMax H3 Image API description: >- The MiniMax H3 Image API generates an image from a prompt or edits up to 16 reference images. It supports 1K, 2K, and 4K output, ten aspect ratios, and custom sizes up to 20 megapixels. version: 1.0.0 servers: - url: https://api.poyo.ai description: Production server security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - MiniMax H3 Image summary: Submit MiniMax H3 Image Task description: >- MiniMax H3 Image text-to-image generation and image editing with up to 16 reference images. operationId: submitMiniMaxH3ImageTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: text-to-image: summary: Text To Image value: model: minimax-h3-image input: prompt: >- A vintage travel poster for Kyoto, headline text 'KYOTO' in large bold serif letters and subtitle 'City of a Thousand Gates' below, red torii gates receding up a mossy hill, autumn maple leaves, 1960s screen-print style size: '16:9' resolution: 2K multi-reference-edit: summary: Multi-Reference Edit value: model: minimax-h3-image input: prompt: >- Place the sofa from and the floor lamp from in the empty living room in . Keep the walls, windows, and daylight of unchanged. image_urls: - https://example.com/empty-room.png - https://example.com/sofa.png - https://example.com/floor-lamp.png resolution: 2K custom-size: summary: Custom Size value: model: minimax-h3-image input: prompt: >- Minimal presentation background, soft gradient from deep navy to teal, subtle geometric lines in the lower right, large empty area on the left for text size: 1920x1080 enable_prompt_expansion: false output_format: jpeg responses: '200': description: Task submitted successfully content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - minimax-h3-image description: >- MiniMax H3 Image model identifier. Omit image_urls for text-to-image; pass 1–16 image_urls for image editing. callback_url: type: string format: uri description: Optional webhook URL for task completion or failure. input: type: object additionalProperties: false required: - prompt description: >- Generate one image. With image_urls, edit or combine the reference images. properties: prompt: type: string minLength: 1 maxLength: 5000 description: >- Prompt describing the image or the requested edit. Must contain non-whitespace text. Put exact on-image text in quotes and state where it goes. In image editing, refer to reference images as , , and so on. image_urls: type: array minItems: 1 maxItems: 16 items: type: string format: uri description: >- Optional 1–16 reference image URLs. Passing this field selects image editing. Must be an array, even for one image. Images are numbered by their order in the array: the first URL is , the second is , and so on; use these tags in the prompt to refer to each image. Each URL must be a publicly accessible HTTP or HTTPS URL pointing to a JPEG, PNG, or WEBP image of up to 20 MB, with each side between 128 and 8192 pixels. example: - https://example.com/empty-room.png - https://example.com/sofa.png size: type: string description: >- Aspect ratio, auto, or custom WIDTHxHEIGHT. Aspect ratios: 1:1, 5:4, 4:5, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9; their pixel size comes from resolution. auto applies to image editing and follows the aspect ratio of at about the pixel area of the selected resolution tier. Custom WIDTHxHEIGHT uses integers with total pixels from 655360 to 20000000 and an aspect ratio between 1:3 and 3:1 (for example 2560x1440); the output has exactly the requested width and height. Defaults to 1:1 for text-to-image and auto for image editing. example: '16:9' resolution: type: string enum: - 1K - 2K - 4K default: 2K description: >- Pixel tier for aspect-ratio sizes and auto. 1K: 1:1 1024x1024, 5:4 1152x928, 4:5 928x1152, 4:3 1184x896, 3:4 896x1184, 3:2 1248x832, 2:3 832x1248, 16:9 1376x768, 9:16 768x1376, 21:9 1568x672. 2K: 1:1 2048x2048, 5:4 2304x1824, 4:5 1824x2304, 4:3 2368x1760, 3:4 1760x2368, 3:2 2496x1664, 2:3 1664x2496, 16:9 2720x1536, 9:16 1536x2720, 21:9 3136x1344. 4K: 1:1 4096x4096, 5:4 4576x3648, 4:5 3648x4576, 4:3 4736x3552, 3:4 3552x4736, 3:2 5024x3360, 2:3 3360x5024, 16:9 5472x3072, 9:16 3072x5472, 21:9 6272x2688. A custom WIDTHxHEIGHT size sets the exact output pixels. enable_prompt_expansion: type: boolean default: true description: >- Expand the prompt into a detailed description of the whole image before generating. Applies to text-to-image requests. Image editing requests always expand the prompt. output_format: type: string enum: - png - jpeg default: png description: Output image format. SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 description: >- Business status code. `200` means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with `code: 400` in the body. - `200`: Success - `400`: Invalid request parameters - `401`: Missing or invalid API key - `402`: Insufficient credits - `403`: Permission denied - `404`: Resource not found - `408`: Request timeout - `429`: Rate limit exceeded - `500`: Internal server error - `502`: Upstream service error - `503`: Service unavailable See [Error Codes](/api-manual/error-codes) for details. enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1794470400-abcd1234 description: Unique task identifier for status tracking status: type: string enum: - not_started - running - finished - failed example: not_started description: >- Task status. Always `not_started` right after submission. Use [Query Task Status](/api-manual/task-management/status) or `callback_url` to get later states. - `not_started`: Queued, waiting to be processed - `running`: Being generated - `finished`: Completed; results are in `files` or `output` - `failed`: Failed; details are in `error_message` created_time: type: string format: date-time example: '2026-11-12T10:30:00' description: ISO 8601 timestamp when the task was created ErrorResponse: type: object required: - code - error properties: code: type: integer example: 400 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- Business status code. `200` means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with `code: 400` in the body. - `200`: Success - `400`: Invalid request parameters - `401`: Missing or invalid API key - `402`: Insufficient credits - `403`: Permission denied - `404`: Resource not found - `408`: Request timeout - `429`: Rate limit exceeded - `500`: Internal server error - `502`: Upstream service error - `503`: Service unavailable See [Error Codes](/api-manual/error-codes) for details. error: type: object required: - message - type properties: message: type: string example: Invalid request parameters type: type: string example: invalid_request_error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- All API endpoints require Bearer Token authentication. Create an API key: sign in to PoYo, open **Dashboard → API Key** at [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and click to create a key. Add it to the request header: ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.