Image Gen Hub：一个聚合四大厂商的图片生成客户端

项目地址：https://github.com/MADMAX110/image_gen_hub

写在前面

最近几个月，国内外主流厂商陆续推出了各自的图像生成模型——火山引擎的 Doubao-Seedream、通义的 qwen-image / wan / z-image、Google Vertex AI 的 Gemini Image、Azure OpenAI 的 GPT Image 2……它们各有所长：有的擅长写实摄影、有的更懂中文海报、有的对长文本和复杂构图理解更好。

但作为使用者最痛苦的一点是：每家的 SDK、鉴权、参数、返回格式都不一样。换一个模型就要换一套代码、换一份配置、换一个客户端。

image_gen_hub 就是为了解决这件事而生的——只认 model 名，自动派发到对应供应商，并提供桌面 GUI、Android APK、CLI、Python API 四种使用方式。

一、它能做什么

一行代码切换模型：

from image_gen_hub import ImageHub

hub = ImageHub.from_env()

hub.generate(model="Doubao-Seedream-5.0-lite", prompt="赛博朋克风格的程序员")
hub.generate(model="qwen-image-2.0-pro",       prompt="水墨画里的大学")
hub.generate(model="gemini-3-pro-image-preview", prompt="A vintage magazine cover")
hub.generate(model="gpt-image-2",              prompt="Polish territorial changes diagram")

• 不用关心鉴权头是 Bearer 还是 api-key
• 不用关心返回字段是 url 还是 b64_json
• 不用关心超时、429 退避、Retry-After 解析

二、四种使用形态

项目代码量并不大（核心 Python 约 4100 行），但一鱼四吃覆盖了几乎所有使用场景：

形态	入口	适合谁
桌面 WebView 客户端	python -m image_gen_hub desktop	普通用户，开箱即用
Android APK	./build_android.sh	想在手机上随时出图
命令行	python -m image_gen_hub gen --model ... --prompt ...	脚本/批量场景
Python API	from image_gen_hub import ImageHub	嵌入到自己的应用

桌面端默认用 pywebview，比 Tk 更现代，也保留了 Tk 兜底。前端在 webui_static/ 里是普通的 HTML/CSS/JS，便于二次定制。

三、架构：一个清爽的 Provider 模式

核心调度只有一百来行：hub.py。

PROVIDER_REGISTRY: dict[str, type[BaseProvider]] = {
    "volcengine":    VolcengineProvider,
    "tongyi":        TongyiProvider,
    "vertex_ai":     VertexAIProvider,
    "azure_openai":  AzureOpenAIProvider,
}

ImageHub 启动时根据 config.yaml 里每个供应商的 models 列表，构建 model -> provider 反查表。generate() 时按模型名派发到对应 BaseProvider 子类，归一化返回 GenerateResult(provider, model, images=[ImageArtifact], text, raw)。

新增一个供应商只要四步：

1. 在 providers/ 写一个继承 BaseProvider 的类，实现 generate()
2. 在 providers/__init__.py 导出
3. 在 hub.py 的 PROVIDER_REGISTRY 注册一行
4. 在 config.yaml 的对应 models 里加上模型名

BaseProvider 在父类里把通用的脏活都做掉了：

• 统一的 requests.Session + 超时（连接/读取分别配置）
• 429/5xx 自动退避，识别服务端 Retry-After
• 图片引用归一化（url / b64 / data:image/...;base64,... 三种入参都接受）
• 统一的落盘命名 {provider}_{model}_{时间戳}_{uuid}.png

四、配置：一个 YAML 走天下

所有 API Key、endpoint、模型列表都集中在根目录的 config.yaml，并被 .gitignore 保护：

shared_api_key: ""              # 四家共用一个网关 Key 时填这里

providers:
  volcengine:
    api_key: "sk-xxx"
    endpoint: "https://your-gateway.example/v1/images/generations"
    models:
      - "Doubao-Seedream-5.0-lite"
  azure_openai:
    api_key: "sk-xxx"
    endpoint: "https://your-gateway.example/v1/images/generations"
    models: ["gpt-image-2"]
    timeout: [20, 1800]         # 连接/读取超时（GPT Image 2 排队会很久）
    max_attempts: 4             # 429 / 5xx 重试次数

桌面端右上角「设置」里也能改这些字段，保存后会写回 config.yaml——不用手动编辑也行。

五、几个工程上的细节

Android 端是怎么打包的？

build_android.sh 会自动下载 Gradle 和 Android SDK 到 .android-build/（不污染系统），并把根目录的 config.yaml 转成 android/app/src/main/assets/api_config.json 写进 APK。这意味着密钥不会进 git，但同一份配置可以同时驱动桌面端和 APK。

桌面端怎么变成单文件 exe？

./build.sh（Windows: build.bat）走 PyInstaller，规范文件在 app.spec，入口是极简的 launcher.py。最终用户拿到 dist/ImageGenHub 后，配合 config.yaml 直接跑，不用装 Python。

GPT Image 2 排队几分钟怎么办？

Azure 这边专门做了 timeout: [20, 1800]——连接 20 秒、读取 30 分钟。配合最多 4 次的指数退避重试，并解析 Retry-After 头部，基本能覆盖排队抖动。

六、适合谁

• 想同时使用多家图像 API、又懒得维护多套客户端的开发者
• 想要一个能离线分发给非技术朋友的桌面/手机出图工具的人
• 想以最小代价接入自家网关（统一鉴权 + 路由）的团队——shared_api_key 和 endpoint 字段就是为这个场景准备的

七、上手

git clone https://github.com/MADMAX110/image_gen_hub
cd image_gen_hub
cp config.example.yaml config.yaml      # 填入各家的 Key
./start.sh                               # Linux/macOS 一键启动
# Windows: 双击 start.bat

首次运行会自动建 .venv 装依赖，生成的图片默认落到 pictures/。

---

项目地址：https://github.com/MADMAX110/image_gen_hub

欢迎 Star、Issue、PR。如果你在用别的图像模型且希望接入，按上面「四步」加一个 Provider 就行。