国内要用gpt-image-2生图，必用代理站。Hermes原生的 OpenAI provider 又不能自定义 base_url，没办法只能自己手搓一个。

起因

最近在用 Hermes Agent 搭建自动化内容生产系统，需要图片生成能力。Hermes 自带了 OpenAI 的 image gen provider，但有一个硬伤 —— base_url 是写死的，只能走 https://api.openai.com/v1。

国内无法直连 OpenAI，必须走代理站。但Hermes原生的 openai 插件不能改 base_url，花银子充代理站在Hermes Agent里也不能用 gpt-image-2 生图。

方案

Hermes 的插件体系支持通过 ctx.register_image_gen_provider() 注册自定义的 image gen provider。插件的核心是一个继承 ImageGenProvider 的类，实现 generate() 方法即可。

我需要的是一个 可配 base_url 的 OpenAI 标准 Images API 适配器：

需求	解法
支持任意代理站	从 config.yaml 读取 base_url
任意分辨率	检测到 “WxH” 格式直接使用
图生图	本地路径自动转 base64 Data URI

实现

插件结构很简单，两个文件：

image_gen/gpt-image-2/
├── plugin.yaml      # 元数据
└── __init__.py      # 核心代码

plugin.yaml

name: gpt-image-2
version: 1.0.0
description: "Generic OpenAI-compatible image generation provider"
kind: backend

配置读取

配置走三层优先级：config.yaml > 环境变量 > 默认值。

def _resolve_api_key() -> Optional[str]:
    cfg = _load_config()
    raw = cfg.get("api_key")
    if isinstance(raw, str) and raw.strip():
        return raw.strip()
    env = os.environ.get("GPT_IMAGE_2_API_KEY", "").strip()
    if env:
        return env
    return None

base_url 同理，没有硬编码，完全由外部配置决定。

自定义尺寸

原生 openai 插件只认 landscape / portrait / square 三个预设。我加了一步检测：如果 aspect_ratio 包含 x，直接当分辨率传。

aspect_input = aspect_ratio or "square"
if "x" in aspect_input.strip().lower():
    size = aspect_input.strip().lower()   # 如 "1920x1080"
else:
    size = _SIZE_MAP.get(aspect_input, "1024x1024")  # 走预设映射

图生图与本地文件支持

图生图的核心是把 image_url 传给 API。但如果传的是本地路径，API 不认。解决方案：自动转 Data URI。

if image_url and not image_url.startswith(("http://", "https://", "data:")):
    p = Path(image_url)
    if p.exists():
        b64 = base64.b64encode(p.read_bytes()).decode("ascii")
        ext = p.suffix.lstrip(".").lower() or "png"
        image_url = f"data:image/{ext};base64,{b64}"

参考图（reference_image_urls）也是同样的处理逻辑。

完整请求

payload = {
    "model": model_id,
    "prompt": prompt,
    "size": size,
    "n": 1,
}
if image_url:
    payload["image"] = image_url
if ref_images:
    payload["reference_images"] = ref_images

resp = requests.post(f"{base_url}/images/generations",
    headers=headers, json=payload, timeout=300)

使用方式

配置

image_gen:
  provider: gpt-image-2
  gpt-image-2:
    api_key: sk-xxx
    base_url: https://你的代理站.com/v1
    model: gpt-image-2

或者用 hermes tools 配环境变量。

文生图

# Agent 调用
image_generate(prompt="一只猫", aspect_ratio="landscape")

图生图（风格转换）

image_generate(
    prompt="改成赛博朋克风格",
    image_url="/path/to/source.png"
)

自定义分辨率

image_generate(
    prompt="高清城市天际线",
    aspect_ratio="1920x1080"
)

验证

实际测试结果：

• 文生图：一次通过
• 图生图：本地文件路径自动转 Data URI，API 正常返回
• 自定义分辨率：传 1920x1080 正确生成对应尺寸图片
• 切换代理站：改 base_url 即可，不改代码

收尾

说到底就一件事：原生 OpenAI provider 不能自定义 base_url。一个插件把 OpenAI 协议、可配 base_url、自定义尺寸、图生图凑齐了，300 行代码搞定。

山不转路转，路不转我转。API 不转我就转插件。

---

项目地址：https://github.com/xing006/hermes-image_gen-plugin