メインコンテンツへスキップ

Mage SDK · TypeScript

Mage TypeScript SDK

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

npm install @mage-space/sdk

ひと目でわかる概要

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

  • 20.19+Node.js
  • 0ランタイム依存パッケージ
  • 37型付きモデル
  • MITオープンソース

セットアップ

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

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

  • 画像 · 42 Gemsから

    Mango API

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

  • 画像 · 51 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はGemのみで利用できます。メンバーシッププランとアプリ内での無制限生成は、APIリクエストには適用されません。まず、アカウントでGemパックまたはプランのいずれかを一度ご購入いただく必要があります。サインアップボーナスのGemはMageアプリでのみ使えます。
API で生成したものは商用利用できますか?
はい。APIやMCPサーバー経由を含め、Mageで作成したコンテンツは商用利用できます。クレジット表記は歓迎しますが、必須ではありません。

Mageで開発を始めよう

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

Charactersコミュニティ