Mage SDK · TypeScript

Mage TypeScript SDK

Node.jsから、Mageの全モデルに対応した型付き設定で画像・動画・音声を生成。1回の呼び出しで、送信から待機、結果の取得までできます。

APIキーを取得TypeScriptガイドを読むGitHubでソースを見る
npm install @mage-space/sdk

ひと目でわかる概要

Mage TypeScript SDKは、Mage APIの公式オープンソースクライアントで、@mage-space/sdkとして公開されています。「npm install @mage-space/sdk」でインストールし、MAGE_API_KEYを設定して、モデルIDと設定を指定してmage.runを呼び出すだけで、28モデルのいずれかから完成した画像・動画・音声を取得できます。Node.js 20.19以降、またはfetchが使えるサーバーランタイムで動作し、すべての生成はGemで支払います。

セットアップ

TypeScript SDKをインストールしてモデルを実行

  1. パッケージをインストール

    プロジェクトに@mage-space/sdkを追加します。

    npm install @mage-space/sdk

  2. APIキーを設定

    mage.spaceの「API → API Keys」でキーを作成し、環境変数に設定します。クライアントはMAGE_API_KEYを読み込みます。

    export MAGE_API_KEY="mage_sk_..."

  3. 生成

    モデルIDとその設定を指定してrunを呼び出します。結果を待って返し、出力は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);

使用例

TypeScript SDKの使い方

各例は、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;
  }
}

SDKを使う理由

SDKが代わりに処理すること

1回の呼び出しで、完成したメディアを取得

runは生成を送信し、APIが推奨するバックオフでポーリングして、result.urlを含む完了済みのリクエストを返します。

二重課金されないリトライ

送信にはすべて冪等性キーが付きます。ネットワークエラーやサーバーエラーはバックオフ付きで再試行され、再試行した送信が再び課金されることはありません。

1回の呼び出しでアップロード

データURLには大きすぎるファイルは署名付きアップロードで送信。チケットの取得、PUT、サイズの確認はSDKが処理します。

わかりやすいエラー

APIに拒否された場合は、HTTPステータス、エラーコード、リクエストIDが付きます。生成の失敗やキャンセル、タイムアウトには、それぞれ専用のエラー型があります。

全モデルに型を用意

MangoConfigやCherryConfigなどの型はAPIリファレンスから生成されるため、エディタがフィールドを補完し、無効なオプションも検出します。

依存パッケージはゼロ

ランタイム依存のないESMです。Node.js組み込みのfetchを使い、すべての呼び出しでAbortSignalを指定できます。

リファレンス

TypeScript SDKの概要

どのモデルでも同じメソッドを使えます。モデルは第1引数で指定します。

メソッドできること
mage.run(model, config)生成を送信して完了を待ち、完了したリクエストを返します。
mage.generate(model, config)生成を送信し、すぐにリクエストを返します。
mage.requests.get / cancel / waitIDを指定して、リクエストの取得、停止、完了待ちを行います。
mage.uploads.upload(data)最大100 MBのファイルをアップロードし、そのURLを返します。
mage.characters / mage.references保存済みのキャラクターとリファレンスの一覧表示、作成、削除を行います。
mage.account.get()Gemの残高です。
mage.architectures.list()オプションと価格つきの最新モデルカタログです。

モデル

まずはこれらのモデルから

画像 · 37 Gems から

Guava API

写真と見間違えるほどのフォトリアリズム

画像 · 135 Gems から

Mango API

フラッグシップの画像モデルファミリー

画像 · 68 Gems から

Nano Banana 2 API

くっきり読みやすい文字、最大 4K

動画 · 618 Gems から

Cherry API

フラッグシップの動画モデルファミリー

動画 · 245 Gems から

Lemon API

すべての動画機能を、よりお手頃な価格で

音声 · 19 Gems から

Seed Audio API

ひとつのプロンプトから音声、音楽、効果音を生成

FAQ

よくある質問

Mage TypeScript SDKはブラウザで使えますか?

いいえ。APIキーを使うとGemが消費されるため、キーはサーバー側で管理してください。APIはCORSヘッダーを返さないので、ブラウザから直接呼び出すことはできません。代わりに自分のバックエンドを呼び出し、そこでSDKを使ってください。

TypeScript SDKはCommonJSで使えますか?

パッケージはESM専用です。Node.js 20.19以降なら、CommonJSからもrequire()で読み込めます。

TypeScript SDKはNext.jsで使えますか?

はい。ルートハンドラーやサーバーアクションなどのサーバーコードで使えます。SDKはfetchとAbortSignalなどの標準Web APIで作られているため、fetchが使える他のサーバーランタイムでも動作するはずですが、CIでテストしているのはNode.jsです。

Mage SDKは無料のオープンソースですか?

はい。SDKとComfyUIノードはGitHubでMITライセンスで公開されており、インストールは無料です。料金がかかるのは実行した生成分のみで、各モデルの表示価格どおりにGemで支払います。

Mageの新しいモデルは古いSDKでも使えますか?

はい。新しいモデルのIDを文字列で渡せば実行できます。SDKは、すべてのモデルに共通するフィールドに対して設定内容をチェックします。APIリファレンスが変更されるたびにボットが型を更新するため、新しいモデルは次のリリースで専用の型とともに追加されます。

SDKは、リトライしたリクエストの二重課金をどう防いでいますか?

送信するたびにIdempotency-Keyが付きます。SDKは呼び出しごとに新しいキーを作り、その呼び出しを自動でリトライするときは同じキーを再利用します。そのため、リトライされた送信は元のリクエストを返し、料金は発生しません。

SDKは安定していますか?

現在は0.xのベータ版のため、マイナーバージョンで変更される場合があります。API自体は別のバージョン管理で、v1の間は安定しています。

Mage API の料金はいくらですか?

サブスクリプションや月額料金はありません。生成ごとに、モデルごとの表示価格が Gems で差し引かれます。標準パックでは 1,000 Gems が $1 です。各モデルのページにはデフォルト設定での価格が掲載されており、各レスポンスには実際の請求額が含まれます。生成に失敗した場合は返却されますが、Mage のコンテンツポリシーでブロックされた場合は返却されません。残高が足りないリクエストは、課金される前に拒否されます。

API を使うには Mage のメンバーシップが必要ですか?

いいえ。API は Gems だけで利用できます。メンバーシッププランやアプリ内での無制限生成は API リクエストには適用されないため、Gems のある Mage アカウントなら誰でも呼び出せます。

API で生成したものは商用利用できますか?

はい。APIやMCPサーバー経由を含め、Mageで作成したコンテンツは商用利用できます。クレジット表記は歓迎しますが、必須ではありません。

Mageで開発を始めよう

アカウントはひとつ、Gemsの残高もひとつで、すべてのモデルが使えます。料金は生成した分だけです。

APIキーを取得TypeScriptガイドを読む

関連情報