Skip to content
PlaygroundDocsGet API key

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.

  • 28Models
  • 3Media types
  • 16MCP tools
  • $0Monthly fee

Ways in

Call it from code, your assistant, or ComfyUI

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

  • SDKs

    TypeScript and Python SDKs

    Official, typed clients that submit, wait for the result, retry safely, and upload files in a few lines.

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

  • ComfyUI

    Mage for ComfyUI

    Mango, Cherry, Seed Audio, and every other Mage model as ComfyUI nodes. No GPU, no model downloads.

By media type

Generation APIs

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"
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('mango', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'mango-v3',
});

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

mage = Mage()  # reads MAGE_API_KEY

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

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.

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