跳至主要内容

Mage API · SDK

Mage API 官方 SDK

提供 TypeScript 和 Python 的类型化客户端,以及适用于 ComfyUI 的 Mage 节点。几行代码即可调用所有图片、视频和音频模型。

一览

Mage 为其 API 发布了开源 SDK:适用于 TypeScript 和 JavaScript 的 npm 包 @mage-space/sdk,适用于 Python 的 PyPI 包 mage-space,以及适用于 ComfyUI 的 comfyui-mage 节点包。它们都封装了 REST API,提供全部 37 个模型的类型化配置、自动轮询、幂等重试和上传功能。

  • 3SDK 和集成
  • 37类型化模型
  • MIT开源
  • $0安装方式

选择你的 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-v4',
});

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-v4",
})

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 请求。账号需要先成功付款一次,购买任意 Gem 包或套餐均可;注册赠送的 Gems 仅限在 Mage 应用内使用。
API 生成的内容可以商用吗?
可以。你用 Mage 创作的内容(包括通过 API 和 MCP 服务器生成的内容)可用于商业用途。署名我们会很感谢,但不是必须的。

用 Mage 开始开发

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

Characters社区