Mage SDK · Python
Mage Python SDK
同期・asyncio クライアントと、すべての Mage モデルに対応した型付き設定で、Python から画像・動画・音声を生成できます。
pip install mage-spaceひと目でわかる概要
Mage Python SDKは、Mage API向けの公式オープンソースクライアントで、mage-space として公開されています。「pip install mage-space」でインストールし、MAGE_API_KEYを設定して、モデルidと設定を指定して mage.run を呼び出せば、37モデルのどれからでも完成した画像、動画、音声を取得できます。Python 3.10以降で動作し、生成ごとにGemsで支払います。
- 3.10+Python
- httpxHTTP クライアント
- 37型付きモデル
- 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-v4", }) 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回の呼び出しで、完成したメディアを取得
runは生成を送信し、APIが推奨するバックオフでポーリングして、result.urlを含む完了済みのリクエストを返します。
二重課金されないリトライ
送信にはすべて冪等性キーが付きます。ネットワークエラーやサーバーエラーはバックオフ付きで再試行され、再試行した送信が再び課金されることはありません。
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() | オプションと価格つきの最新モデルカタログです。 |
モデル
まずはこれらのモデルから
Guava API
写真と見間違えるほどのフォトリアリズム
Mango API
フラッグシップの画像モデルファミリー
Nano Banana 2 API
くっきり読みやすい文字、最大 4K
Cherry API
フラッグシップの動画モデルファミリー
Lemon API
すべての動画機能を、よりお手頃な価格で
Seed Audio API
ひとつのプロンプトから音声、音楽、効果音を生成
FAQ
よくある質問
Python SDK は asyncio に対応していますか?
SDK はどの Python バージョンに対応していますか?
Python SDK はノートブックやデータパイプラインで使えますか?
Mage SDKは無料のオープンソースですか?
Mageの新しいモデルは古いSDKでも使えますか?
SDKは、リトライしたリクエストの二重課金をどう防いでいますか?
SDKは安定していますか?
Mage API の料金はいくらですか?
API を使うには Mage のメンバーシップが必要ですか?
API で生成したものは商用利用できますか?
Mageで開発を始めよう
アカウントはひとつ、Gemsの残高もひとつで、すべてのモデルが使えます。料金は生成した分だけです。