One call, finished media
run submits the generation, polls with the backoff the API recommends, and resolves to the completed request with result.url.
At a glance
Mage publishes open-source SDKs for its API: @mage-space/sdk on npm for TypeScript and JavaScript, mage-space on PyPI for Python, and the comfyui-mage node pack for ComfyUI. Each wraps the REST API with typed configs for all 28 models, automatic polling, idempotent retries, and uploads.
3
SDKs and integrations
28
Typed models
MIT
Open source
$0
To install
Pick yours
SDKs and integrations
npm install @mage-space/sdk
TypeScript SDK
Generate images, video, and audio from Node.js with typed configs for every Mage model. One call submits, waits, and returns the result.
pip install mage-space
Python SDK
Generate images, video, and audio from Python with sync and asyncio clients and typed configs for every Mage model.
comfy node install comfyui-mage
Mage for ComfyUI
Mango, Cherry, Seed Audio, and every other Mage model as ComfyUI nodes. No GPU, no model downloads.
Quick start
Your first generation with an SDK
Install the package, export MAGE_API_KEY, and run a model.
TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
model_id: 'mango-v3',
});
console.log(request.result.url);Python
# pip install mage-space
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-v3",
})
print(request["result"]["url"])Built in
What every SDK handles for you
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.
Packages
Where to get them
| SDK | Package | Install | Source |
|---|---|---|---|
| TypeScript SDK | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| Python SDK | mage-space | pip install mage-space | GitHub |
| Mage for ComfyUI | comfyui-mage | comfy node install comfyui-mage | GitHub |
FAQ
Frequently asked questions
Are the Mage SDKs free and open source?
Yes. The SDKs and the ComfyUI nodes are MIT-licensed on GitHub, and installing them is free. You pay only for the generations you run, in Gems, at each model’s listed price.
Do new Mage models work with an older SDK?
Yes. Pass the new model’s id as a string and it runs; the SDK checks its config against the fields every model shares. A bot updates the types whenever the API reference changes, so new models arrive with their own types in the next release.
How do the SDKs avoid paying twice for a retried request?
Every submission carries an Idempotency-Key. The SDK makes a new key per call and reuses it when it retries that call itself, so a retried submission returns the original request and charges nothing.
Are the SDKs stable?
They are in beta at 0.x, so a minor version may still change them. The API itself is versioned separately and stays stable within v1.
How much does the Mage API cost?
There is no subscription or monthly fee. Each generation is paid in Gems at its model's listed price, and 1,000 Gems cost $1 on the standard pack. Every model page lists its default-settings price, and each response reports the exact charge. A generation that fails is refunded; one Mage's content policy blocks is not. A request your balance cannot cover is refused before anything is charged.
Do I need a Mage membership to use the API?
No. The API runs on Gems alone. Membership plans and their unlimited in-app generation do not apply to API requests, so any Mage account with Gems can call it.
Can I use API outputs commercially?
Yes. Content you create with Mage, including through the API and MCP server, can be used commercially. Attribution is appreciated but not required.
Start building with Mage
One account, one Gems balance, every model. Pay only for what you generate.