Mage SDK · Python
The Mage Python SDK
Generate images, video, and audio from Python with sync and asyncio clients and typed configs for every Mage model.
pip install mage-spaceAt a glance
The Mage Python SDK is the official, open-source client for the Mage API, published as mage-space. Install it with "pip install mage-space", set MAGE_API_KEY, and call mage.run with a model id and a config to get finished images, video, or audio from any of 37 models. It runs on Python 3.10 or later, and every generation is paid in Gems.
- 3.10+Python
- httpxHTTP client
- 37Typed models
- MITOpen source
Setup
Install the Python SDK and run a model
Install the package
Add mage-space to your project.
pip install mage-spaceSet your API key
Create a key in API → API Keys on mage.space and export it. The client reads MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Generate
Call run with a model id and its config. It waits for the result and returns it; the output is at result.url.
from mage_space import Mage mage = Mage() # reads MAGE_API_KEY request = mage.run("mango", { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5", "model_id": "mango-v4", }) print(request["result"]["url"])
Examples
The Python SDK in practice
Each example starts from a client that reads MAGE_API_KEY.
Submit now, wait later
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)Upload a file
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})Use a saved character
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})Handle errors
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)Why the SDK
What the SDK handles for you
One call, finished media
run submits the generation, polls with the backoff the API recommends, and resolves to the completed request with result.url.
Retries that never pay twice
Every submission carries an idempotency key. Network errors and server errors are retried with backoff, and a retried submission is never charged again.
Uploads in one call
Files too large for a data URL go through a signed upload, with the ticket, the PUT, and the size check handled for you.
Clear errors
API refusals carry their HTTP status, error code, and request id; failed or cancelled generations and timeouts have their own error types.
Sync and asyncio
Mage and AsyncMage share every method. The async client fits web servers, notebooks, and pipelines that run many generations at once.
Typed configs
Each model has a TypedDict, such as MangoConfig, generated from the API reference. Annotate a config with it and your type checker checks the fields.
Reference
The Python SDK at a glance
The same methods cover every model; the model is the first argument.
| Method | What it does |
|---|---|
| mage.run(model, config) | Submit a generation, wait for it, and return the completed request. |
| mage.generate(model, config) | Submit a generation and return the request at once. |
| mage.requests.get / cancel / wait | Read, stop, or wait for a request by id. |
| mage.uploads.upload(data) | Upload a path, bytes, or file of up to 100 MB and return its URL. |
| mage.characters / mage.references | List, create, and delete saved characters and references. |
| mage.account.get() | Your Gems balance. |
| mage.architectures.list() | The live model catalog with options and prices. |
Models
Start with these models
Guava API
Photorealism that passes for a photograph
Mango API
Our flagship image family
Nano Banana 2 API
Crisp, readable text, up to 4K
Cherry API
Our flagship video family
Lemon API
Every video feature, at a friendlier price
Seed Audio API
Voices, music, and sound effects from one prompt
FAQ
Frequently asked questions
Does the Python SDK support asyncio?
Which Python versions does the SDK support?
Can I use the Python SDK in a notebook or a data pipeline?
Are the Mage SDKs free and open source?
Do new Mage models work with an older SDK?
How do the SDKs avoid paying twice for a retried request?
Are the SDKs stable?
How much does the Mage API cost?
Do I need a Mage membership to use the API?
Can I use API outputs commercially?
Start building with Mage
One account, one Gems balance, every model. Pay only for what you generate.