Mage Python SDK

Beta. This SDK is at 0.x: names and behaviour may change between minor versions until 1.0. The Mage API itself is versioned separately and is stable within v1.

The official Python client for the Mage API. Generate images, video, and audio with Mage models from your own code. Every request is paid in Gems from your Mage account.

• Sync (Mage) and asyncio (AsyncMage) clients on httpx
• run() submits a generation and waits for the result, backing off as the API recommends
• Safe retries: every submit carries an idempotency key, so a retry is never charged twice
• Uploads of large files through signed URLs in one call
• Typed request and response bodies for every model, generated from the API's OpenAPI spec

Install

pip install mage-space
# or
uv add mage-space

Python 3.10 or newer.

Quick start

Create a key in API → API Keys and export it:

export MAGE_API_KEY="mage_sk_..."

from mage_space import Mage

mage = Mage()

request = mage.run("mango", {"prompt": "A lighthouse at dawn, 35mm film", "aspect_ratio": "16:9"})
print(request["result"]["url"])

Keys belong to your account and spend your Gems. Keep them on your servers: the API sends no CORS headers, and a key shipped inside an app can be extracted.

Generating

run() is generate() followed by requests.wait(). Use the parts when you want the request id before the output is ready:

request = mage.generate(
    "cherry",
    {
        "prompt": "Waves rolling onto a black sand beach at sunset",
        "resolution": "720p",
        "duration": "5",
    },
)
print(request["request_id"], request["status"])  # ... in_progress

final = mage.requests.wait(
    request,
    timeout=900,  # seconds; then MageTimeoutError, and the request keeps running
    on_update=lambda r: print(r["status"]),
)
if final["status"] == "completed":
    print(final["result"]["url"])

wait() polls with growing intervals (2 s, then ×1.5 up to 15 s, with jitter). run() raises MageGenerationError when the request fails or is cancelled, so what it returns always has a result. Cancel a live request with mage.requests.cancel(request_id); Gems are not returned for a cancelled request.

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

Async

import asyncio

from mage_space import AsyncMage


async def main() -> None:
    async with AsyncMage() as mage:
        request = await mage.run("seed_audio", {"prompt": "Rain on a tin roof", "duration": "10"})
        print(request["result"]["url"])


asyncio.run(main())

AsyncMage has the same methods. Its on_update may be a plain function or a coroutine function.

Models

The first argument is the model's architecture id, as in its endpoint path: mango for images, cherry for video, seed_audio for audio, and many more. Choose a variant with model_id:

mage.run("mango", {"prompt": "...", "model_id": "mango-v3s"})

Each model has a TypedDict in mage_space.types with its fields, allowed values, and defaults. Annotate a config with it to have your type checker check it:

from mage_space.types import CherryConfig

config: CherryConfig = {"prompt": "A paper boat in a gutter stream", "resolution": "1080p"}
mage.run("cherry", config)

Fields a model's schema does not list pass through to the model unchanged, and a model newer than your SDK works by its id. For the live catalog with each model's options and price, call mage.architectures.list(). mage_space.ARCHITECTURES holds the name, output type, and request JSON Schema of every model this SDK version was generated from.

Inputs and uploads

Media fields (image, additional_images, first_image, last_image, video, videos) take an https URL or a data URL. Request bodies are capped at 4.5 MB, so upload larger files first and send the returned URL:

photo = mage.uploads.upload("photo.jpg")  # a path, bytes, or a binary file object; 100 MB max
mage.run("kiwi", {"prompt": "The camera slowly pushes in", "first_image": photo["url"]})

clip = mage.uploads.upload("clip.mp4")
mage.run("cherry", {"prompt": "Restyle this clip as watercolor", "videos": [clip["url"]]})

The content type comes from the file name; pass content_type= for raw bytes. Uploaded files are deleted after 30 days (url_expires_at).

Characters and references

Save a character or a reference once, then mention it by @handle in any prompt:

ana = mage.characters.create(name="Ana", handle="ana", image="https://example.com/ana.png")
coat = mage.references.create(name="Red coat", handle="red-coat", kind="outfit", image=photo["url"])

mage.run("mango", {"prompt": "@ana walking through a night market, wearing @red-coat"})

page = mage.characters.list(limit=50)
while page["next_cursor"]:
    page = mage.characters.list(cursor=page["next_cursor"])

mage.references.delete(coat["id"])

Errors

Exception	When
MageAPIError	The API answered with an error: status, code (for example insufficient_gems, invalid_config), message, request_id, body.
MageConnectionError	No response at all (network error or timeout), after retries.
MageGenerationError	run() ended with a failed or cancelled request: code (for example content_blocked), reason and stage for a provider block, and the final request.
MageTimeoutError	wait() or run() passed its timeout. A response that finishes late is never returned; Mage checks the deadline between network reads, so a stalled read can overrun it by up to the time that was left when the read began (AsyncMage stops on time). request is the last state read (None if none was); the request keeps running.

All four derive from MageError.

This is the beginning of the README. Read the rest at the original. Read the full README ↗