1回の呼び出しで、完成したメディアを取得
runは生成を送信し、APIが推奨するバックオフでポーリングして、result.urlを含む完了済みのリクエストを返します。
ひと目でわかる概要
Mage Python SDK は、Mage API の公式オープンソースクライアントで、mage-space として公開されています。「pip install mage-space」でインストールし、MAGE_API_KEY を設定して、モデルIDと設定を指定して mage.run を呼び出すだけで、28種類のモデルから完成した画像・動画・音声を取得できます。Python 3.10 以降で動作し、生成にはすべて Gems を使用します。
3.10+
Python
httpx
HTTP クライアント
28
型付きモデル
MIT
オープンソース
セットアップ
Python SDK をインストールしてモデルを実行
パッケージをインストール
プロジェクトに mage-space を追加します。
pip install mage-spaceAPIキーを設定
mage.spaceの「API → API Keys」でキーを作成し、環境変数に設定します。クライアントはMAGE_API_KEYを読み込みます。
export MAGE_API_KEY="mage_sk_..."生成
モデルIDとその設定を指定してrunを呼び出します。結果を待って返し、出力はresult.urlにあります。
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"])
使用例
Python SDK の使いどころ
各例は、MAGE_API_KEYを読み込むクライアントから始まります。
今すぐ送信して、後で待つ
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)ファイルをアップロード
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})保存済みのキャラクターを使う
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})エラーを処理
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)SDKを使う理由
SDKが代わりに処理すること
二重課金されないリトライ
送信にはすべて冪等性キーが付きます。ネットワークエラーやサーバーエラーはバックオフ付きで再試行され、再試行した送信が再び課金されることはありません。
1回の呼び出しでアップロード
データURLには大きすぎるファイルは署名付きアップロードで送信。チケットの取得、PUT、サイズの確認はSDKが処理します。
わかりやすいエラー
APIに拒否された場合は、HTTPステータス、エラーコード、リクエストIDが付きます。生成の失敗やキャンセル、タイムアウトには、それぞれ専用のエラー型があります。
同期と asyncio
Mage と AsyncMage はすべてのメソッドが共通です。非同期クライアントは、Webサーバーやノートブック、多数の生成を同時に走らせるパイプラインに最適です。
型付き設定
各モデルには、APIリファレンスから生成された MangoConfig などの TypedDict があります。設定に型を付ければ、型チェッカーがフィールドを検証してくれます。
リファレンス
Python 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() | オプションと価格つきの最新モデルカタログです。 |
モデル
まずはこれらのモデルから
FAQ
よくある質問
Python SDK は asyncio に対応していますか?
はい。AsyncMage は Mage と同じメソッドを await で呼び出せ、非同期コンテキストマネージャーとしても使えます。
SDK はどの Python バージョンに対応していますか?
Python 3.10 以降に対応しています。依存ライブラリは httpx と typing-extensions のみです。
Python SDK はノートブックやデータパイプラインで使えますか?
はい。スクリプトやノートブックでは Mage を、多数の生成を同時に実行したい場合は asyncio と AsyncMage を使ってください。アカウントあたり最大20件の生成を同時に実行できます。
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の残高もひとつで、すべてのモデルが使えます。料金は生成した分だけです。