MiniMax Image API: Image-01, Reference Images, and Seeds

The MiniMax Image API exposes one synchronous endpoint for two documented Image-01 workflows: create an image from a text prompt, or generate a new scene while preserving the key characteristics of a person supplied in one reference image. This guide covers the exact payload fields, sizes, seeds, response formats, temporary URLs, and production checks.

Independent-site notice: MiniMax-AI.chat is an independent educational website. It is not MiniMax or an official MiniMax Open Platform property. API keys, billing, model access, rate limits, and generated images are provided by MiniMax through its official developer platform.

Last verified: July 18, 2026. The model ID, endpoint schema, dimensions, output expiry, price, and rate limit below were checked against the official sources linked at the end of this page. Verify them again before deployment.

Verification scope: The payloads were checked against the documented schema, and the Node.js and Python examples passed syntax validation. No billable Image-01 request was run for this article, so it does not present invented output images or quality scores.

Requires MiniMax Open Platform API. The text-only MiniMax-AI.chat demo does not submit image-generation calls, accept reference-image uploads, consume a MiniMax API balance, or expose Image-01. Never place a MiniMax API key in browser JavaScript or a WordPress block.

How the MiniMax Image API works

Send a server-side JSON request to POST https://api.minimax.io/v1/image_generation.
Use model: "image-01" and a prompt of no more than 1,500 characters.
For subject-reference image-to-image generation, add one subject_reference entry containing a clear character image.
Select a preset aspect_ratio, or omit it and provide both width and height.
Choose response_format: "url" or response_format: "base64".
Save every successful image immediately. URL output expires after 24 hours.

The image endpoint returns the generated result on the same HTTP request. It is not the asynchronous video workflow: there is no image task_id, polling loop, file_id, or /v1/files/retrieve step in the Image-01 generation references.

Why this guide says “outputs” instead of “files”

The proposed page title ended with “Seeds, and Files,” but that wording suggests that Image-01 stores generated images in MiniMax’s separate File Management API. The documented image response instead provides temporary URLs or Base64 strings. The corrected title describes the real lifecycle and prevents developers from adding an unsupported file-retrieval step.

Text-to-image versus subject-reference image-to-image

Workflow	Required input	Documented model used here	What it is designed to do
Text-to-image	`prompt`	`image-01`	Create images directly from a text description.
Subject-reference image-to-image	`prompt` plus one `subject_reference`	`image-01`	Generate a new image that preserves key characteristics of the clear person or character in the reference.

“Image-to-image” is narrower here than a general image editor. The official request uses type: "character" and image_file inside subject_reference. The checked schema does not document a mask, inpainting region, denoising strength, arbitrary style-image field, or pixel-level edit instruction. Do not promise those controls.

For a capability overview and visual examples, use the MiniMax Image-01 model page. For shared authentication and request conventions, start with the MiniMax API overview. This guide focuses on image integration so it supports the model page without duplicating its search intent.

Image-01 request parameters and limits

Field	Documented rule	Common mistake
`model`	Required; `image-01` for the workflows in this guide.	Changing capitalization or inventing `MiniMax-Image-01`.
`prompt`	Required; maximum 1,500 characters.	Sending a 2,000-character video prompt to the image endpoint.
`subject_reference`	Subject reference for image-to-image. The official guide supports one reference image per request.	Sending a gallery of references or treating it as a mask array.
`aspect_ratio`	Defaults to `1:1`; eight presets are documented.	Providing custom dimensions and expecting them to override an included aspect ratio.
`width` / `height`	Both are required together; each must be 512–2,048 pixels and divisible by 8. Effective for `image-01`.	Sending only one dimension or a value not divisible by 8.
`response_format`	`url` or `base64`; default `url`. URLs expire after 24 hours.	Saving the URL as though it were permanent.
`seed`	An integer seed. The reference describes the same seed and parameters as reproducible.	Changing the prompt, dimensions, optimizer, or model and attributing the difference only to the seed.
`n`	1–9 images; default 1.	Budgeting for one image while requesting nine.
`prompt_optimizer`	Boolean; default `false`.	Assuming prompt rewriting is enabled without setting it.

Supported aspect ratios and pixel dimensions

Aspect ratio	Documented output size	Typical orientation
`1:1`	1024 × 1024	Square
`16:9`	1280 × 720	Landscape
`4:3`	1152 × 864	Landscape
`3:2`	1248 × 832	Landscape
`2:3`	832 × 1248	Portrait
`3:4`	864 × 1152	Portrait
`9:16`	720 × 1280	Vertical
`21:9`	1344 × 576	Wide landscape

If you need a custom size, omit aspect_ratio and send both dimensions. If you send all three fields, aspect_ratio takes priority. For example, width: 1200 and height: 800 are valid because both are within range and divisible by 8.

Node.js: generate and download Image-01 URLs

This server-side example requests two 16:9 images, checks both HTTP and MiniMax application errors, reads partial-success metadata, and copies each temporary URL to local storage.

import { writeFile } from "node:fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;
const ENDPOINT = "https://api.minimax.io/v1/image_generation";

if (!API_KEY) {
  throw new Error("Set MINIMAX_API_KEY in the server environment.");
}

const response = await fetch(ENDPOINT, {
  method: "POST",
  headers: {
    Authorization: "Bearer " + API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "image-01",
    prompt:
      "Editorial photograph of a small solar-powered research station on a " +
      "rocky coast, overcast daylight, restrained colors, realistic materials, " +
      "wide composition, no text or logos",
    aspect_ratio: "16:9",
    response_format: "url",
    seed: 80421,
    n: 2,
    prompt_optimizer: false
  })
});

const raw = await response.text();
let result;

try {
  result = raw ? JSON.parse(raw) : {};
} catch {
  throw new Error("MiniMax returned non-JSON data (HTTP " + response.status + ").");
}

if (!response.ok) {
  throw new Error("MiniMax HTTP " + response.status + ": " + raw);
}

const code = result?.base_resp?.status_code;
if (typeof code === "number" && code !== 0) {
  const message = result?.base_resp?.status_msg || "Unknown MiniMax error";
  throw new Error("MiniMax error " + code + ": " + message);
}

const urls = result?.data?.image_urls;
if (!Array.isArray(urls) || urls.length === 0) {
  throw new Error("The response did not contain image_urls.");
}

const extensionFor = (contentType) => {
  if (contentType.includes("png")) return "png";
  if (contentType.includes("webp")) return "webp";
  if (contentType.includes("jpeg") || contentType.includes("jpg")) return "jpg";
  return "img";
};

for (const [index, imageUrl] of urls.entries()) {
  const parsed = new URL(imageUrl);
  if (parsed.protocol !== "https:") {
    throw new Error("Refusing a non-HTTPS image URL.");
  }

  const download = await fetch(parsed);
  if (!download.ok) {
    throw new Error("Image download failed with HTTP " + download.status + ".");
  }

  const contentType = download.headers.get("content-type") || "";
  const extension = extensionFor(contentType);
  const filename = "minimax-image-" + (index + 1) + "." + extension;

  await writeFile(filename, Buffer.from(await download.arrayBuffer()));
  console.log("Saved " + filename);
}

console.log({
  traceId: result.id,
  successCount: Number(result?.metadata?.success_count ?? urls.length),
  failedCount: Number(result?.metadata?.failed_count ?? 0)
});

For object storage, replace writeFile with your storage client’s upload call. Preserve the content type and set your own access policy. Generated images should not become public merely because the API returned an accessible download URL.

Python: request Base64 and save the images

import base64
import os
import requests

api_key = os.environ.get("MINIMAX_API_KEY")
if not api_key:
    raise RuntimeError("Set MINIMAX_API_KEY in the server environment.")

response = requests.post(
    "https://api.minimax.io/v1/image_generation",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "image-01",
        "prompt": (
            "Minimal product photograph of a matte ceramic desk lamp, white "
            "background, soft side light, accurate shadow, no text or logo"
        ),
        "width": 1200,
        "height": 800,
        "response_format": "base64",
        "seed": 31107,
        "n": 2,
        "prompt_optimizer": False,
    },
    timeout=300,
)

response.raise_for_status()
result = response.json()

code = result.get("base_resp", {}).get("status_code")
if code not in (None, 0):
    message = result.get("base_resp", {}).get("status_msg", "Unknown error")
    raise RuntimeError(f"MiniMax error {code}: {message}")

images = result.get("data", {}).get("image_base64", [])
if not images:
    raise RuntimeError("The response did not contain image_base64.")

for index, encoded in enumerate(images, start=1):
    with open(f"minimax-image-{index}.jpeg", "wb") as output:
        output.write(base64.b64decode(encoded, validate=True))

print(
    {
        "trace_id": result.get("id"),
        "saved": len(images),
        "failed": int(result.get("metadata", {}).get("failed_count", "0")),
    }
)

Base64 avoids a second download and the 24-hour URL deadline, but it makes the JSON response much larger. URL output is often easier for larger batches if your server downloads and persists each file immediately.

Subject-reference image-to-image payload

{
  "model": "image-01",
  "prompt": "The referenced character reading beside a library window, natural daylight, realistic editorial photography",
  "subject_reference": [
    {
      "type": "character",
      "image_file": "https://assets.example.com/authorized-character-reference.jpg"
    }
  ],
  "aspect_ratio": "16:9",
  "response_format": "url",
  "seed": 42618,
  "n": 2,
  "prompt_optimizer": false
}

The official guide says only a single reference image is supported per request and demonstrates an online URL containing a clear subject. Use a URL that MiniMax can fetch without a login, cookie, expiring browser session, or blocked private network. Do not use a reference person unless you have a lawful basis and the necessary consent for the intended generation and publication.

The Image-to-Image reference displays image-01-live in its exposed enum even though the descriptive model line names image-01. This page deliberately uses image-01, the model consistently demonstrated by the official guide and examples. Do not switch model IDs based on the enum alone; verify a dedicated reference and your account access first.

How to use seeds for controlled comparisons

Fix the model ID, prompt, dimensions or aspect ratio, n, reference image, response format, and prompt_optimizer setting.
Choose and store one integer seed.
Generate the baseline and keep the response trace ID.
Change only one prompt or layout variable for the next request.
Compare composition, subject consistency, anatomy, text artifacts, brand accuracy, and safety with the same rubric.

The API reference describes the same seed and parameters as reproducible. A seed is not a promise that different prompts will retain the same composition, that a person will be perfectly identical, or that service updates can be ignored. For evaluation work, keep prompt_optimizer: false so an undocumented prompt rewrite does not become another variable.

Response fields and image lifecycle

Field	Meaning	What to do
`data.image_urls`	Generated URLs when URL format is requested.	Download within 24 hours and replace the temporary URL in your application record.
`data.image_base64`	Base64-encoded images when Base64 format is requested.	Decode immediately; do not log the full payload.
`metadata.success_count`	Count of successful images, represented as a string in the official example.	Compare with requested `n`.
`metadata.failed_count`	Count of failed images, represented as a string in the official example.	Do not assume the entire request failed or succeeded as one unit.
`id`	Trace ID for request tracking.	Save it with your internal job record and support logs.
`base_resp`	MiniMax application status and message.	Check it even when the HTTP status is 200.

Image-01 price and rate limit

The official pay-as-you-go table lists image-01 at $0.0035 per image. The official rate table lists Image Generation with image-01 at 10 requests per minute. These measure different things: n controls images requested in one call, while RPM controls calls.

At the verified price, requesting nine images represents a planned generation amount of $0.0315 before any account-specific terms or billing treatment. Do not state that failed images are free unless MiniMax’s billing record or account terms explicitly confirm it. Use the MiniMax pricing page for a dated cross-product view.

Security, privacy, and publication checks

Proxy the request through your server; never expose MINIMAX_API_KEY in a public client.
Validate prompt length, n, aspect ratio, dimensions, seed type, and response format before spending balance.
Accept reference URLs only from an approved asset system. Block private-network hosts and untrusted redirects in any user-supplied URL pipeline.
Do not place private, biometric, confidential, or customer images in a request without an approved purpose, retention rule, and lawful basis.
Record consent and license evidence for identifiable people, logos, artwork, products, and other protected material.
Check both HTTP status and base_resp; preserve the trace ID and partial-success counts.
Moderate generated images before making them public. Check identity, anatomy, text, trademarks, misleading context, and prohibited content.
Review the site security guide, privacy policy, and MiniMax API error guide when designing a user-facing integration.

MiniMax Image API FAQ

Does Image-01 use asynchronous tasks or polling?

No task workflow is documented for this endpoint. The generated URLs or Base64 strings return in the response to POST /v1/image_generation.

How many images can one MiniMax Image API request generate?

The n field accepts 1 through 9 and defaults to 1. Inspect success_count and failed_count instead of assuming that every requested image succeeded.

Can Image-01 use more than one reference image?

The official guide says only one reference image is supported per request. Its example uses a clear character image supplied through subject_reference.

Does the Image API support masks or inpainting?

The checked Image-01 request schema does not document a mask or inpainting field. Its image-to-image route is framed as character subject reference, not a general region-editing API.

Are generated image URLs permanent?

No. The official endpoint references say URL output expires after 24 hours. Download it promptly or request Base64 and decode the response.

Does the same seed reproduce an image?

The reference describes the same seed and parameters as reproducible. Keep every other field fixed and store the exact prompt, model, size, reference image, optimizer setting, and trace ID with the test.

Official sources followed

Scope: This page documents Image-01 API implementation. It does not claim that the MiniMax-AI.chat demo generates images, and it does not replace the dedicated model overview, official account documentation, or legal advice.