一次呼叫,直接拿到成品
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-space設定 API 金鑰
在 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 幫你處理的事
重試也不會重複扣款
每次送出都帶有冪等鍵。遇到網路錯誤與伺服器錯誤時會以退避方式重試,重試送出的請求絕不會再次收費。
一次呼叫完成上傳
太大而無法使用 data URL 的檔案會改走簽署上傳,票證、PUT 請求與大小檢查都由 SDK 代為處理。
清楚的錯誤訊息
API 拒絕請求時會附上 HTTP 狀態碼、錯誤代碼與請求 ID;生成失敗、被取消或逾時,也各有專屬的錯誤類型。
同步與 asyncio
Mage 和 AsyncMage 的方法完全相同。非同步用戶端適合網頁伺服器、Notebook,以及同時執行大量生成的管線。
型別化設定
每個模型都有依 API 參考文件產生的 TypedDict,例如 MangoConfig。用它標註設定,型別檢查工具就會幫你檢查欄位。
參考
Python SDK 快速總覽
同一組方法適用於所有模型；模型是第一個引數。
| 方法 | 功能 |
|---|---|
| mage.run(model, config) | 提交生成、等待完成，並回傳已完成的請求。 |
| mage.generate(model, config) | 提交生成，並立即回傳請求。 |
| mage.requests.get / cancel / wait | 依 id 讀取、停止或等待請求。 |
| mage.uploads.upload(data) | 上傳路徑、位元組或最大 100 MB 的檔案,並回傳其網址。 |
| mage.characters / mage.references | 列出、建立與刪除已儲存的角色與參考圖。 |
| mage.account.get() | 你的 Gems 餘額。 |
| mage.architectures.list() | 即時模型目錄，包含選項與價格。 |
模型
從這些模型開始
常見問題
常見問題
Python SDK 支援 asyncio 嗎?
支援。AsyncMage 的方法與 Mage 相同,以 await 呼叫,也可以當作非同步情境管理器使用。
SDK 支援哪些 Python 版本?
支援 Python 3.10 以上版本。僅依賴 httpx 和 typing-extensions。
可以在 Notebook 或資料管線中使用 Python SDK 嗎?
可以。在指令碼和 Notebook 中使用 Mage,或搭配 asyncio 使用 AsyncMage 同時執行多個生成。帳號最多可同時進行 20 個生成。
Mage SDK 是免費且開源的嗎?
是的。SDK 與 ComfyUI 節點皆以 MIT 授權在 GitHub 上開源，安裝完全免費。你只需為實際執行的生成付費，以 Gems 依各模型標示的價格計算。
新的 Mage 模型能搭配舊版 SDK 使用嗎？
可以。將新模型的 id 以字串傳入就能執行；SDK 會依所有模型共通的欄位檢查設定。每當 API 參考文件有變動，機器人就會更新型別，所以新模型會在下一個版本附上自己的型別。
SDK 如何避免重試請求時重複扣款？
每次提交都會帶有 Idempotency-Key。SDK 會為每次呼叫產生新的金鑰，並在自行重試該次呼叫時沿用同一把金鑰，因此重試的提交會回傳原本的請求，不會再次收費。
SDK 穩定嗎？
目前處於 0.x 的 Beta 階段，次要版本仍可能更動內容。API 本身的版本另外管理，並在 v1 內保持穩定。
Mage API 的費用是多少?
沒有訂閱制,也沒有月費。每次生成都依該模型的標示價格以 Gems 支付,標準方案中 1,000 Gems 為 $1。每個模型頁面都會列出預設設定下的價格,每次回應也會顯示實際扣款金額。生成失敗會退款;但被 Mage 內容政策封鎖的不會退款。若你的餘額不足以支付請求,系統會在扣款前直接拒絕。
使用 API 需要 Mage 會員資格嗎?
不需要。API 只使用 Gems。會員方案及其應用程式內無限生成的權益不適用於 API 請求,因此任何擁有 Gems 的 Mage 帳號都能呼叫。
API 生成的內容可以商用嗎?
可以。你使用 Mage 建立的內容,包括透過 API 和 MCP 伺服器產生的內容,都可以用於商業用途。我們歡迎標示出處,但不強制要求。
開始使用 Mage 打造你的作品
一個帳號、一份 Gems 餘額,通用所有模型。只需為你生成的內容付費。