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 余额,畅用所有模型。按生成量付费,用多少付多少。