Mage API · 图片生成

支持全部模型的 AI 图片生成 API

文生图、图片编辑和角色一致性,涵盖 15 个模型(包括 Mage 旗舰模型 Mango 3),一个密钥、一份余额即可搞定。

获取 API 密钥阅读 API 文档
POST https://api.mage.space/v1/{model}/generate

一览

Mage 图片生成 API 是位于 https://api.mage.space/v1 的 REST API,可运行 15 个文生图和图片编辑模型,包括 Mango 3、Guava 2 Pro、GPT Image 2.5、Nano Banana 2、Flux 2 和 Krea 2。你向 /{model}/generate 提交 prompt(POST),轮询请求状态,然后下载图片。每张图片用 Gems 支付,无需订阅。

模型

Mage API 中的所有图片模型

价格按每次生成计算,以 Gems 计价。标准包 1,000 Gems 售价 $1,更大的套餐还会赠送额外 Gems。价格取决于模型、分辨率和时长;此处显示的是默认设置下的价格,每个响应都会在 billing.gems_charged 中给出实际扣费。生成失败会退还 Gems;因 Mage 内容政策被拦截的则不退还。

模型最适合model_id 取值默认价格
Anima专为动漫打造anima-v120 Gems ($0.02)
Chroma开放权重,基于 Flux 构建chroma-v1-hd35 Gems ($0.035)
Flux 2长提示词和多参考图编辑flux2-dev40 Gems ($0.04)
GPT Image 2精准遵循提示词,文字清晰可读gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst9 Gems ($0.009)
Grok ImageGrok Imagine,分三档画质grok-imagine-image, grok-imagine-image-quality, grok-imagine-image-2.075 Gems ($0.075)
Guava以假乱真的照片级写实guava, guava-pro, guava-pro-v1-5, guava-2, guava-2-pro37 Gems ($0.037)
HiDream快速多能,支持负面提示词hidream-fast20 Gems ($0.02)
Krea 2几秒钟生成惊艳美图krea-2-turbo20 Gems ($0.02)
Mango我们的旗舰图片系列mango, mango-v2, mango-v3s, mango-v3, mango-v3-turbo135 Gems ($0.135)
Nano Banana 2文字清晰锐利,最高 4Knano-banana-v268 Gems ($0.068)
SDXL Plus修复了面部和手部的 SDXL6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8015 Gems ($0.015)
Stable Diffusion v1.5经典之选,经济实惠15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D10 Gems ($0.01)
Stable Diffusion v3.5 Large最听话的 Stable Diffusionsd-3-5-large10 Gems ($0.01)
Stable Diffusion XL针对照片级写实调优的 SDXL6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B8010 Gems ($0.01)
Z-ImageMage 上最快的图片模型z-image-turbo10 Gems ($0.01)

快速开始

使用 Anima v1 生成图片

设置 MAGE_API_KEY,提交请求,然后轮询直到完成。把 URL 中的 anima 换成上面任意一个模型即可。

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/anima/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": "anima-v1"
}' | 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('anima', {
  prompt: 'Editorial portrait in soft daylight, 35mm film look',
  aspect_ratio: '4:5',
  model_id: 'anima-v1',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("anima", {
    "prompt": "Editorial portrait in soft daylight, 35mm film look",
    "aspect_ratio": "4:5",
    "model_id": "anima-v1",
})

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 天。

为生产环境而生

每个 Mage API 请求都享有

一个密钥,通用所有模型

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

按生成次数付费

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

安全重试

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

角色保持一致

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

支持大文件输入

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

同时处理 20 个生成任务

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

使用场景

开发者用图片 API 做什么

产品图和营销图片

按需生成产品图、广告变体和社交媒体帖子,借助 GPT Image 2.5 或 Nano Banana 2 让文字清晰可读。

角色保持一致

只需保存一次角色,就能用 Mango 3、Guava 2 Pro 以及其他支持 @handle 提及的模型,让整套图片保持同一张脸。

图像编辑流水线

发送原图并附上指令,只修改你指定的内容,其余部分保持不变。

应用与游戏

无需自己部署任何 GPU,就能在产品内生成头像、贴纸、卡片和场景。

写实人像

Guava 2 Pro 能渲染人像、时尚和生活方式照片,肌肤、面料和光线都逼真自然。

大批量快速出稿

Z-Image Turbo 和 Krea 2 价格低廉,适合大批量缩略图和初稿生成。

常见问题

常见问题解答

最好的 AI 图像生成 API 是什么?

这要看具体任务。在 Mage 上,Mango 3 是大多数图像的默认模型:它能准确遵循指令,保持角色一致,编辑时不会影响图像的其余部分。Guava 2 Pro 最适合写实风格,GPT Image 2.5 和 Nano Banana 2 适合生成含文字的图像,Z-Image Turbo 或 Krea 2 则适合快速、低成本的草稿。所有模型都通过同一个 API 调用。

图像 API 支持图像编辑和参考图吗?

支持。接受图像输入的模型可通过 image 和 additional_images 字段传入图像,格式可以是 URL、data URL 或上传文件。每个模型页面都列出了它的输入项以及可使用的参考图数量。

图像 API 支持哪些分辨率?

因模型而异:大多数模型支持 1K 和 2K,Mango 3S 支持 3K,Mango 2 和 Nano Banana 2 最高支持 4K。每个模型页面都列出了可选的分辨率和宽高比。

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 密钥阅读 API 文档

相关内容