Mage SDK · Python
Mage Python SDK
用 Python 搭配同步與 asyncio 用戶端,以及每個 Mage 模型的型別化設定,生成圖片、影片和音訊。
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-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-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 幫你處理的事
一次呼叫,直接拿到成品
run 會送出生成請求,依 API 建議的退避間隔進行輪詢,最後回傳已完成的請求,並附上 result.url。
重試也不會重複扣款
每次送出都帶有冪等鍵。遇到網路錯誤與伺服器錯誤時會以退避方式重試,重試送出的請求絕不會再次收費。
一次呼叫完成上傳
太大而無法使用 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() | 即時模型目錄,包含選項與價格。 |
模型
從這些模型開始
Guava API
擬真度媲美實拍照片
Mango API
我們的旗艦圖片系列
Nano Banana 2 API
文字銳利清晰,最高支援 4K
Cherry API
我們的旗艦影片系列
Lemon API
完整影片功能,價格更親民
Seed Audio API
一個提示詞,生成人聲、音樂和音效
常見問題
常見問題
Python SDK 支援 asyncio 嗎?
SDK 支援哪些 Python 版本?
可以在 Notebook 或資料管線中使用 Python SDK 嗎?
Mage SDK 是免費且開源的嗎?
新的 Mage 模型能搭配舊版 SDK 使用嗎?
SDK 如何避免重試請求時重複扣款?
SDK 穩定嗎?
Mage API 的費用是多少?
使用 API 需要 Mage 會員資格嗎?
API 生成的內容可以商用嗎?
開始使用 Mage 打造你的作品
一個帳號、一份 Gems 餘額,通用所有模型。只需為你生成的內容付費。