Quickstart

This walkthrough runs one generation from the command line with curl and jq, to show each step of the API. You need a Mage account with a successful payment (any Gem pack or plan; the signup bonus does not cover the API) and access to API → API Keys.

Writing TypeScript or Python? The TypeScript SDK and the Python SDK do the submitting and polling below in one call. Create a key as in step 1, then:

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

const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('flux2', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
});
console.log(request.result.url);

# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY
request = mage.run("flux2", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
})
print(request["result"]["url"])

An API key spends the Gems on your account. Use it in server-side code only, and never commit it to source control.

Create a key

Open API → API Keys. In Mage’s navigation, this is API (Beta), below Agent, then the API Keys tab.
Select Create API key. In the popup, enter a Key name, such as Production server, then select Create key.
The You’re ready to build popup shows your new key. Select Copy key and save it securely before closing the popup.

The key starts with mage_sk_ and is shown only once; Mage keeps only a hash of it. The popup also includes an editable quick start and playground. To follow this command-line walkthrough, export the key in your shell:

export MAGE_API_KEY="mage_sk_..."

Your key appears under Active in API Keys. Previously revoked keys and their usage history are under Revoked. See Authentication for key management.

Submit a generation

Each model has its own endpoint, POST /v1/{architecture}/generate. The body holds the fields you want to set; every other field keeps the model’s default. This call uses Flux 2.

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, 35mm film look", "aspect_ratio": "4:5" }'

The response is the request’s current state. Gems are charged now, and status_url is where to look next.

{
  "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"
}

Keep request_id; everything else about the request is reached through it.

export REQUEST_ID="d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"

Poll until it finishes

Read status_url every few seconds until status is completed, failed, or cancelled.

while true; do
  STATE=$(curl --silent \
    --url "https://api.mage.space/v1/requests/$REQUEST_ID/status" \
    --header "Authorization: Bearer $MAGE_API_KEY")
  STATUS=$(echo "$STATE" | jq -r .status)
  [ "$STATUS" = "queued" ] || [ "$STATUS" = "in_progress" ] || break
  sleep 3
done
echo "$STATE" | jq .

A completed request carries the output in result.

{
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status": "completed",
  "architecture": "flux2",
  "model_id": "flux2-dev",
  "created_at": "2026-09-17T14:52:48.000Z",
  "updated_at": "2026-09-17T14:53:10.000Z",
  "billing": { "mode": "gems", "gems_charged": 40 },
  "result": {
    "type": "image",
    "url": "https://cdn3.mage.space/temp/30d/user/image.png",
    "width": 1024,
    "height": 1280,
    "seed": 1234567,
    "expires_at": "2026-10-17T14:52:48.000Z",
    "moderation": { "nsfw": false }
  },
  "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"
}

Download the output

curl --output portrait.png "$(echo "$STATE" | jq -r .result.url)"

Temporary media expires 30 days after the request, at result.expires_at. Copy what you want to keep to your own storage.

Cancel a request

A live request stops when you POST to its cancel_url. The response is the request’s state afterwards. Gems are not returned for a cancelled request.

curl --request POST \
  --url "https://api.mage.space/v1/requests/$REQUEST_ID/cancel" \
  --header "Authorization: Bearer $MAGE_API_KEY"

Try a video model

The same call reaches every model; only the endpoint and the fields change. This one runs Plum for five seconds at 16:9. Video takes longer than an image, so poll less often.

curl --request POST \
  --url https://api.mage.space/v1/plum/generate \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "5" }'

Try an audio model

Seed Audio generates voices, dialogue, music, and sound effects as an MP3 of exactly the duration you ask for, from 5 to 120 seconds. The result’s type is audio, and its url is the MP3.

curl --request POST \
  --url https://api.mage.space/v1/seed_audio/generate \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "prompt": "A calm narrator reading a short weather report", "duration": "10" }'

To voice it with a clip of your own, save the clip as an audio reference with POST /v1/references and mention its handle in the prompt: "@radio-host reads the forecast". The same field names mean the same thing on every model: aspect_ratio as W:H, first_image and last_image, resolution, duration. Each model’s reference page lists its fields, the values each one accepts, its defaults, and its price at those defaults. You can also open Playground and select Try this on a model to edit the request, try it in the playground, or copy it as cURL or as code for the TypeScript or Python SDK.

Next steps

TypeScript SDK

Typed configs, a call that waits for the result, and safe retries.

Python SDK

The same, with sync and asyncio clients.

Requests and lifecycle

Statuses, polling, idempotency keys, cancellation, and results.

Models

Every model with its endpoint, fields, and price.

Inputs and uploads

Send images, video, and saved audio clips to a model.

Errors and retries

Every error code, what it means, and what to retry.

Get started

SDKs and integrations

Concepts

Endpoints

Models

Image models

Video models

Audio models

Cancel a request

Try a video model

Try an audio model

Next steps

TypeScript SDK

Python SDK

Requests and lifecycle

Models

Inputs and uploads

Errors and retries

​Cancel a request

​Try a video model

​Try an audio model

​Next steps

TypeScript SDK

Python SDK

Requests and lifecycle

Models

Inputs and uploads

Errors and retries

Cancel a request

Try a video model

Try an audio model

Next steps