Mage SDK · TypeScript
Mage TypeScript SDK
在 Node.js 中生成圖片、影片與音訊,每個 Mage 模型都有型別化設定。一次呼叫即可提交、等待並取得結果。
npm install @mage-space/sdk重點速覽
Mage TypeScript SDK 是 Mage API 的官方開源用戶端,套件名稱為 @mage-space/sdk。執行「npm install @mage-space/sdk」安裝,設定 MAGE_API_KEY,再以模型 ID 和設定呼叫 mage.run,即可從 37 款模型中取得生成完成的圖片、影片或音訊。它可在 Node.js 20.19 或更新版本,或任何支援 fetch 的伺服器執行環境中執行,每次生成都以 Gems 付費。
- 20.19+Node.js
- 0執行階段相依套件
- 37型別化模型
- MIT開源
設定
安裝 TypeScript SDK 並執行模型
安裝套件
將 @mage-space/sdk 加入你的專案。
npm install @mage-space/sdk設定 API 金鑰
在 mage.space 的 API → API Keys 建立金鑰,並匯出為環境變數。用戶端會讀取 MAGE_API_KEY。
export MAGE_API_KEY="mage_sk_..."開始生成
以模型 id 與其設定呼叫 run。它會等待結果並回傳,輸出內容位於 result.url。
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-v4', }); console.log(request.result.url);
範例
TypeScript SDK 實際應用
每個範例都從讀取 MAGE_API_KEY 的用戶端開始。
先提交,稍後再等待
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const submitted = await mage.generate('cherry', {
prompt: 'Waves rolling onto a black sand beach at sunset',
resolution: '720p',
duration: '5',
});
const final = await mage.requests.wait(submitted.request_id, {
timeout: 15 * 60_000,
onUpdate: (request) => console.log(request.status),
});上傳檔案
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
await mage.run('cherry', {
prompt: 'Restyle this clip as a watercolor painting',
videos: [clip.url],
});使用已儲存的角色
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
await mage.characters.create({
name: 'Ana',
handle: 'ana',
image: 'https://example.com/ana.png',
});
await mage.run('mango', { prompt: '@ana walking through a night market' });處理錯誤
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
try {
await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
// Top up Gems, then try again.
} else if (error instanceof MageGenerationError) {
console.log('No output:', error.code);
} else {
throw error;
}
}為什麼選擇 SDK
SDK 幫你處理的事
一次呼叫,直接拿到成品
run 會送出生成請求,依 API 建議的退避間隔進行輪詢,最後回傳已完成的請求,並附上 result.url。
重試也不會重複扣款
每次送出都帶有冪等鍵。遇到網路錯誤與伺服器錯誤時會以退避方式重試,重試送出的請求絕不會再次收費。
一次呼叫完成上傳
太大而無法使用 data URL 的檔案會改走簽署上傳,票證、PUT 請求與大小檢查都由 SDK 代為處理。
清楚的錯誤訊息
API 拒絕請求時會附上 HTTP 狀態碼、錯誤代碼與請求 ID;生成失敗、被取消或逾時,也各有專屬的錯誤類型。
每個模型都有型別
MangoConfig、CherryConfig 等型別皆由 API 參考文件自動產生,因此編輯器能補全欄位,並攔截無效的選項。
零相依
採用 ESM 格式,沒有任何執行階段相依套件。使用 Node.js 內建的 fetch,每次呼叫都能傳入 AbortSignal。
參考
TypeScript SDK 速覽
同一組方法適用於所有模型;模型是第一個引數。
| 方法 | 功能 |
|---|---|
| mage.run(model, config) | 提交生成、等待完成,並回傳已完成的請求。 |
| mage.generate(model, config) | 提交生成,並立即回傳請求。 |
| mage.requests.get / cancel / wait | 依 id 讀取、停止或等待請求。 |
| mage.uploads.upload(data) | 上傳最大 100 MB 的檔案,並回傳其 URL。 |
| 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
一個提示詞,生成人聲、音樂和音效
常見問題
常見問題
可以在瀏覽器中使用 Mage TypeScript SDK 嗎?
TypeScript SDK 支援 CommonJS 嗎?
TypeScript SDK 可以搭配 Next.js 使用嗎?
Mage SDK 是免費且開源的嗎?
新的 Mage 模型能搭配舊版 SDK 使用嗎?
SDK 如何避免重試請求時重複扣款?
SDK 穩定嗎?
Mage API 的費用是多少?
使用 API 需要 Mage 會員資格嗎?
API 生成的內容可以商用嗎?
開始使用 Mage 打造你的作品
一個帳號、一份 Gems 餘額,通用所有模型。只需為你生成的內容付費。