Skip to content
PlaygroundDocsGet API key

Mage API · Image generation

The AI image generation API for every model

Text-to-image, image editing, and consistent characters from 17 models, including Mage's flagship Mango 4, through one key and one balance.

Get an API keyRead the API docs
POST https://api.mage.space/v1/{model}/generate

At a glance

The Mage image generation API is a REST API at https://api.mage.space/v1 that runs 17 text-to-image and image-editing models, including Mango 4, Guava 2 Pro, GPT Image 2.6, Nano Banana 2, Flux 2, and Krea 2. You POST a prompt to /{model}/generate, poll the request, and download the image. Each image is paid in Gems, with no subscription.

  • 17image models
  • $0.009Cheapest default, per image
  • 20Concurrent generations
  • $0Monthly fee

Models

Every image model in the Mage API

Prices are per generation, in Gems. 1,000 Gems cost $1 on the standard pack, and larger packs add bonus Gems. The price depends on the model, resolution, and duration; the default-settings price is shown, and every response reports the exact charge in billing.gems_charged. A generation that fails is refunded; one Mage's content policy blocks is not.

ModelBest formodel_id valuesDefault price
AnimaPurpose-built for animeanima-v120 Gems ($0.02)
ChromaOpen-weights, built on Fluxchroma-v1-hd35 Gems ($0.035)
Flux 2Long prompts and multi-reference editsflux2-dev40 Gems ($0.04)
GPT Image 2Precise prompts and readable textgpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2.6-flare, gpt-image-2.6-sunburst9 Gems ($0.009)
Grok ImageGrok Imagine, in two tiersgrok-imagine-image, grok-imagine-image-2.090 Gems ($0.09)
GuavaPhotorealism that passes for a photographguava, guava-pro, guava-pro-v1-5, guava-2, guava-2-pro37 Gems ($0.037)
HiDreamFast and versatile, with negative promptshidream-fast20 Gems ($0.02)
Krea 2Gorgeous aesthetics in secondskrea-2-turbo20 Gems ($0.02)
MangoOur flagship image familymango, mango-v2, mango-v3s, mango-v3, mango-v3-turbo, mango-v442 Gems ($0.042)
MOSS-ImageLong prompts and bilingual text, open weightsmoss-image25 Gems ($0.025)
Nano Banana 2Crisp, readable text, up to 4Knano-banana-v2, nano-banana-v2.151 Gems ($0.051)
SDXL PlusSDXL with faces and hands fixed6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8015 Gems ($0.015)
SeedreamSeedream, with a strict filterseedream-4.0, seedream-4.5, seedream-5.0-lite, seedream-5.0-pro, seedream-5.0-flash, seedream-5.542 Gems ($0.042)
Stable Diffusion v1.5The classic, on a budget15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D10 Gems ($0.01)
Stable Diffusion v3.5 LargeThe Stable Diffusion that listens bestsd-3-5-large10 Gems ($0.01)
Stable Diffusion XLPhotoreal-tuned SDXL6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8010 Gems ($0.01)
Z-ImageThe fastest image model on Magez-image-turbo10 Gems ($0.01)

Quick start

Generate an image with Anima v1

Set MAGE_API_KEY, submit the request, and poll until it completes. Swap anima in the URL for any model above.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/anima/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Editorial portrait in soft daylight, 35mm film look",
  "aspect_ratio": "4:5",
  "model_id": "anima-v1"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('anima', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'anima-v1',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("anima", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "anima-v1",
})

print(request["result"]["url"])

How it works

From API key to finished media in three calls

Every model shares one authentication scheme, one asynchronous request lifecycle, and the same field names.

  1. Create an API key

    Sign in to Mage, open API → API Keys, and create a key. It starts with mage_sk_ and is shown once. An account can hold 10 active keys.

  2. Submit a generation

    POST a JSON body to https://api.mage.space/v1/{model}/generate with an Authorization: Bearer header. The response returns at once with a request_id, a status, and a status_url. Send an Idempotency-Key header so a retry never pays twice.

  3. Poll and download

    Poll status_url until the status is completed, failed, or cancelled. A completed request carries result.url with the image, video, or audio file, kept for 30 days.

Built for production

What every Mage API request gets

  • One key, every model

    35 image, video, and audio models behind one REST API and one Gems balance. Switch models by changing the URL path.

  • Pay per generation

    No subscription and no minimum spend. You buy Gems, and each request is charged its listed price. A generation that fails is refunded, unless Mage's content policy blocked it.

  • Safe retries

    Idempotency keys make a retried submit return the original request without charging again.

  • Consistent characters

    Save a character or reference once, then write @handle in any prompt to use it with every model that supports it.

  • Large inputs

    Send image, video, and audio inputs as URLs or data URLs, or upload files up to 100 MB through a signed upload.

  • 20 generations in flight

    Each account can run 20 generations at once, and the limit can be raised for your use case. Refused requests are never charged.

Use cases

What developers build with the image API

  • Product and marketing images

    Render product shots, ad variants, and social posts on demand, with readable text from GPT Image 2.6 or Nano Banana 2.

  • Consistent characters

    Save a character once and keep the same face across a whole set with Mango 4, Guava 2 Pro, and other models that take @handle mentions.

  • Image editing pipelines

    Send a source image with an instruction to change exactly what you ask and keep the rest in place.

  • Apps and games

    Generate avatars, stickers, cards, and scenes inside your product without hosting a single GPU.

  • Photoreal portraits

    Guava 2 Pro renders portraits, fashion, and lifestyle shots with true-to-life skin, fabric, and light.

  • Fast drafts at scale

    Z-Image Turbo and Krea 2 keep prices low for high-volume thumbnails and first passes.

FAQ

Frequently asked questions

What is the best AI image generation API?
It depends on the job. On Mage, Mango 4 is the default for most images: it follows precise instructions, keeps characters consistent, and edits without disturbing the rest of the image. Guava 2 Pro is best for photorealism, GPT Image 2.6 and Nano Banana 2 for text in images, and Z-Image Turbo or Krea 2 for fast, low-cost drafts. All of them run through the same API.
Does the image API support image editing and reference images?
Yes. Models that accept images take them in the image and additional_images fields as URLs, data URLs, or uploads. Each model page lists its inputs and how many reference images it takes.
What resolutions does the image API support?
It depends on the model: 1K and 2K on most models, 3K on Mango 3S, and up to 4K on Mango 2 and Nano Banana 2. Each model page lists its resolution and aspect ratio options.
How much does the Mage API cost?
There is no subscription or monthly fee. Each generation is paid in Gems at its model's listed price, and 1,000 Gems cost $1 on the standard pack. Every model page lists its default-settings price, and each response reports the exact charge. A generation that fails is refunded; one Mage's content policy blocks is not. A request your balance cannot cover is refused before anything is charged.
Do I need a Mage membership to use the API?
No. The API runs on Gems alone. Membership plans and their unlimited in-app generation do not apply to API requests. The account needs one successful payment first, any Gem pack or plan; signup bonus Gems work in the Mage app only.
Can I use API outputs commercially?
Yes. Content you create with Mage, including through the API and MCP server, can be used commercially. Attribution is appreciated but not required.
What are the rate limits?
An account can have 20 generations queued or running at once. A submit past that is refused with 429 and costs nothing. Write to [email protected] to raise the cap for your use case.
Can my AI agent use the Mage API?
Yes. Agents can call the REST API with a key, or connect to the Mage MCP server, which gives Claude, ChatGPT, Claude Code, Grok, and Cursor sixteen ready-made tools for choosing a model, quoting the price, generating, and fetching the result. See the MCP server.
Is there an SDK for the Mage API?
Yes. The official @mage-space/sdk package on npm and mage-space on PyPI are open source and typed for every model. They submit, wait for the result, retry safely, and upload files for you. ComfyUI users can install the comfyui-mage node pack. See the Mage SDKs.
I already use another generation API. What do I have to change?
Point your client at https://api.mage.space/v1, send your Mage key as a Bearer token, and map your fields to the model page: prompt, aspect_ratio, resolution, duration, and model_id work the same way across every Mage model. Requests are asynchronous, so submit and then poll status_url.

Start building with Mage

One account, one Gems balance, every model. Pay only for what you generate.

Get an API keyRead the API docs