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 并运行模型
安装软件包
将 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-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() | 实时模型目录,含选项和价格。 |
模型
从这些模型开始
Guava API
逼真到可以乱真的摄影级画质
Mango API
我们的旗舰图片系列
Nano Banana 2 API
文字锐利清晰,最高支持 4K
Cherry API
我们的旗舰视频系列
Lemon API
视频功能一应俱全,价格更亲民
Seed Audio API
一条提示词,生成人声、音乐和音效
常见问题
常见问题解答
Python SDK 支持 asyncio 吗?
SDK 支持哪些 Python 版本?
可以在 Notebook 或数据流水线中使用 Python SDK 吗?
Mage SDK 是免费开源的吗?
新的 Mage 模型能在旧版 SDK 上使用吗?
SDK 如何避免重试请求时重复扣费?
SDK 稳定吗?
Mage API 的费用是多少?
使用 API 需要 Mage 会员吗?
API 生成的内容可以商用吗?
用 Mage 开始开发
一个账号,一份 Gems 余额,畅用所有模型。按生成量付费,用多少付多少。