> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax-H3-Image Image Generation

>  - Uses the minimax-h3-image standard model, which excels at photorealistic photography, posters, product images, and images with text
- Asynchronous processing returns a task_id for status queries
- Supports text-to-image and image editing with up to 16 reference images
- Generates up to 10 images per request, with built-in prompt enhancement (can be disabled)
- Supports 1K / 2K / 4K tiers with aspect ratios, or exact pixel dimensions (up to 20 megapixels) 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "A seaside cafe at dusk, photorealistic, warm tones",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3-image",
        "prompt": "A seaside cafe at dusk, photorealistic, warm tones",
        "size": "16:9",
        "resolution": "2K",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "minimax-h3-image",
      prompt: "A seaside cafe at dusk, photorealistic, warm tones",
      size: "16:9",
      resolution: "2K",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "Internal server error. Try again later.",
    "type": "server_error"
  }
}
```

## Authentication

**Authorization** `string` *required*

All endpoints use Bearer Token authentication. Get your key from the [API Key page](https://apimart.ai/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Model overview

| Model | Features | Recommended use |
| - | - | - |
| `minimax-h3-image` | Standard version with a lower unit price | Batch generation, photorealistic photography, posters, product images, and images with text |
| `minimax-h3-image-highspeed` | High-speed version with faster generation; image input / output unit prices are 2 times those of the standard version | Latency-sensitive scenarios. See [MiniMax-H3-Image-Highspeed](https://docs.apimart.ai/en/api-reference/images/minimax-h3-image-highspeed/generation.md) |

By default, MiniMax H3 Image automatically expands your prompt into a detailed scene description before generating the image. The expanded text is available in `revised_prompt` in the query result. To generate strictly from your original text, see [Disable prompt enhancement](#disable-prompt-enhancement).

> [!WARNING]
>
> If `resolution` is omitted, output defaults to **4K** (about 16 megapixels), which costs about 3 times as much as 1K / 2K. If you don't need 4K, pass `"resolution": "2K"` explicitly.

## Request parameters

**model** `string` *required*

Image generation model name. Must be `minimax-h3-image`.

**prompt** `string` *required*

Text description for image generation or editing.

The prompt supports Chinese and English. After trimming leading and trailing whitespace, it must be `1` – `32,000` characters long.

**image\_urls** `string[]`

Array of reference images, up to `16`. Passing this field automatically switches to editing mode.

Each item can be a publicly accessible `http(s)://` direct link or inline Base64 in `data:image/png;base64,...` format (the platform converts it to a link before sending it to the model).

See [Reference image requirements](#reference-image-requirements).

**size** `string` (default: auto)

Aspect ratio or exact pixel dimensions of the output image.

Supported values:

* `auto`: the model chooses composition and aspect ratio based on the prompt
* Aspect ratio: `X:Y` format, where X and Y are integers from `1` to `300` and the ratio is between `1:3` and `3:1` (inclusive), such as `1:1`, `4:3`, `16:9`, `9:16`, `3:1`
* Exact pixels: `WIDTHxHEIGHT`, such as `2048x1152` (`X`, `×`, and `*` are also accepted as separators)

See [Size rules](#size-rules).

**resolution** `string` (default: 4K)

Resolution tier. Combined with the aspect ratio, it determines the actual output pixels.

* `1K`: about 1 megapixel
* `2K`: about 4.2 megapixels
* `4K` (default): about 16 megapixels

Lowercase values are also accepted.

> [!WARNING]
>
> When `size` uses exact pixels, you **cannot** pass `resolution`; otherwise the request returns 400.

**n** `integer` (default: 1)

Number of images to generate, from `1` to `10`.

**prompt\_optimizer** `boolean` (default: true)

Whether to automatically expand the prompt.

Setting it to `false` only works for text-to-image and requires an explicit size. See [Disable prompt enhancement](#disable-prompt-enhancement).

**output\_format** `string` (default: jpeg)

Output file format.

* `jpeg` (default; `jpg` is also accepted)
* `png`
* `webp`

**output\_compression** `integer` (default: 95)

Compression quality, from `0` to `100`. Has no effect on `png`.

**watermark** `boolean` (default: false)

Whether to add a visible AI-generated watermark to the image. Does not affect the implicit marker in the image metadata.

> [!NOTE]
>
> The following parameters are not supported and are ignored if passed: `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`.
>
> Results are always returned as URLs. Passing `response_format: "b64_json"` returns 400.

## Size rules

| What you want | What to pass |
| - | - |
| Default (4K, model-chosen aspect ratio) | Omit size parameters |
| Tier + aspect ratio | `size: "16:9"`, `resolution: "2K"` |
| Control only the tier, let the model choose the ratio | `resolution: "1K"` (omit `size` or pass `auto`) |
| Exact pixel control | `size: "2048x1152"` (**do not also pass `resolution`**) |

### Tier + aspect ratio

The tier determines the total area, and the aspect ratio determines the shape:

| Tier | Target area | Measured output example |
| - | - | - |
| `1K` | About 1024×1024 (about 1 megapixel) | Model-chosen ratio → 1184×880 |
| `2K` | About 2048×2048 (about 4.2 megapixels) | `1:1` → 2048×2048 |
| `4K` (default) | About 4096×4096 (about 16 megapixels) | Model-chosen ratio → 3552×4736 |

The model rounds the actual output pixels based on the ratio and tier; refer to the returned result. For exact dimensions, use the pixel format.

### Exact pixels

When using `size: "WIDTHxHEIGHT"`, the following constraints apply:

| Constraint | Value |
| - | - |
| Total pixels (width × height) | `655,360` – `20,000,000` |
| Aspect ratio | `1:3` – `3:1` |
| With `resolution` | Cannot be passed together |

* ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000`
* ❌ `512x512` (area too small), `4000x1000` (ratio exceeds 3:1), `5000x5000` (exceeds 20 megapixels)

## Reference image requirements

| Item | Requirement |
| - | - |
| Count | Up to 16 images |
| Format | JPG / JPEG / PNG / WebP / HEIC / HEIF (GIF not supported) |
| File size | Up to 64 MB per image |
| Dimensions | Each side 128 – 8192 pixels; long side ÷ short side ≤ 4 |

> [!WARNING]
>
> When using URLs, make sure the links are **publicly accessible**. If a link cannot be reached, the task fails during generation (`status` is `failed`, and the charge is fully refunded).
>
> Prompt enhancement is always on in editing mode and cannot be disabled.

## Disable prompt enhancement

By default, the model expands the prompt before generating the image. To generate strictly from your original text, pass `"prompt_optimizer": false`, provided that:

* It is used only for **text-to-image**; requests with `image_urls` return 400
* An **explicit size** is specified: `size` must be an aspect ratio (such as `1:1`) or pixels (such as `1024x1024`), not `auto` or omitted

When disabled, the model reads only about the first 4096 tokens of the prompt.

## Response

**code** `integer`

Response status code; 200 when submission succeeds.

**data** `array`

Submission response data.

**Array item**

**status** `string`

Initially `submitted`.

**task\_id** `string`

Unique task ID used to query task status and generation results.

## Submission response

A successful submission immediately returns an asynchronous task ID:

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## Query task results

Call the [task status endpoint](https://docs.apimart.ai/en/api-reference/tasks/status.md) with the `task_id` from the submission response:

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

In testing, a single 1K / 2K image takes about 10 – 20 seconds, 4K about 20 seconds, and reference image editing about 20 seconds. Poll every 3 – 5 seconds until the status becomes `completed` or `failed`. A single task can run for up to 600 seconds; set your client polling timeout to 10 minutes.

### Successful task

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "created": 1794450409,
    "completed": 1794450428,
    "actual_time": 19,
    "estimated_time": 60,
    "cost": 0.0493,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example_0.jpeg",
            "https://upload.apimart.ai/f/image/example_1.jpeg"
          ],
          "expires_at": 1794536828,
          "revised_prompt": "The image is a realistic, close-up still life photograph of ...",
          "revised_prompts": [
            "The image is a realistic ...",
            "The image is a professional ..."
          ]
        }
      ]
    }
  }
}
```

Image URLs are in `data.result.images[0].url[]`, with all `n` images in this single array. Download and store them before `expires_at`. If the task fails, `status` is `failed`, the reason is in `error.message`, and the charge is automatically refunded in full.

## Usage examples

### Text to image (default 4K)

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones"
}
```

### Text to image (1K + aspect ratio, 4 images)

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "Minimalist headphone product shot, white background, soft shadows",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### Exact pixels + PNG

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "City night poster, neon lights, cyberpunk style, title text NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### Reference image editing

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "Dress the person in the first image in the jacket from the second image, keeping the background unchanged",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### Disable prompt enhancement

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "a red apple on a wooden table, top view",
  "size": "1:1",
  "resolution": "1K",
  "prompt_optimizer": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.