Mage-Flow RL 文生图 API

镜像简介

这是一个基于 Microsoft Mage-Flow RL 的文生图 API 镜像，预装模型、运行环境和带鉴权的 HTTP API。实例启动后服务会自动运行，适合受控的图片创作、批量生成和工作流集成。

已预装内容

• Mage-Flow RL 正式文生图模型
• Python 3.12.11
• PyTorch 2.13.0 + CUDA 13.2
• FastAPI / Uvicorn API 服务
• 开机自启脚本
• 运行时临时 API 令牌

当前版本仅包含文生图模型，不包含 Mage-Flow-Edit，因此不提供图片编辑能力。

环境与端口

• 已验证 GPU： RTX 4090 24GB
• 支持卡型： RTX 40 系列（显存建议不低于 24GB）
• API 端口： 8000
• JupyterLab 端口： 8888
• 镜像展示版本： v1.0
• 服务内部版本： 1.0.0

快速使用

1. 部署实例

使用本镜像部署一张 RTX 4090，等待实例显示“运行中”。API 会由镜像内的自启动脚本自动启动，无需重新安装依赖或下载模型。

2. 检查服务

在 JupyterLab 终端中执行：

curl -s http://127.0.0.1:8000/health

正常情况下会看到 "status":"ok"、"ready":true 和 GPU 名称。

也可以点击实例页面中的“应用端口：8000”，然后在地址末尾添加 /health 验证外网访问。

3. 获取本次启动的临时令牌

cat /run/mage-flow/api_token

每次实例启动时都会生成新令牌。令牌不会固化在镜像中。请勿公开、截图或分享令牌。

4. 调用文生图 API

TOKEN="$(cat /run/mage-flow/api_token)"

curl -sS --max-time 1800 \
  -X POST http://127.0.0.1:8000/v1/images/generations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "one red paper circle centered on a clean neutral background",
    "negative_prompt": "text, watermark, multiple objects",
    "width": 768,
    "height": 1360,
    "steps": 20,
    "cfg": 6.0,
    "seed": 42,
    "response_format": "url"
  }'

外部调用时，将 http://127.0.0.1:8000 替换为平台“应用端口：8000”分配的 HTTPS 基础地址。生成结果的图片下载地址同样需要携带 Authorization: Bearer <token>。

如果不希望二次下载图片，可将 response_format 改为 b64_json。

API 说明

无需鉴权

• GET /health — 健康状态
• GET /version — 服务、代码和模型版本

需要 Bearer 鉴权

• POST /v1/images/generations — 文生图
• GET /outputs/{filename} — 下载生成图片

生成参数限制

• width / height：512–2048，必须能被 16 整除
• steps：1–60，RL 版推荐 20
• cfg：0–20
• seed：非负整数
• response_format：url 或 b64_json

性能说明

在 RTX 4090 24GB、768×1360、20步的实测中：

• 新实例首次加载模型并出图约 2–3 分钟
• 模型完成预热后，同规格生成约 7–9 秒/张

实际耗时会受 GPU 型号、分辨率、步数和平台当时负载影响。首次请求期间可能暂无中间进度输出，请勿重复提交。

安全与费用

• 镜像不包含固定 API 令牌、Hugging Face 令牌、测试图片或历史输出。
• 生成端点和图片下载端点默认开启 Bearer 鉴权。
• 不再生成时，请关闭或销毁 GPU 实例，避免继续产生算力费用。
• 生成内容应由人工审核，不得用于违法、侵权、欺诈或其他滥用场景。

许可证与来源

• Mage-Flow 代码：Microsoft Mage，MIT License
• Mage-Flow RL 模型：Microsoft Mage-Flow，MIT License
• 镜像内保留了上游 LICENSE 和 THIRD_PARTY_NOTICES.md

相关链接：

• Microsoft Mage：https://github.com/microsoft/Mage
• Microsoft Mage-Flow：https://huggingface.co/microsoft/Mage-Flow
• 模型镜像来源说明：https://huggingface.co/SceneWorks/Mage-Flow

常见问题

为什么第一张图比较慢？

实例启动后首次请求需要将模型加载到 GPU 显存。后续请求会复用已加载的模型。

为什么重启后旧令牌无法使用？

这是预期的安全行为。每次实例启动都会生成新令牌，请重新读取 /run/mage-flow/api_token。

如何查看日志？

tail -n 100 /root/mage-flow-rl/logs/api.log

如何停止或重启 API？

/root/mage-flow-rl/stop.sh
/start.d/90-mage-flow-api.sh

本镜像是实验性创作工具，使用时请遵守平台规则、上游许可证和适用法律。