Mage API

The Mage API runs the same models as the app from your own code. You submit a generation to a model’s endpoint, get back a request id with a status link, poll it, and download the result. Every request is paid in Gems from your account. Open the API dashboard by choosing API (Beta), below Agent in Mage’s navigation. Its API Keys, Billing, and Stats tabs bring key management, Gems billing, and usage together. The floating navigation also opens MCP to connect your assistant and the Playground to explore and try models.

Run your first request

Create a key and complete a generation from submission to result.

Get an API key

Open API → API Keys, select Create API key, and name it in the popup. Copy the one-time key, then use the quick start shown below it.

Make a request

Every model shares the same authentication, the same request lifecycle, and the same field names. The JSON body depends on the model.

curl --request POST \
  --url https://api.mage.space/v1/flux2/generate \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "prompt": "Editorial portrait in soft daylight", "aspect_ratio": "4:5" }'

import Mage from '@mage-space/sdk';

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

const request = await mage.generate('flux2', {
  prompt: 'Editorial portrait in soft daylight',
  aspect_ratio: '4:5',
});

from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.generate("flux2", {
    "prompt": "Editorial portrait in soft daylight",
    "aspect_ratio": "4:5",
})

The API answers at once with the request’s id, its state, and the links to check or cancel it. The SDKs’ run goes one step further: it waits for the result and returns the finished request.

{
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status": "in_progress",
  "architecture": "flux2",
  "model_id": "flux2-dev",
  "created_at": "2026-09-17T14:52:48.000Z",
  "updated_at": "2026-09-17T14:52:49.000Z",
  "billing": { "mode": "gems", "gems_charged": 40 },
  "result": null,
  "error": null,
  "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}

Choose your path

Ship to production

The request lifecycle, polling, cancellation, errors, and limits.

Send images, video, and audio

URLs, data URLs, and uploads for files larger than a request body.

Pick a model

Every model with its fields, tokens, defaults, and price.

SDKs and integrations

TypeScript SDK

npm install @mage-space/sdk. Typed configs for every model.

Python SDK

pip install mage-space. Sync and asyncio clients.

ComfyUI

Every Mage model as ComfyUI nodes. No GPU needed.

The SDKs submit and wait for results, send an idempotency key with every submission so a retry never charges twice, and upload large files for you. They are open source in the mage-space GitHub organization.

Base URL

Every endpoint lives under https://api.mage.space/v1. Fields, models, and endpoints are added within v1; anything that would break an existing client ships as a new version. See versioning.

Results and inputs are kept for 30 days. Download what you want to keep.

Get started

SDKs and integrations

Concepts

Endpoints

Models

Image models

Video models

Audio models

Run your first request

Get an API key

Make a request

Choose your path

Ship to production

Send images, video, and audio

Pick a model

SDKs and integrations

TypeScript SDK

Python SDK

ComfyUI

Base URL

Run your first request

Get an API key

​Make a request

​Choose your path

Ship to production

Send images, video, and audio

Pick a model

​SDKs and integrations

TypeScript SDK

Python SDK

ComfyUI

​Base URL

Make a request

Choose your path

SDKs and integrations

Base URL