MiniMax H3 Image

Generate or edit an image from text and up to 16 reference images, at 1K, 2K or 4K or at an exact pixel size, billed by the tokens each render uses.

• Asynchronous: the create call returns a task ID in a moment; the image arrives when the task succeeds.
• One image per task. To get several images, create several tasks.
• Text to image, or edit and combine up to 16 reference images given as public HTTPS links.
• Choose the frame with resolution and aspect_ratio, or with one exact size such as 2720x1536. Never both. aspect_ratio defaults to auto, which lets the model choose the frame from the prompt and any images.
• Billed by tokens: text input (the prompt, including MiniMax’s prompt enhancement), reference-image input and image output, each at its own per-1M-token rate. The per-image prices below are estimates. The default resolution is 4K; 1K and 2K use the same output tokens and so cost the same.
• The result is a png (the default), jpeg or webp file, chosen with output_format. A failed task costs nothing.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

Both MiniMax H3 Image models use this endpoint and take the same fields. The values below come straight from the gateway contract.

Endpoint and authentication

POST https://api.beatapi.io/v1/images/tasks

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

"size": "2720x1536"

"output_format": "webp"

The gateway also checks these combinations before creating the task:

• size is WIDTHxHEIGHT and replaces resolution and aspect_ratio: 655,360-20,000,000 pixels in total, at most 3:1; it is rendered exactly, never rounded
• billed per token at the listed rates for the tokens each render uses (text input including prompt enhancement, reference images, image output); the listed per-image prices are estimates; 1K and 2K use the same output tokens
• aspect_ratio auto lets the model choose the frame from the prompt and any images

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• Reference images: PNG, JPEG or WebP, recognised from the file content; at most 50 MB each (decimal megabytes; checked when the host states the size); 1 to 16 links. GIF, HEIC and SVG are refused.
• No pixel or aspect-ratio limit is checked on the reference images themselves.
• If a host does not answer in time, the link is not refused at create. The gateway fetches it again when the task is dispatched, and a link that still cannot be fetched fails the task, which is refunded.
• Have a local file? Upload it with POST /v1/files and pass the returned data.url.

Choose the frame: resolution and aspect_ratio, or size

There are two ways to say how big and how wide the image is, and they exclude each other:

• Tier and ratio. Send resolution (1K, 2K or 4K) and, if you want a shape, aspect_ratio. Leave both out and you get 4K and auto: the model chooses the frame.
• Exact size. Send size alone, for example 2720x1536: 655,360 to 20,000,000 pixels, at most 3:1, rendered exactly.

Sending size with resolution or with aspect_ratio is refused with "size" already fixes the output; do not send "resolution" with it (or "aspect_ratio"). The check applies even when the other field holds its default value.

What the estimate assumes

The per-image prices in the table below are estimates. Each one assumes 3,000 text tokens (the prompt and MiniMax’s prompt enhancement) and the output tokens of the tier, and no reference images. What you are charged is settled to the tokens the render actually used.

Fields this model does not accept

The image endpoint knows a few fields that other image models use. Sending one of them here is refused instead of being ignored, so you never pay for a setting that had no effect:

• background, quality, seed, enhance_prompt → field "background" is not supported by model minimax-h3-image (with the field you sent and the model you called).
• Any other unknown field, such as n or moderation → unknown field: n. There is no n: one task makes one image.

Request examples

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

Text to image

A 2K landscape image from a prompt, with a tier and a ratio.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

Let the model choose the frame

Only a prompt: resolution is 4K and aspect_ratio is auto, so the model chooses the frame.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "A tall, narrow travel poster of a mountain railway at dawn, bold flat colours"
}'

Edit one image

Change the background and keep the product.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'

Combine several images

Name each reference in the prompt by its position.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

Exact size

A 2720x1536 frame as WebP. size stands alone: no resolution, no aspect_ratio.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "2720x1536",
  "output_format": "webp"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.015725,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.015725
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.015725,
      "credits_settled": 0.015725,
      "credits_refunded": 0,
      "credits_charged": 0.015725
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.015725,
      "credits_settled": 0,
      "credits_refunded": 0.015725,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "minimax-h3-image",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• Billed by tokens at the per-1M-token rates in the table below: text input (the prompt, including MiniMax’s prompt enhancement), image input (the reference images in images) and image output. The model counts the tokens; the resolution or size, the prompt and the reference images all change the count.
• The per-image prices are estimates for one render of each resolution without reference images, at 3,000 text tokens and the output tokens in the table above. 1K and 2K use the same output tokens and so have the same estimate.
• When the task is created, the estimate for its tier is reserved from your balance, and from the key’s quota if it has one. When it succeeds, the charge is settled to the tokens the render actually used, so the final data.usage can differ from the reservation. A request refused before a task exists costs nothing.
• A failed task is refunded in full.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}