一次呼叫,直接拿到成品
run 會送出生成請求,依 API 建議的退避間隔進行輪詢,最後回傳已完成的請求,並附上 result.url。
重點速覽
Mage 為其 API 提供開源 SDK:TypeScript 與 JavaScript 使用 npm 上的 @mage-space/sdk,Python 使用 PyPI 上的 mage-space,ComfyUI 則使用 comfyui-mage 節點包。每個 SDK 都封裝了 REST API,內建全部 28 種模型的型別化設定、自動輪詢、冪等重試與檔案上傳。
3
SDK 與整合
28
型別化模型
MIT
開源
$0
安裝方式
選擇你的工具
npm install @mage-space/sdk
在 Node.js 中生成圖片、影片與音訊,每個 Mage 模型都有型別化設定。只需一次呼叫,就能送出請求、等待並取回結果。
pip install mage-space
在 Python 中生成圖片、影片與音訊,提供同步與 asyncio 用戶端,每個 Mage 模型都有型別化設定。
comfy node install comfyui-mage
Mango、Cherry、Seed Audio 和 Mage 的所有其他模型,都能作為 ComfyUI 節點使用。不需要 GPU,也不用下載模型。
快速開始
安裝套件、匯出 MAGE_API_KEY,然後執行模型。
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
model_id: 'mango-v3',
});
console.log(request.result.url);# pip install mage-space
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"])內建功能
run 會送出生成請求,依 API 建議的退避間隔進行輪詢,最後回傳已完成的請求,並附上 result.url。
每次送出都帶有冪等鍵。遇到網路錯誤與伺服器錯誤時會以退避方式重試,重試送出的請求絕不會再次收費。
太大而無法使用 data URL 的檔案會改走簽署上傳,票證、PUT 請求與大小檢查都由 SDK 代為處理。
API 拒絕請求時會附上 HTTP 狀態碼、錯誤代碼與請求 ID;生成失敗、被取消或逾時,也各有專屬的錯誤類型。
套件
| SDK | 套件 | 安裝 | 原始碼 |
|---|---|---|---|
| TypeScript SDK | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| Python SDK | mage-space | pip install mage-space | GitHub |
| Mage for ComfyUI | comfyui-mage | comfy node install comfyui-mage | GitHub |
常見問題
是的。SDK 與 ComfyUI 節點皆以 MIT 授權在 GitHub 上開源,安裝完全免費。你只需為實際執行的生成付費,以 Gems 依各模型標示的價格計算。
可以。將新模型的 id 以字串傳入就能執行;SDK 會依所有模型共通的欄位檢查設定。每當 API 參考文件有變動,機器人就會更新型別,所以新模型會在下一個版本附上自己的型別。
每次提交都會帶有 Idempotency-Key。SDK 會為每次呼叫產生新的金鑰,並在自行重試該次呼叫時沿用同一把金鑰,因此重試的提交會回傳原本的請求,不會再次收費。
目前處於 0.x 的 Beta 階段,次要版本仍可能更動內容。API 本身的版本另外管理,並在 v1 內保持穩定。
沒有訂閱制,也沒有月費。每次生成都依該模型的標示價格以 Gems 支付,標準方案中 1,000 Gems 為 $1。每個模型頁面都會列出預設設定下的價格,每次回應也會顯示實際扣款金額。生成失敗會退款;但被 Mage 內容政策封鎖的不會退款。若你的餘額不足以支付請求,系統會在扣款前直接拒絕。
不需要。API 只使用 Gems。會員方案及其應用程式內無限生成的權益不適用於 API 請求,因此任何擁有 Gems 的 Mage 帳號都能呼叫。
可以。你使用 Mage 建立的內容,包括透過 API 和 MCP 伺服器產生的內容,都可以用於商業用途。我們歡迎標示出處,但不強制要求。
一個帳號、一份 Gems 餘額,通用所有模型。只需為你生成的內容付費。