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
  }'

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())

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());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "Internal server error. Try again later.",
    "type": "server_error"
  }
}

MiniMax-H3-Image

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)

POST

images

generations

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
  }'

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())

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());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "Internal server error. Try again later.",
    "type": "server_error"
  }
}

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
  }'

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())

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());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": 500,
    "message": "Internal server error. Try again later.",
    "type": "server_error"
  }
}

Authentication

string

required

All endpoints use Bearer Token authentication. Get your key from the API Key page.

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

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.

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

string

required

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

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.

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.

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.

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.

When size uses exact pixels, you cannot pass resolution; otherwise the request returns 400.

integer

default:"1"

Number of images to generate, from 1 to 10.

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.

string

default:"jpeg"

Output file format.

jpeg (default; jpg is also accepted)
png
webp

integer

default:"95"

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

boolean

default:"false"

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

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

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

integer

Response status code; 200 when submission succeeds.

array

Submission response data.

Show Array item

string

Initially submitted.

string

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

Submission response

A successful submission immediately returns an asynchronous task ID:

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

Query task results

Call the task status endpoint with the task_id from the submission response:

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

{
  "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)

{
  "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)

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

Exact pixels + PNG

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

Reference image editing

{
  "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

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

Overview

Models

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

MiniMax-H3-Image Image Generation

Authentication

Model overview

Request parameters

Size rules

Tier + aspect ratio

Exact pixels

Reference image requirements

Disable prompt enhancement

Response

Submission response

Query task results

Successful task

Usage examples

Text to image (default 4K)

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

Exact pixels + PNG

Reference image editing

Disable prompt enhancement

​Authentication

​Model overview

​Request parameters

​Size rules

​Tier + aspect ratio

​Exact pixels

​Reference image requirements

​Disable prompt enhancement

​Response

​Submission response

​Query task results

​Successful task

​Usage examples

​Text to image (default 4K)

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

​Exact pixels + PNG

​Reference image editing

​Disable prompt enhancement

Authentication

Model overview

Request parameters

Size rules

Tier + aspect ratio

Exact pixels

Reference image requirements

Disable prompt enhancement

Response

Submission response

Query task results

Successful task

Usage examples

Text to image (default 4K)

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

Exact pixels + PNG

Reference image editing

Disable prompt enhancement