Mage SDK · TypeScript
The Mage 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.
npm install @mage-space/sdkAt a glance
The Mage TypeScript SDK is the official, open-source client for the Mage API, published as @mage-space/sdk. Install it with "npm install @mage-space/sdk", 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 Node.js 20.19 or later, or any server runtime with fetch, and every generation is paid in Gems.
- 20.19+Node.js
- 0Runtime dependencies
- 37Typed models
- MITOpen source
Setup
Install the TypeScript SDK and run a model
Install the package
Add @mage-space/sdk to your project.
npm install @mage-space/sdkSet 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.
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);
Examples
The TypeScript SDK in practice
Each example starts from a client that reads MAGE_API_KEY.
Submit now, wait later
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const submitted = await mage.generate('cherry', {
prompt: 'Waves rolling onto a black sand beach at sunset',
resolution: '720p',
duration: '5',
});
const final = await mage.requests.wait(submitted.request_id, {
timeout: 15 * 60_000,
onUpdate: (request) => console.log(request.status),
});Upload a file
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
await mage.run('cherry', {
prompt: 'Restyle this clip as a watercolor painting',
videos: [clip.url],
});Use a saved character
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
await mage.characters.create({
name: 'Ana',
handle: 'ana',
image: 'https://example.com/ana.png',
});
await mage.run('mango', { prompt: '@ana walking through a night market' });Handle errors
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
try {
await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
// Top up Gems, then try again.
} else if (error instanceof MageGenerationError) {
console.log('No output:', error.code);
} else {
throw error;
}
}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.
Typed for every model
MangoConfig, CherryConfig, and the rest are generated from the API reference, so your editor completes fields and catches invalid options.
Zero dependencies
ESM with no runtime dependencies. It uses the fetch built into Node.js, and every call takes an AbortSignal.
Reference
The TypeScript 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 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
Can I use the Mage TypeScript SDK in the browser?
Does the TypeScript SDK work with CommonJS?
Does the TypeScript SDK work with Next.js?
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.