统一生图网关 Unified Image Gateway

把多个免费 / 低价的在线生图渠道集成到一个本地入口：

• 对 AI Agent / 程序：暴露 OpenAI 兼容的本地 API，像调普通生图接口一样用，底层自动在各渠道间切换、故障转移。

• 对人：提供网页控制台，手动选渠道、多渠道并排对比。

• 另提供 CLI 命令行。

• 会话化存档：生成/上传的图片统一保存在一个资源目录、按会话分子目录；历史记录可按提示词搜索、多维度排序、一键用原参数重生成。

• 本机与云服务器都能部署（直跑 / Docker / Nginx 反代 / systemd 常驻）。

• 不需要本地部署任何大模型，全部调用在线服务。

1. 快速开始

cd image-gateway
pip install -r requirements.txt
cp config.example.yaml config.yaml      # 按需填入各渠道 key（不填也有免费通道）
python -m imggen.server                 # 或 ./run.sh

打开：

• 网页控制台： http://127.0.0.1:8799/

• 接口文档： http://127.0.0.1:8799/docs

开箱即用的免费通道是 pollinations（无需 key）。其余渠道在 config.yaml 填 key 后启用，改完配置执行 POST /admin/reload 热加载，无需重启。

管理接口安全：/admin/reload 若配置了 server.admin_token（或环境变量 ADMIN_TOKEN），需带请求头 X-Admin-Token；未配置时仅允许本机回环调用。所有图片统一归档到 server.storage_dir，按会话分子目录（见第 3 节）。

Related MCP server: MCP Image Generator

2. 给其他 AI Agent 调用（核心）

端点对齐 OpenAI Images API（/v1/images/generations、/v1/models，请求/响应字段一致），把 base_url 指向本地即可。另在响应里附带 provider、chain_order、tried_before 等便于排障的扩展字段。

curl

# 自动链：按 config 里 default_chain 顺序，免费渠道优先，失败自动换
curl -X POST http://127.0.0.1:8799/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一只穿西装的柯基","size":"1024x1024"}'

# 指定渠道
-d '{"prompt":"...","model":"gemini"}'

# 自定义故障转移顺序（逐个尝试直到成功）
-d '{"prompt":"...","model":["pollinations","gemini","siliconflow/black-forest-labs/FLUX.2-flex"]}'

Python（openai SDK，只改 base_url）

from openai import OpenAI
c = OpenAI(base_url="http://127.0.0.1:8799", api_key="not-needed")
r = c.images.generate(model="auto", prompt="your prompt", size="1024x1024")
# r.data[0].b64_json

请求参数

n 单次最多 8；未知模型等 4xx 语义会返回对应 4xx 状态码，通道侧故障才返回 502。无论 b64/url，图片都会归档进当前会话。

返回（OpenAI 格式 + 扩展字段）：

{ "object": "list", "created": 0, "provider": "pollinations", "model": "pollinations",
  "session_id": "default",
  "data": [ {"b64_json": "...."} ],
  "chain_order": ["pollinations"], "tried_before": [] }

MCP（Model Context Protocol）接入

网关同时暴露 MCP 接口，Claude Desktop、Cursor、Cline、VS Code Copilot、Windsurf 等支持 MCP 的 agent 客户端可直接把生图当工具调用。

工具列表：generate_image、list_sessions、list_history、get_providers、configure_provider、test_provider。

两种传输：

1. Streamable HTTP（推荐，与网关同进程）：网关启动后即挂载在 http://127.0.0.1:8799/mcp，客户端配置 URL 即可。

2. stdio（本地客户端拉起子进程）：

   python -m imggen.mcp_server

   环境变量 IMGGW_BASE_URL 指定网关地址（默认 http://127.0.0.1:8799），ADMIN_TOKEN 用于写配置类工具。

MCP 调用会自动带 X-Transport: mcp 和客户端名，统一记入「接入方与日志」。

客户端配置样例（Claude Desktop / Cursor / Cline 等的 mcpServers）：

{
  "image-gateway-http": {
    "url": "http://127.0.0.1:8799/mcp"
  },
  "image-gateway-stdio": {
    "command": "python",
    "args": ["-m", "imggen.mcp_server"],
    "env": { "IMGGW_BASE_URL": "http://127.0.0.1:8799" }
  }
}

二选一即可；HTTP 模式要求网关已在运行，stdio 模式由客户端拉起子进程（网关仍需单独运行）。

3. CLI

python -m imggen.cli models                       # 全部渠道及可用状态
python -m imggen.cli "水墨山水"                    # 走默认链
python -m imggen.cli "赛博城市" -p gemini          # 指定渠道
python -m imggen.cli "猫" -p pollinations,gemini   # 顺序 fallback
python -m imggen.cli "猫" --size 768x512 -o c.png  # 指定尺寸/额外复制
python -m imggen.cli "猫" -s myproj                # 归档到指定会话
python -m imggen.cli serve                         # 启动网关

4. 已内置渠道

key 也可用环境变量提供：GEMINI_API_KEY、DASHSCOPE_API_KEY、 SILICONFLOW_API_KEY、OPENAI_API_KEY、HF_TOKEN、BING_COOKIE_U。

渠道总览与在线配置（不必手改 yaml）

• 网页控制台 →「渠道管理」：顶部数字卡汇总「可用 / 未配置 / 冷却 / 总数」， 每个渠道一张卡，显示状态点、类型（免费/免费额度/低价/付费/中转）、默认模型、 模型列表、所需凭证；可直接填 key、选默认模型、拨动启用开关，保存即热加载生效 （自动写回 config.yaml；凭证框留空表示不修改，不会覆盖已填值）。「自检」按钮 做不消耗额度的可用性检查。

• API：

  • GET /v1/providers：渠道状态汇总（凭证只回「是否已设置」，不回明文）；

  • POST /v1/providers/config：在线写回配置，body {"updates":{"gemini":{"api_key":"...","enabled":true}}}；

  • POST /v1/providers/{name}/test：轻量自检。

• 写配置属于管理操作：配置了 admin_token 时需带 X-Admin-Token 头；未配置时仅本机回环放行。

历史记录里每条都显著标注是哪个第三方渠道出的图（如 pollinations / gemini）， 「生成 / 上传」仅作为次要动作标签。

5. 自动模式（优先列表，依次尝试直到一个可用）

请求时 model 传 "auto"（或不传）即进入自动模式。优先列表这样生成：

1. config.yaml 的 server.default_chain 作为显式优先骨架，按你写的顺序排前面；

2. 其余当前可用（免费或已填凭证）的通道自动补到后面、免费优先——新配渠道 不用手动加列表也会被自动模式用到；

3. 不可用（未启用/缺 key）的通道直接剔除，不做无意义尝试；

4. 刚失败的通道进入约 30 秒冷却，自动排到最后。

config.yaml 中：

server:
  default_chain: [pollinations, gemini, siliconflow, bailian]

执行时按列表逐个尝试：某个渠道报错 / 超时 / 限流就自动切下一个，直到一个成功； 全部失败才返回错误并附每个渠道原因。返回带 chain_order（本次尝试顺序）和 tried_before（成功前试过哪些）。查看当前自动链：GET /v1/chain。 建议把免费渠道排前面、付费渠道兜底。

6. 多渠道对比

• 网页控制台「多渠道对比」标签：勾选多个渠道，同一 prompt 并发出图、并排查看下载。

• 接口：POST /v1/images/compare，model 传数组。对比结果同样归档到当前会话。

7. 数据与文件保存（图 / 历史存哪）

所有图片统一保存在 server.storage_dir（默认项目下 storage/，云上建议指向数据盘绝对路径），按会话分子目录：

storage/sessions/<session_id>/
├── meta.json                 # 会话标题、创建时间
├── history.jsonl             # 每行一条记录（JSON）
└── images/
    ├── gen_xxxx.jpg          # 生成的图（gen_ 前缀）
    └── up_xxxx.png           # 上传的图（up_ 前缀）

history.jsonl 每条记录包含：时间戳、来源（generate/upload）、prompt、负向词、尺寸、n、seed、生成渠道 provider、文件名列表、字节数。可直接 grep / 用程序解析。

会话与历史相关接口：

sort 可选：ts_desc/ts_asc、provider_asc/provider_desc、size_desc/size_asc、n_desc/n_asc。网页控制台「历史」标签提供搜索框、排序下拉、缩略图预览（点击放大）、下载与「用此参数重生成」。

会话内容是你的资产，程序不会自动删除；如需清理，直接删除对应会话目录即可。

8. 部署到云服务器（本机 / 云一致）

代码本身跨平台，本机与云服务器同一套。云端对外提供按下面任一方式，上线前对照安全清单。

方式 A：直接运行

pip install -r requirements.txt
# config.yaml: host 改 0.0.0.0，设置 admin_token；云安全组放行 8799
python -m imggen.server

方式 B：Docker（推荐，数据用卷持久化）

docker build -t image-gateway .
docker run -d --name imgw -p 8799:8799 \
  -e ADMIN_TOKEN=change-me \
  -v /data/imgw:/data image-gateway

方式 C：Nginx + systemd（域名/HTTPS 常驻，生产推荐）

• deploy/nginx.conf.example：反代示例，已处理 X-Forwarded-* 与 SSE；

• deploy/image-gateway.service.example：开机自启、崩溃自动重启。

• 此时 config.public_base_url 可填 https://你的域名，forwarded_allow_ips 按需放开。

云端安全清单

1. 务必设置 admin_token（或 ADMIN_TOKEN），否则管理接口在对外时不可用/仅本机；

2. 云安全组只放行必要端口，优先用 Nginx + HTTPS 对外、网关本身不直接暴露；

3. 各渠道 key 优先用环境变量注入，不写进会随包带走的 config.yaml；

4. storage_dir 指向可持久化/可备份的数据盘，避免容器重建丢图。

9. 扩展一个新渠道（开发者）

1. 在 imggen/providers/ 新建文件，继承 BaseProvider，实现 available() 与 _generate_once()（返回 list[bytes]）。

2. 在 imggen/registry.py 的 _build() 中实例化。

3. 在 config.example.yaml 增加对应配置。

OpenAI 兼容的新渠道无需写代码：直接在 openai_compatible 下加一个子项， 填 base_url / key / models 即可。

10. 注意事项

• 免费通道都有速率/配额约束：限流（429 / ZeroGPU quota）时网关会自动切换或稍后重试；稳定批量生产建议配一个低价 API（硅基流动 / 百炼）。

• 网页逆向通道（perchance / bing）依赖对方前端结构，可能随官网更新失效，属尽力而为。

• 商用版权：多数免费生成渠道未明确授予商用版权，对客户交付的关键素材请走有商用授权的付费渠道。

• 本服务默认只监听 127.0.0.1；若要让局域网/其他机器调用，把 server.host 改为 0.0.0.0，并自行做好访问控制。

目录结构

image-gateway/
├── run.sh
├── Dockerfile
├── requirements.txt
├── config.example.yaml
├── imggen/
│   ├── config.py          # 配置加载 + 环境变量 + 热加载
│   ├── registry.py        # 渠道注册与路由
│   ├── storage.py         # 会话化存储 / 历史检索
│   ├── server.py          # FastAPI 网关
│   ├── cli.py             # 命令行
│   └── providers/         # 各渠道适配器
├── web/index.html         # 网页控制台
├── deploy/                # nginx / systemd 部署示例
└── storage/               # 统一资源根（sessions/<会话>/），运行后生成