> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Mage API

> Run Mage image and video models from your own code through one authenticated, asynchronous API: submit a generation, poll its status, download the result. Every request is paid in Gems.

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.

<Note>
  The API is in early access. If the API tab is not visible in your settings
  yet, write to [mage@mage.space](mailto:mage@mage.space).
</Note>

<CardGroup cols={2}>
  <Card title="Run your first request" icon="rocket" href="/api/quickstart">
    Create a key and complete a generation from submission to result.
  </Card>

  <Card title="Get an API key" icon="key" href="https://www.mage.space/settings?tab=api">
    Keys are created in Settings → API and shown once.
  </Card>
</CardGroup>

## Make a request

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

```bash cURL theme={null}
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.

```json theme={null}
{
  "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

<CardGroup cols={3}>
  <Card title="Ship to production" icon="server" href="/api/requests">
    The request lifecycle, polling, cancellation, errors, and limits.
  </Card>

  <Card title="Send images and video" icon="upload" href="/api/inputs">
    URLs, data URLs, and uploads for files larger than a request body.
  </Card>

  <Card title="Pick a model" icon="layer-group" href="/api/models/overview">
    Every model with its fields, tokens, defaults, and price.
  </Card>
</CardGroup>

## 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](/api/versioning).

<Note>
  Results and inputs are kept for 30 days. Download what you want to keep.
</Note>