Mage API · SDK

Mage API公式SDK

TypeScriptとPython向けの型付きクライアントと、ComfyUI向けのMageノード。画像・動画・音声のあらゆるモデルを、数行のコードで使えます。

APIキーを取得SDKドキュメントを読む

ひと目でわかる概要

Mageは、APIのオープンソースSDKを公開しています。TypeScript/JavaScript向けにnpmの@mage-space/sdk、Python向けにPyPIのmage-space、ComfyUI向けにcomfyui-mageノードパックを提供。いずれもREST APIをラップし、全28モデルの型付き設定、自動ポーリング、冪等なリトライ、アップロードに対応しています。

お好みのものを選択

SDKと連携

npm install @mage-space/sdk

TypeScript SDK

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

pip install mage-space

Python SDK

Pythonから画像・動画・音声を生成。同期クライアントとasyncioクライアントに対応し、すべてのMageモデルに型付き設定を用意しています。

comfy node install comfyui-mage

ComfyUI向けMage

Mango、Cherry、Seed Audioをはじめ、Mageのすべてのモデルを ComfyUIノードとして利用可能。GPUもモデルのダウンロードも不要です。

クイックスタート

SDKで最初の生成をする

パッケージをインストールし、MAGE_API_KEYをexportして、モデルを実行しましょう。

TypeScript
// npm install @mage-space/sdk
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);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("mango", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "mango-v3",
})

print(request["result"]["url"])

標準搭載

すべてのSDKが代わりに処理してくれること

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

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

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

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

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

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

わかりやすいエラー

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

パッケージ

入手先

SDKパッケージインストールソース
TypeScript SDK@mage-space/sdknpm install @mage-space/sdkGitHub
Python SDKmage-spacepip install mage-spaceGitHub
ComfyUI向けMagecomfyui-magecomfy node install comfyui-mageGitHub

FAQ

よくある質問

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キーを取得SDKドキュメントを読む

関連情報