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

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 をインストールしてモデルを実行

  1. パッケージをインストール

    プロジェクトに mage-space を追加します。

    pip install mage-space
  2. APIキーを設定

    mage.spaceの「API → API Keys」でキーを作成し、環境変数に設定します。クライアントはMAGE_API_KEYを読み込みます。

    export MAGE_API_KEY="mage_sk_..."
  3. 生成

    モデル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 / 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

よくある質問

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

Mageで開発を始めよう

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

Charactersコミュニティ