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.
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.
28
Models
3
Media types
16
MCP tools
$0
Monthly fee
Two ways in
REST 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
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
Quick start
Create a key in API → API Keys, export it as MAGE_API_KEY, and run one of these.
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"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"])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
Every model shares one authentication scheme, one asynchronous request lifecycle, and the same field names.
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.
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.
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
Generate images, video, and audio in Claude on the web, the desktop app, the mobile apps, and Cowork.
Generate images, video, and audio in ChatGPT as a personal MCP app.
Generate images, video, and audio in Claude Code in your terminal and editor.
Generate images, video, and audio in Grok as a custom connector.
Generate images, video, and audio in Cursor Agent mode.
Models
Image · from 40 Gems
Long prompts and multi-reference edits
Image · from 9 Gems
Precise prompts and readable text
Image · from 37 Gems
Photorealism that passes for a photograph
Image · from 135 Gems
Our flagship image family
Image · from 68 Gems
Crisp, readable text, up to 4K
Video · from 618 Gems
Our flagship video family
Video · from 245 Gems
Every video feature, at a friendlier price
Video · from 338 Gems
Sound on every clip, up to 2K
Audio · from 19 Gems
Voices, music, and sound effects from one prompt
Built for production
28 image, video, and audio models behind one REST API and one Gems balance. Switch models by changing the URL path.
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.
Idempotency keys make a retried submit return the original request without charging again.
Save a character or reference once, then write @handle in any prompt to use it with every model that supports it.
Send image, video, and audio inputs as URLs or data URLs, or upload files up to 100 MB through a signed upload.
Each account can run 20 generations at once, and the limit can be raised for your use case. Refused requests are never charged.
FAQ
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.
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.
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.
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.
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.
Yes. Content you create with Mage, including through the API and MCP server, can be used commercially. Attribution is appreciated but not required.
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.
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.
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.
One account, one Gems balance, every model. Pay only for what you generate.