MiniMax Image Generation API: Complete Developer Guide 2025

The MiniMax Image Generation API is one of the cleanest multimodal APIs you can ship against in 2025. Predictable JSON, sane defaults, a useful parameter set, and a pricing model that doesn't punish you for iterating. This is the documentation I wish I'd had on day one — everything you need to go from curl hello-world to a production pipeline, in one place.

We'll cover authentication, endpoints, request and response shapes, the full parameter set (size, steps, guidance, negative prompts, seed), code in Python and JavaScript, error handling, rate limits, and the production patterns that actually work.

API overview: what it is and who it's for

The MiniMax Image Generation API is a REST endpoint that turns a text prompt (and optional reference image) into a generated image, returned as a URL plus metadata. It runs on the same multimodal models that power the Studio UI, so anything you can do in the dashboard, you can do programmatically. The API is part of the broader MiniMax token plan stack — you buy tokens, every API call spends them.

It's worth being clear about who this is for. The API is not the cheapest path to one-off generations — the Studio UI is faster for that. The API is the right choice when you need any of these:

• Generate images at scale (hundreds or thousands per day).
• Embed generation inside a product, app, or workflow.
• Build automation — A/B tests, content pipelines, programmatic creative.
• Use generation as a backend for a CMS, marketing tool, or design system.
• Integrate with server-side logic: condition generation on user input, analytics, or business rules.

If you haven't set up an account yet, our 10-minute platform quickstart walks you through the first run. Then come back here for the developer deep dive.

Authentication with API keys

All API calls authenticate with a bearer token in the Authorization header. Generate a key from the Studio dashboard under Settings → API Keys, give it a label, and copy the value at creation time — the full key is shown exactly once.

The recommended approach is to load the key from an environment variable, never hard-code it in source control.

# Local development: a .env file (and add it to .gitignore)
MINIMAX_API_KEY=sk-mx-•••••••••••••••••••••

Security best practices

• Never commit the key. Add .env to .gitignore; use a secrets manager in production.
• Use scoped keys. MiniMax supports read-only and generate-only scopes — grant the minimum needed.
• Rotate regularly. Treat the key like a password. Rotate quarterly, and revoke any old key the moment you replace it.
• Don't expose it client-side. For browser or mobile use, proxy through your own backend. Direct browser calls would leak the key.

Auth failures return 401 Unauthorized with a clear JSON error body, so a misconfigured key is easy to debug. The full error list is later in the article.

Endpoints you'll actually use

The Image Generation API exposes a small, focused set of endpoints. You don't need to learn ten routes — four cover almost every workload.

The base URL is https://api.minimax.io. All endpoints accept and return JSON; non-GET requests need a Content-Type: application/json header alongside Authorization.

Request and response shape

Here's what a clean POST /v1/images/generate looks like, and the response you'll get back.

// Request body
{
  "model": "minimax-image-v2",
  "prompt": "A serene mountain cabin at dawn, soft fog, cinematic lighting",
  "size": "1024x1024",
  "steps": 30,
  "guidance": 7.5,
  "negative_prompt": "blurry, low quality, watermark",
  "seed": 42,
  "num_images": 1
}

// Response body (200 OK)
{
  "id": "img_8f3a2c1d4e",
  "created": 1715990400,
  "model": "minimax-image-v2",
  "data": [
    {
      "url": "https://cdn.minimax.io/...",
      "width": 1024,
      "height": 1024,
      "content_type": "image/jpeg",
      "seed": 42
    }
  ],
  "usage": {
    "tokens": 3,
    "cost_usd": 0.012
  }
}

Three things worth noticing. The model is named explicitly in the request, so you can pin a version and avoid silent output drift on upgrades. The response includes a seed even if you didn't pass one — store it to reproduce any result. And the usage block tells you exactly how many tokens the call cost, which is gold for budgeting pipelines.

Python example

The official Python helper is the cleanest way to call the API, and the underlying requests call is short enough to drop into any script. Here's a complete, production-ready example with retries, error handling, and saving the result locally.

import os
import time
import requests
from pathlib import Path

API_KEY = os.environ["MINIMAX_API_KEY"]
BASE_URL = "https://api.minimax.io/v1"

def generate_image(prompt, size="1024x1024", steps=30, seed=None):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "minimax-image-v2",
        "prompt": prompt,
        "size": size,
        "steps": steps,
        "negative_prompt": "blurry, low quality, watermark",
    }
    if seed is not None:
        payload["seed"] = seed

    for attempt in range(3):
        r = requests.post(f"{BASE_URL}/images/generate",
                          json=payload, headers=headers, timeout=60)
        if r.status_code == 200:
            return r.json()
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", 2)))
            continue
        r.raise_for_status()

    raise RuntimeError("Image generation failed after 3 attempts")

if __name__ == "__main__":
    result = generate_image("A corgi astronaut, studio lighting, 85mm")
    image_url = result["data"][0]["url"]
    Path("out.jpg").write_bytes(requests.get(image_url).content)
    print(f"Saved. Cost: {result['usage']['tokens']} tokens")

JavaScript example

The same flow in modern JavaScript, using fetch with async/await. Drop this into any Node.js service or a serverless function.

import fs from "node:fs/promises";

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

async function generateImage(prompt, opts = {}) {
  const body = {
    model: "minimax-image-v2",
    prompt,
    size: opts.size ?? "1024x1024",
    steps: opts.steps ?? 30,
    guidance: opts.guidance ?? 7.5,
    negative_prompt: opts.negative ?? "blurry, low quality, watermark",
    num_images: opts.n ?? 1,
  };
  if (opts.seed !== undefined) body.seed = opts.seed;

  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(`${BASE_URL}/images/generate`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    if (res.ok) return res.json();
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 2);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const err = await res.json().catch(() => ({}));
    throw new Error(`API ${res.status}: ${err.error?.message ?? "unknown"}`);
  }
  throw new Error("Image generation failed after 3 attempts");
}

const result = await generateImage("A corgi astronaut, studio lighting, 85mm");
const bytes = await fetch(result.data[0].url).then((r) => r.arrayBuffer());
await fs.writeFile("out.jpg", Buffer.from(bytes));
console.log(`Saved. Cost: ${result.usage.tokens} tokens`);

Error handling and status codes

API errors come back as JSON with a stable shape, so a single error handler works for every endpoint.

Every error response uses the same body shape:

{
  "error": {
    "code": "invalid_parameter",
    "message": "size must be one of: 512x512, 1024x1024, 1024x1792, 1792x1024",
    "request_id": "req_4d2a8f9b"
  }
}

The request_id is the right thing to log — support uses it to find your call in the system.

Rate limits by plan

Rate limits scale with your plan. The numbers below are the published limits at time of writing; check the docs for current values when you go live.

A rate limit returns 429 with a Retry-After header in seconds — always honor it. The concurrent-request limit is the one most people forget: fire 50 parallel requests from a script and you'll trip it. Batch sequentially, use a small worker pool, or upgrade to Business for real parallelism.

For a deeper cost breakdown across modalities, the token cost calculator pairs well with this section.

Image parameters: size, steps, guidance, negative prompts

The parameter set is the part of the API you'll spend the most time tuning. A few have non-obvious trade-offs worth knowing.

Size

Supported values: 512x512, 1024x1024, 1024x1792, 1792x1024. Choose the orientation that matches your output channel. Larger images cost more tokens — roughly linearly with pixel count.

Steps

The number of denoising iterations. Default is 30. Lower values (10–20) are faster and cheaper, useful for early iteration. Higher values (40–60) give finer detail for final output. Past 60, returns diminish.

Guidance scale

How strongly the model follows your prompt. Default is 7.5, the sweet spot for most use cases. Lower (4–6) is more creative and loose; higher (10+) follows the prompt literally, sometimes at the cost of natural composition.

Negative prompts

A list of concepts the model should avoid. Negative prompts are one of the highest-leverage parameters — they remove an entire class of failure modes with one line.

Good defaults to keep in your negative_prompt field for most work:

• blurry, out of focus, low quality — base quality floor
• watermark, signature, logo, text — keeps brand noise out
• deformed, disfigured, extra fingers — common anatomy failures
• oversaturated, overprocessed — for natural-looking output

Seed

Pin a seed to make generation reproducible. Same seed, prompt, and model give the same image back — perfect for iterating on a successful result with controlled variations.

Number of images

Set num_images between 1 and 4 to get multiple candidates in a single call. Useful for "pick the best of N" workflows, where you generate four and ship the one closest to the brief.

Reference image (img2img)

Pass a publicly accessible URL of an existing image to condition generation on it. The model uses the reference for composition and style cues, then re-renders. Great for "make this but different" workflows.

For a deeper dive into writing good prompts that pair with these parameters, the MiniMax prompt guide is the canonical companion to this section.

Real-world use cases

The API is the right tool when the Studio UI is the wrong one — usually because of scale, automation, or product integration. Four patterns work well in production:

1. Programmatic ad creative

Generate 50 variants of a hero image in a single batch, varying background, color treatment, and framing. A/B test the lot, ship the winners. Effective cost per image at Pro rates is well under a cent — cheaper than stock, fully original.

2. CMS cover-image generation

When a new article publishes in your CMS, auto-generate a cover image from the title and lede. Most teams wire this in as a background job that posts the result back to the article record. Pair with a small human review step for high-stakes posts.

3. E-commerce variant rendering

Take a single product shot, then generate lifestyle variations — different backgrounds, seasons, or use contexts. The reference_image field is built for this.

4. Customer-facing in-app generation

Embed generation in your app: a user fills in a brief, your backend calls the API, the result renders in your product. This is where guidance and negative_prompt matter most — they keep output quality consistent for non-expert users.

For an honest read on output quality after sustained use, the 30-day honest review is the right follow-up. And for a side-by-side against other multimodal tools, the MiniMax vs OpenAI vs Runway comparison covers it.

Frequently asked questions

What plan do I need to use the MiniMax Image Generation API?

API access is unlocked on the Pro plan ($39/month) and above. The Starter tier is Studio-only. Business and Enterprise tiers add higher rate limits, team seats, and custom volume. See the full token plan breakdown for what's gated at each tier.

How long does a typical image generation request take?

A standard 1024×1024 image at default 30 steps usually completes in 3–8 seconds on Pro. Larger images, higher step counts, or batch requests take longer. Tier affects throughput (queue priority) more than single-image latency.

Can I use the API for commercial projects?

Yes. The Pro plan and above include commercial usage rights. The Starter plan is for personal exploration only — for client work, ad creative, product imagery, or any monetized output, you need Pro or higher.

How do I handle rate limits in production?

Honor the Retry-After header on 429 responses, use exponential backoff for retries, batch where you can, and cache generated URLs since they're CDN-served and idempotent. Pro allows 60 RPM, Business 600, and Enterprise scales to custom limits.

Is the API output deterministic with the same seed?

Yes. When you pass the same seed, prompt, model version, and parameters, the output is reproducible. The seed is the right tool for A/B testing prompt variations and generating controlled variations of a successful image.

Conclusion

The MiniMax Image Generation API is one of the few AI generation endpoints that feels designed for developers first. Small surface area, predictable JSON, a useful parameter set, and pricing that doesn't punish iteration. Fastest path from zero to working: generate an API key, run the Python or JavaScript snippet above, then start building.

Most teams ship their first integration in a day. The patterns that work: pin your model version, store the seed of every output, batch where you can, and use negative prompts to keep quality consistent. If you haven't picked a plan yet, the Pro tier is the right starting point.