Skip to content
PlaygroundDocsGet API key

Mage API · SDKs

Official SDKs for the Mage API

Typed clients for TypeScript and Python, and Mage nodes for ComfyUI. Every image, video, and audio model in a few lines of code.

Get an API keyRead the SDK docs

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 37 models, automatic polling, idempotent retries, and uploads.

  • 3SDKs and integrations
  • 37Typed models
  • MITOpen source
  • $0To 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-v4',
});

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-v4",
})

print(request["result"]["url"])

Built in

What every 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.

Packages

Where to get them

SDKPackageInstallSource
TypeScript SDK@mage-space/sdknpm install @mage-space/sdkGitHub
Python SDKmage-spacepip install mage-spaceGitHub
Mage for ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

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. The account needs one successful payment first, any Gem pack or plan; signup bonus Gems work in the Mage app only.
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.

Get an API keyRead the SDK docs
CharactersCommunity