一次调用,直接得到成品
run 会提交生成任务,按 API 推荐的退避间隔轮询,并在完成后返回包含 result.url 的请求结果。
一览
Mage Python SDK 是 Mage API 的官方开源客户端,发布名为 mage-space。运行 "pip install mage-space" 安装,设置 MAGE_API_KEY,再传入模型 ID 和配置调用 mage.run,即可用 28 个模型中的任意一个生成成品图片、视频或音频。它支持 Python 3.10 或更高版本,每次生成都使用 Gems 支付。
3.10+
Python
httpx
HTTP 客户端
28
类型化模型
MIT
开源
设置
安装 Python SDK 并运行模型
安装软件包
将 mage-space 添加到你的项目中。
pip install mage-space设置 API 密钥
在 mage.space 的 API → API Keys 中创建密钥并导出。客户端会读取 MAGE_API_KEY。
export MAGE_API_KEY="mage_sk_..."生成
用模型 id 及其配置调用 run。它会等待并返回结果,输出内容位于 result.url。
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"])
示例
Python SDK 实际使用
每个示例都从读取 MAGE_API_KEY 的客户端开始。
先提交,稍后再等结果
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)上传文件
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})使用已保存的角色
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})处理错误
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)为什么选择 SDK
SDK 帮你搞定的事
重试不会重复扣费
每次提交都带有幂等键。遇到网络错误和服务器错误时会按退避策略重试,重试的提交不会被再次扣费。
一次调用完成上传
对于太大而无法用 data URL 传输的文件,会通过签名上传完成,凭证、PUT 请求和大小检查都由 SDK 代劳。
清晰的错误信息
API 拒绝请求时会附带 HTTP 状态码、错误码和请求 ID;生成失败、被取消和超时也都有各自的错误类型。
同步与 asyncio
Mage 和 AsyncMage 的方法完全一致。异步客户端适用于 Web 服务器、Notebook,以及需要同时运行多个生成任务的流水线。
类型化配置
每个模型都有一个根据 API 参考生成的 TypedDict,例如 MangoConfig。用它标注配置,类型检查器就会检查各个字段。
参考
Python 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() | 实时模型目录,含选项和价格。 |
模型
从这些模型开始
常见问题
常见问题解答
Python SDK 支持 asyncio 吗?
支持。AsyncMage 的方法与 Mage 相同,需使用 await 调用,也可以作为异步上下文管理器使用。
SDK 支持哪些 Python 版本?
支持 Python 3.10 及更高版本。它仅依赖 httpx 和 typing-extensions。
可以在 Notebook 或数据流水线中使用 Python SDK 吗?
可以。在脚本和 Notebook 中使用 Mage,或者配合 asyncio 使用 AsyncMage 同时运行多个生成任务。每个账号最多可同时进行 20 个生成任务。
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 余额,畅用所有模型。按生成量付费,用多少付多少。