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をインストールしてモデルを実行
パッケージをインストール
プロジェクトに@mage-space/sdkを追加します。
npm install @mage-space/sdkAPIキーを設定
mage.spaceの「API → API Keys」でキーを作成し、環境変数に設定します。クライアントはMAGE_API_KEYを読み込みます。
export MAGE_API_KEY="mage_sk_..."生成
モデル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 / wait | IDを指定して、リクエストの取得、停止、完了待ちを行います。 |
| mage.uploads.upload(data) | 最大100 MBのファイルをアップロードし、そのURLを返します。 |
| mage.characters / mage.references | 保存済みのキャラクターとリファレンスの一覧表示、作成、削除を行います。 |
| mage.account.get() | Gemの残高です。 |
| mage.architectures.list() | オプションと価格つきの最新モデルカタログです。 |
モデル
まずはこれらのモデルから
Guava API
写真と見間違えるほどのフォトリアリズム
Mango API
フラッグシップの画像モデルファミリー
Nano Banana 2 API
くっきり読みやすい文字、最大 4K
Cherry API
フラッグシップの動画モデルファミリー
Lemon API
すべての動画機能を、よりお手頃な価格で
Seed Audio API
ひとつのプロンプトから音声、音楽、効果音を生成
FAQ
よくある質問
Mage TypeScript SDKはブラウザで使えますか?
TypeScript SDKはCommonJSで使えますか?
TypeScript SDKはNext.jsで使えますか?
Mage SDKは無料のオープンソースですか?
Mageの新しいモデルは古いSDKでも使えますか?
SDKは、リトライしたリクエストの二重課金をどう防いでいますか?
SDKは安定していますか?
Mage API の料金はいくらですか?
API を使うには Mage のメンバーシップが必要ですか?
API で生成したものは商用利用できますか?
Mageで開発を始めよう
アカウントはひとつ、Gemsの残高もひとつで、すべてのモデルが使えます。料金は生成した分だけです。