The Mage TypeScript SDK

At 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 28 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

• 0

  Runtime dependencies

• 28

  Typed models

• MIT

  Open source

Setup

Install the TypeScript SDK and run a model

1. 01

   Install the package

   Add @mage-space/sdk to your project.

   npm install @mage-space/sdk

2. 02

   Set 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_..."

3. 03

   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-v3',
   });
   
   console.log(request.result.url);

Examples

The TypeScript SDK in practice

Each example starts from a client that reads MAGE_API_KEY.

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),
});

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],
});

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' });

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

Reference

The TypeScript SDK at a glance

The same methods cover every model; the model is the first argument.

Models

Start with these models

FAQ

Frequently asked questions

Start building with Mage

One account, one Gems balance, every model. Pay only for what you generate.

Related

• Mage SDKs
• Mage Python SDK
• Mage for ComfyUI
• @mage-space/sdk on npm
• All API models
• API documentation