跳至主要内容

Mage SDK · Python

Mage Python SDK

用 Python 生成图片、视频和音频,支持同步和 asyncio 客户端,并为每个 Mage 模型提供类型化配置。

pip install mage-space

一览

Mage Python SDK 是 Mage API 的官方开源客户端,包名为 mage-space。用 "pip install mage-space" 安装,设置 MAGE_API_KEY,再用模型 ID 和配置调用 mage.run,即可从 37 个模型中的任意一个获得成品图片、视频或音频。它支持 Python 3.10 或更高版本,每次生成都用 Gems 付费。

  • 3.10+Python
  • httpxHTTP 客户端
  • 37类型化模型
  • MIT开源

设置

安装 Python SDK 并运行模型

  1. 安装软件包

    将 mage-space 添加到你的项目中。

    pip install mage-space
  2. 设置 API 密钥

    在 mage.space 的 API → API Keys 中创建密钥并导出。客户端会读取 MAGE_API_KEY。

    export MAGE_API_KEY="mage_sk_..."
  3. 生成

    用模型 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-v4",
    })
    
    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 帮你搞定的事

  • 一次调用,直接得到成品

    run 会提交生成任务,按 API 推荐的退避间隔轮询,并在完成后返回包含 result.url 的请求结果。

  • 重试不会重复扣费

    每次提交都带有幂等键。遇到网络错误和服务器错误时会按退避策略重试,重试的提交不会被再次扣费。

  • 一次调用完成上传

    对于太大而无法用 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()实时模型目录,含选项和价格。

模型

从这些模型开始

  • 图片 · 37 Gems 起

    Guava API

    逼真到可以乱真的摄影级画质

  • 图片 · 42 Gems 起

    Mango API

    我们的旗舰图片系列

  • 图片 · 51 Gems 起

    Nano Banana 2 API

    文字锐利清晰,最高支持 4K

  • 视频 · 618 Gems 起

    Cherry API

    我们的旗舰视频系列

  • 视频 · 245 Gems 起

    Lemon API

    视频功能一应俱全,价格更亲民

  • 音频 · 19 Gems 起

    Seed Audio API

    一条提示词,生成人声、音乐和音效

常见问题

常见问题解答

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

用 Mage 开始开发

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

Characters社区