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 节点包。它们都封装了 REST API,提供全部 28 个模型的类型化配置、自动轮询、幂等重试和文件上传。

选择你的 SDK

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 测试阶段,次版本更新仍可能带来变动。API 本身单独进行版本管理,在 v1 内保持稳定。

Mage API 的费用是多少?

没有订阅,也没有月费。每次生成按对应模型的标价以 Gems 支付,标准包中 1,000 Gems 售价 $1。每个模型页面都会列出默认设置下的价格,每次响应也会返回实际扣费金额。生成失败会退还 Gems;因违反 Mage 内容政策而被拦截的则不予退还。如果你的余额不足以支付某次请求,该请求会在扣费前被拒绝。

使用 API 需要 Mage 会员吗?

不需要。API 仅使用 Gems。会员方案及其应用内无限生成权益不适用于 API 请求,因此任何有 Gems 的 Mage 账号都可以调用。

API 生成的内容可以商用吗?

可以。你用 Mage 创作的内容(包括通过 API 和 MCP 服务器生成的内容)可用于商业用途。署名我们会很感谢,但不是必须的。

用 Mage 开始开发

一个账号,一份 Gems 余额,畅用所有模型。按生成量付费,用多少付多少。

获取 API 密钥查看 SDK 文档

相关内容