Mage API · SDK

Mage API 官方 SDK

提供 TypeScript 與 Python 的型別化用戶端,以及適用於 ComfyUI 的 Mage 節點。幾行程式碼就能使用所有圖片、影片與音訊模型。

取得 API 金鑰閱讀 SDK 文件

重點速覽

Mage 為其 API 提供開源 SDK:TypeScript 與 JavaScript 使用 npm 上的 @mage-space/sdk,Python 使用 PyPI 上的 mage-space,ComfyUI 則使用 comfyui-mage 節點包。每個 SDK 都封裝了 REST API,內建全部 28 種模型的型別化設定、自動輪詢、冪等重試與檔案上傳。

選擇你的工具

SDK 與整合

npm install @mage-space/sdk

TypeScript SDK

在 Node.js 中生成圖片、影片與音訊,每個 Mage 模型都有型別化設定。只需一次呼叫,就能送出請求、等待並取回結果。

pip install mage-space

Python SDK

在 Python 中生成圖片、影片與音訊,提供同步與 asyncio 用戶端,每個 Mage 模型都有型別化設定。

comfy node install comfyui-mage

適用於 ComfyUI 的 Mage

Mango、Cherry、Seed Audio 和 Mage 的所有其他模型,都能作為 ComfyUI 節點使用。不需要 GPU,也不用下載模型。

快速開始

用 SDK 完成你的第一次生成

安裝套件、匯出 MAGE_API_KEY,然後執行模型。

TypeScript
// 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);
Python
# 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"])

內建功能

每個 SDK 都幫你處理好的事

一次呼叫,直接拿到成品

run 會送出生成請求,依 API 建議的退避間隔進行輪詢,最後回傳已完成的請求,並附上 result.url。

重試也不會重複扣款

每次送出都帶有冪等鍵。遇到網路錯誤與伺服器錯誤時會以退避方式重試,重試送出的請求絕不會再次收費。

一次呼叫完成上傳

太大而無法使用 data URL 的檔案會改走簽署上傳,票證、PUT 請求與大小檢查都由 SDK 代為處理。

清楚的錯誤訊息

API 拒絕請求時會附上 HTTP 狀態碼、錯誤代碼與請求 ID;生成失敗、被取消或逾時,也各有專屬的錯誤類型。

套件

取得方式

SDK套件安裝原始碼
TypeScript SDK@mage-space/sdknpm install @mage-space/sdkGitHub
Python SDKmage-spacepip install mage-spaceGitHub
Mage for ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

常見問題

常見問題

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 餘額,通用所有模型。只需為你生成的內容付費。

取得 API 金鑰閱讀 SDK 文件

相關內容