Mage API · 为你的下一个创意而生

一个 API,无限可能。

把 Mage 的强大能力带到你的产品和 AI 助手中。只需一个 API 密钥或一次 MCP 连接,就能生成图片、视频和音频。

获取 API 密钥连接你的助手阅读 API 文档
https://api.mage.space/v1

一览

Mage 为开发者提供位于 https://api.mage.space/v1 的 REST API,以及位于 https://mcp.mage.space/mcp 的远程 MCP 服务器。两者在同一个账号下运行相同的 28 个图片、视频和音频模型,包括 Mage 独家的 Mango 3 和 Cherry 2 Pro,每次生成都用 Gems 付费,无需订阅。

接入方式

通过代码、AI 助手或 ComfyUI 调用

REST API

Mage API

用密钥在你自己的代码中提交生成任务。支持异步请求、幂等重试、最大 100 MB 的上传,以及 20 个任务同时进行。

SDK

TypeScript 和 Python SDK

官方类型化客户端,几行代码即可提交任务、等待结果、安全重试并上传文件。

MCP 服务器

Mage MCP 服务器

登录即可连接 Claude、ChatGPT、Claude Code、Grok 或 Cursor,用日常语言就能生成图片、视频和音频。

ComfyUI

适用于 ComfyUI 的 Mage

Mango、Cherry、Seed Audio 以及 Mage 的所有其他模型,都以 ComfyUI 节点的形式提供。无需 GPU,无需下载模型。

按媒体类型

生成 API

15 个模型

AI 图片生成 API

文生图、图片编辑,以及最高 4K 的角色一致性生成。

12 个模型

AI 视频生成 API

文生视频、图生视频、帧控制、参考图和声音。

1 个模型

AI 音频生成 API

通过提示词生成人声、旁白、音乐和音效。

快速开始

你的第一次生成

在 API → API Keys 中创建密钥,将其导出为 MAGE_API_KEY,然后运行以下任意一段代码。

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/mango/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Editorial portrait in soft daylight, 35mm film look",
  "aspect_ratio": "4:5",
  "model_id": "mango-v3"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $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"])

工作原理

从 API 密钥到成品,只需三次调用

所有模型共用一套认证方式、一套异步请求流程和相同的字段名称。

  1. 创建 API 密钥

    登录 Mage,打开 API → API Keys 并创建密钥。密钥以 mage_sk_ 开头,只显示一次。每个账号最多可以有 10 个有效密钥。

  2. 提交生成任务

    携带 Authorization: Bearer 请求头,向 https://api.mage.space/v1/{model}/generate 发送 JSON 格式的 POST 请求。接口会立即返回 request_id、status 和 status_url。请附上 Idempotency-Key 请求头,这样重试时不会重复扣费。

  3. 轮询并下载

    持续轮询 status_url,直到状态变为 completed、failed 或 cancelled。请求完成后,result.url 会提供图片、视频或音频文件,文件保留 30 天。

MCP

在 AI 助手中使用 Mage

在 Claude 中使用 Mage

在网页版、桌面应用、手机应用和 Cowork 的 Claude 中生成图片、视频和音频。

在 ChatGPT 中使用 Mage

以个人 MCP 应用的方式,在 ChatGPT 中生成图片、视频和音频。

Claude Code 中的 Mage

在终端和编辑器的 Claude Code 中生成图片、视频和音频。

Grok 中的 Mage

通过自定义连接器,在 Grok 中生成图片、视频和音频。

Cursor 中的 Mage

在 Cursor 的 Agent 模式中生成图片、视频和音频。

模型

精选模型

图片 · 40 Gems 起

Flux 2 API

支持长提示词和多参考图编辑

图片 · 9 Gems 起

GPT Image 2 API

提示词理解精准,文字清晰可读

图片 · 37 Gems 起

Guava API

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

图片 · 135 Gems 起

Mango API

我们的旗舰图片系列

图片 · 68 Gems 起

Nano Banana 2 API

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

视频 · 618 Gems 起

Cherry API

我们的旗舰视频系列

视频 · 245 Gems 起

Lemon API

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

视频 · 338 Gems 起

Plum API

每段视频都带声音,最高支持 2K

音频 · 19 Gems 起

Seed Audio API

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

为生产环境而生

每个 Mage API 请求都享有

一个密钥,通用所有模型

28 个图片、视频和音频模型,共用一个 REST API 和一个 Gems 余额。只需更改 URL 路径即可切换模型。

按生成次数付费

无需订阅,也没有最低消费。你购买 Gems,每次请求按标价扣费。生成失败会退还 Gems,但因违反 Mage 内容政策而被拦截的除外。

安全重试

借助幂等键,重试提交时会返回原始请求,不会重复扣费。

角色保持一致

只需保存一次角色或参考图,之后在任意提示词中写下 @handle,即可在所有支持的模型中使用。

支持大文件输入

可通过 URL 或 data URL 传入图片、视频和音频,也可通过签名上传方式上传最大 100 MB 的文件。

同时处理 20 个生成任务

每个账号可同时运行 20 个生成任务,并可根据你的使用场景提高上限。被拒绝的请求不会扣费。

常见问题

常见问题解答

什么是 Mage API?

Mage API 是位于 https://api.mage.space/v1 的 REST API,可让你在自己的代码中调用 28 个模型来生成图片、视频和音频。请求为异步处理,按每次生成以 Gems 付费。

什么是 Mage MCP 服务器?

这是位于 https://mcp.mage.space/mcp 的远程 Model Context Protocol 服务器,可让 AI 助手在你的 Mage 账号上生成图片、视频和音频。它为助手提供 16 个工具,用于选择模型、报价、生成、等待结果,以及使用你保存的角色、参考图和历史记录。

使用 MCP 服务器需要 API 密钥吗?

不需要。Claude、ChatGPT、Grok、Cursor 和 Claude Code 通过 OAuth 登录 Mage 即可连接。API 密钥是可选的,适用于 CI 等无界面环境。

Mage API 的费用是多少?

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

使用 API 需要 Mage 会员吗?

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

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

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

速率限制是多少?

一个账号最多可同时有 20 个生成任务处于排队或运行中。超出后提交会被以 429 拒绝,且不会扣费。如需根据你的使用场景提高上限,请发邮件至 [email protected]。

我的 AI 智能体可以使用 Mage API 吗?

可以。智能体可以使用密钥调用 REST API,也可以连接 Mage MCP 服务器,它为 Claude、ChatGPT、Claude Code、Grok 和 Cursor 提供十六个现成工具,用于选择模型、查询价格、生成内容以及获取结果。详见MCP 服务器。

Mage API 有 SDK 吗?

有。npm 上的官方 @mage-space/sdk 包和 PyPI 上的 mage-space 均为开源,并为每个模型提供了类型定义。它们会替你提交任务、等待结果、安全重试并上传文件。ComfyUI 用户可以安装 comfyui-mage 节点包。详见Mage SDK。

我已经在用其他生成 API 了,需要改哪些地方?

将你的客户端指向 https://api.mage.space/v1,把 Mage 密钥作为 Bearer 令牌发送,并按模型页面映射你的字段:prompt、aspect_ratio、resolution、duration 和 model_id 在所有 Mage 模型中的用法一致。请求是异步的,所以先提交,再轮询 status_url。

用 Mage 开始开发

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

获取 API 密钥连接你的助手

相关内容