这是一份面向 Hermes Agent 用户和插件作者的实践指南，说明如何把通过 OpenAI Responses 兼容接口提供的 gpt-image-2 接入 Hermes 的 image_generate 工具。
本项目是纯文档仓库，不提供托管服务，也不包含 API Key、用户配置、生成图片或原始响应。文中示例使用 Maitokens 作为已经验证的兼容端点，但方法也适用于返回相同 Responses 图片结构的其他服务。
Hermes 的聊天模型和图片模型是两套独立配置：
用户请求画图
-> Hermes image_generate 工具
-> image_gen provider 插件
-> POST /v1/responses
-> output[].image_generation_call.result
-> Base64 解码并保存图片
不要把图片模型写进 Hermes 的普通 model.default 或聊天 provider 配置。正确入口是一个 ImageGenProvider 后端插件，以及 config.yaml 中独立的 image_gen 配置。
截至 2026-07-21，我们实际验证了以下链路：
- API 模型 ID：
gpt-image-2 - Base URL：
https://wcf.maitokens.com/v1 - 请求端点：
POST /responses - 最小请求体只包含
model和input - 图片位于
output[]中type == "image_generation_call"的result字段 result是 Base64 编码的 PNG- Hermes 用户插件能够把图片保存到本地，并通过真实
image_generate工具完成文生图
尚未验证的能力：
- 图片编辑和参考图输入
- 流式图片响应
- 一次生成多张图
- 自定义尺寸、质量和压缩参数
- Maitokens 对协议的长期兼容保证
因此，示例插件只声明文生图能力。不要在未验证请求格式前对外宣称支持图片编辑。
- 确认 API Key 所属账户或分组有图片生成权限。
- 用脱敏的
curl请求验证/v1/models和/v1/responses。 - 在
~/.hermes/plugins/image_gen/<provider-name>/创建图片后端插件。 - 将 API Key 只写入当前 Hermes profile 的
.env。 - 在
config.yaml中启用插件，并把image_gen.provider指向它。 - 新开 Hermes 会话，通过
image_generate进行真实端到端测试。
完整命令、插件代码和返回结构见上面的文档链接。
本仓库记录了两类信息：
- Hermes 插件目录、
ImageGenProvider接口和配置方式来自 Hermes 官方文档。 - Maitokens 请求与响应格式来自实际兼容性测试，不代表 Maitokens 官方长期承诺。服务端行为变化时，应重新执行验证步骤。
响应中可能出现内部模型名称，例如 gpt-image-2-codex。客户端请求仍应使用模型列表中公开的 gpt-image-2，不要依赖内部名称。
- 不要把真实 API Key 放进 README、代码、命令历史、Issue、日志或 Git 历史。
- 不要提交
.env、原始响应、Base64 图片数据和用户的config.yaml。 - 示例统一使用
YOUR_API_KEY和环境变量。 - 发布前应扫描整个工作树和 Git 历史。
详见安全与回滚。
This repository documents how to connect an OpenAI Responses-compatible gpt-image-2 endpoint to Hermes Agent through a user-local image generation provider plugin.
The documented Maitokens endpoint was verified with text-to-image requests. The guide covers the request and response contract, Hermes plugin structure, configuration, end-to-end verification, troubleshooting, and rollback. It contains documentation only and no credentials, generated images, private configuration, or raw API responses.
文档使用 CC BY 4.0 许可。引用或改编时请保留来源说明。