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.

The API is in early access. If the API tab is not visible in your settings yet, write to mage@mage.space.

Run your first request

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

Get an API key

Keys are created in Settings → API and shown once.

Make a request

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

cURL

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": "portrait" }'

The API answers at once with the request’s id, its state, and the links to check or cancel it.

{
  "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 and video

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

Pick a model

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

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.

Last modified on September 17, 2026

Get started

Concepts

Endpoints

Models

Image models

Video models

Run your first request

Get an API key

Make a request

Choose your path

Ship to production

Send images and video

Pick a model

Base URL

Run your first request

Get an API key

​Make a request

​Choose your path

Ship to production

Send images and video

Pick a model

​Base URL

Make a request

Choose your path

Base URL