The AI image generation API for every model

At a glance

The Mage image generation API is a REST API at https://api.mage.space/v1 that runs 15 text-to-image and image-editing models, including Mango 3, Guava 2 Pro, GPT Image 2.5, 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.

• 15

  image models

• $0.009

  Cheapest default, per image

• 20

  Concurrent generations

• $0

  Monthly 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.

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.

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"

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['MAGE_API_KEY']}"}
request = requests.post(
    "https://api.mage.space/v1/anima/generate",
    headers=headers,
    json={
      "prompt": "Editorial portrait in soft daylight, 35mm film look",
      "aspect_ratio": "4:5",
      "model_id": "anima-v1"
    },
).json()

while request["status"] in ("queued", "in_progress"):
    time.sleep(3)
    request = requests.get(request["status_url"], headers=headers).json()

print(request["status"], request["result"] and request["result"]["url"])

const headers = {
  Authorization: `Bearer ${process.env.MAGE_API_KEY}`,
  'Content-Type': 'application/json',
};
let request = await fetch('https://api.mage.space/v1/anima/generate', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "anima-v1"
  }),
}).then((response) => response.json());

while (['queued', 'in_progress'].includes(request.status)) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  request = await fetch(request.status_url, { headers }).then((r) => r.json());
}

console.log(request.status, 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. 01

   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. 02

   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. 03

   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

Use cases

What developers build with the image API

FAQ

Frequently asked questions

Start building with Mage

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

Related

• AI video generation API
• AI audio generation API
• Mage MCP server
• All API models
• API playground
• API documentation