Mage API · Built for your next idea

One API. Endless possibilities.

Bring the best of Mage to your product and your AI assistant. Generate images, video, and audio with a single API key or a single MCP connection.

Get an API keyConnect your assistantRead the API docs
https://api.mage.space/v1

At a glance

Mage offers developers a REST API at https://api.mage.space/v1 and a remote MCP server at https://mcp.mage.space/mcp. Both run the same 28 image, video, and audio models, including the Mage-exclusive Mango 3 and Cherry 2 Pro, on one account, and every generation is paid in Gems with no subscription.

Two ways in

Call it from code, or from your assistant

REST API

The Mage API

Submit generations from your own code with a key. Asynchronous requests, idempotent retries, uploads up to 100 MB, and 20 generations in flight.

MCP server

The Mage MCP server

Connect Claude, ChatGPT, Claude Code, Grok, or Cursor with a sign-in, and ask for images, video, and audio in plain words.

By media type

Generation APIs

15 models

AI image generation API

Text-to-image, editing, and consistent characters up to 4K.

12 models

AI video generation API

Text-to-video, image-to-video, frames, references, and sound.

1 model

AI audio generation API

Voices, narration, music, and sound effects from a prompt.

Quick start

Your first generation

Create a key in API → API Keys, export it as MAGE_API_KEY, and run one of these.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/mango/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": "mango-v3"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
Python
import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['MAGE_API_KEY']}"}
request = requests.post(
    "https://api.mage.space/v1/mango/generate",
    headers=headers,
    json={
      "prompt": "Editorial portrait in soft daylight, 35mm film look",
      "aspect_ratio": "4:5",
      "model_id": "mango-v3"
    },
).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"])
JavaScript
const headers = {
  Authorization: `Bearer ${process.env.MAGE_API_KEY}`,
  'Content-Type': 'application/json',
};
let request = await fetch('https://api.mage.space/v1/mango/generate', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "mango-v3"
  }),
}).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. 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.

MCP

Mage in your AI assistant

Mage in Claude

Generate images, video, and audio in Claude on the web, the desktop app, the mobile apps, and Cowork.

Mage in ChatGPT

Generate images, video, and audio in ChatGPT as a personal MCP app.

Mage in Claude Code

Generate images, video, and audio in Claude Code in your terminal and editor.

Mage in Grok

Generate images, video, and audio in Grok as a custom connector.

Mage in Cursor

Generate images, video, and audio in Cursor Agent mode.

Models

Featured models

Image · from 40 Gems

Flux 2 API

Long prompts and multi-reference edits

Image · from 9 Gems

GPT Image 2 API

Precise prompts and readable text

Image · from 37 Gems

Guava API

Photorealism that passes for a photograph

Image · from 135 Gems

Mango API

Our flagship image family

Image · from 68 Gems

Nano Banana 2 API

Crisp, readable text, up to 4K

Video · from 618 Gems

Cherry API

Our flagship video family

Video · from 245 Gems

Lemon API

Every video feature, at a friendlier price

Video · from 338 Gems

Plum API

Sound on every clip, up to 2K

Audio · from 19 Gems

Seed Audio API

Voices, music, and sound effects from one prompt

Built for production

What every Mage API request gets

One key, every model

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

FAQ

Frequently asked questions

What is the Mage API?

The Mage API is a REST API at https://api.mage.space/v1 for generating images, video, and audio with 28 models from your own code. Requests are asynchronous and paid per generation in Gems.

What is the Mage MCP server?

A remote Model Context Protocol server at https://mcp.mage.space/mcp that lets AI assistants generate images, video, and audio on your Mage account. It gives the assistant 16 tools to pick a model, quote the price, generate, wait for the result, and use your saved characters, references, and history.

Do I need an API key to use the MCP server?

No. Claude, ChatGPT, Grok, Cursor, and Claude Code connect by signing in to Mage through OAuth. An API key is optional, for headless setups such as CI.

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, so any Mage account with Gems can call it.

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.

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 keyConnect your assistant

Related