一个给 Hermes 用的图片技能与脚本封装:不需要切会话模型,不需要为图片任务额外适配执行流;默认仍可直接读取本机主配置里的 base_url 和 api_key,也支持图片链路的可选独立覆盖;默认用 gpt-image-2 调用 OpenAI-compatible Images API。
这个仓库的核心目标不是做一个“通用图片工具箱”,而是解决 Hermes 里最常见的实际问题:
- 用户只是随口说一句“帮我生成个图”;
- 不希望先切模型、改 provider、改命令习惯;
- 不希望每次图片任务都临时写一套接口适配;
- 希望代理能直接读取现有 Hermes 配置,然后稳定调用图片接口。
所以这里把图片生成/编辑统一收口到 ~/.hermes/skills/img/scripts/remote_image.py:
- 保持文字主对话继续走当前模型;
- 图片生成/编辑时单独调用图片接口,不污染普通聊天链路;
- 生成图片时优先按 transport 自动选择协议(默认先试
/v1/images/generations,如果该站点生图链路不可用,再回退/v1/responses); - 纯编辑/局部修改走
/v1/images/edits;如果是“参考这张图生成 / 以这张图为参考 / 同风格来一张”这类参考图生成,则走生成链路并优先使用/v1/responses; - 图片相关 base_url / key / model 可独立覆盖,但默认仍可复用 Hermes 主配置。
即使当前对话主模型不是图片模型,这个脚本也会单独发起图片 API 请求。
也就是说,Hermes 处理图片请求时不用先把整场会话切到图片模型,只需要调用:
python3 ~/.hermes/skills/img/scripts/remote_image.py --prompt "..."脚本已经把以下事情封装好了:
- 读取
~/.hermes/config.yaml - 回退读取
~/.hermes/.env - 自动组装 OpenAI-compatible 请求
- 生成模式支持
auto / responses / images / chattransport,默认auto,其中auto会先试/images/generations,再回退/responses - 编辑模式走
/images/edits - 自动把返回的 base64 或 URL 落盘
注意:如果 ~/.hermes/skills/img/ 目录里还有历史遗留的 config.yaml 或备份文件,不要默认把它当成当前生效配置。当前 remote_image.py 的运行时来源仍以 --base-url / --api-key、环境变量、~/.hermes/.env、~/.hermes/config.yaml 为准;排障时应先用 --dry-run --show-resolved 看实际解析结果。
上层技能只需要决定:
- 用户是要生成还是编辑
- 要不要传
--input - 图片尺寸、提示词、返回格式怎么说
仓库里的 SKILL.md 约束了图片任务的默认行为:
- 普通自然语言“生成图片”请求直接走这个技能
- 默认
n=1 - 默认模型是
gpt-image-2 - 不静默切换到别的图片后端
- Telegram 原图需求要走 zip 打包
- 局部文字修复不要整图重绘
- 用户明确说“快速来一张 / 先来一版 / 先看方向”时,应优先走
fast,避免默认落到official-like + quality=high
.
├── SKILL.md
├── README.md
├── requirements.txt
├── scripts/
│ └── remote_image.py
└── fix-localized-text-in-attached-image-with-crop-and-composite/
└── SKILL.md
统一图片生成/编辑入口。
关键行为:
- 默认模型:
gpt-image-2 - 默认尺寸:普通生成如果没有显式
--size,默认省略 size 字段,让 provider 自然决定;显式尺寸仍优先保留 - 生成接口:默认按 transport 自动选择,优先
<base_url>/images/generations,失败再回退<base_url>/responses - 编辑接口:
<base_url>/images/edits - 输出:时间戳目录下的图片文件
- 可选 profile:
official-like/fast/anime-poster/photo-real - 可选 profile:
official-like/fast/anime-poster/photo-real/social-cover - 支持
--show-resolved查看解析后的 profile / size / quality / prompt - 支持
--best-of、--record-run、--archive、--negative-hints、--variant-of
配置读取顺序:
--api-keyOPENAI_API_KEY_IMAGE~/.hermes/.env里的OPENAI_API_KEY_IMAGEOPENAI_API_KEY~/.hermes/.env里的OPENAI_API_KEY~/.hermes/config.yaml中的model.api_key
base_url 默认读取:
--base-urlOPENAI_BASE_URL_IMAGE~/.hermes/.env里的OPENAI_BASE_URL_IMAGEOPENAI_BASE_URL~/.hermes/.env里的OPENAI_BASE_URL~/.hermes/config.yaml中的model.base_url- 若缺失则回退
https://api.openai.com/v1
model 默认读取:
--modelOPENAI_IMAGE_MODEL~/.hermes/.env里的OPENAI_IMAGE_MODEL- 默认
gpt-image-2
这意味着:
base_url不是必须单独配置的- 如果没有设置图片专用
base_url,脚本会继续回退到 Hermes 主配置中的model.base_url - 只有显式设置图片专用覆盖时,图片链路才会与主链路分开
Hermes 主技能说明。
重点不是介绍接口参数,而是规定:
- 哪些请求应该自动走图片技能
- 默认如何控制成本与变体数量
- 如何向用户回报真实使用的模型
- 什么时候不能静默降级
- Telegram 图片如何无损交付
局部修图子技能。
用于“只改一小块字、其他地方别动”的场景,避免整张图被模型重绘。
先安装依赖:
python3 -m pip install -r requirements.txt查看帮助:
python3 ~/.hermes/skills/img/scripts/remote_image.py --help查看可用 profile:
python3 ~/.hermes/skills/img/scripts/remote_image.py --list-profiles --prompt x查看成熟归档与多候选:
python3 ~/.hermes/skills/img/scripts/remote_image.py \
--prompt "做一张 AI 产品发布社媒封面" \
--profile social-cover \
--negative-hints "avoid watermark, avoid unreadable tiny text, avoid busy background behind title area" \
--best-of 3 \
--record-run \
--archive \
--show-resolvedpython3 ~/.hermes/skills/img/scripts/remote_image.py \
--prompt "Create a vertical AI illustration of a livestream host in a neon studio" \
--profile official-like \
--n 1这会默认使用 gpt-image-2,并调用:
<base_url>/v1/images/generations
说明:脚本内部传入的是
/images/generations,而base_url通常已经是.../v1,所以组合后的完整地址就是<base_url>/images/generations,也就是常见的/v1/images/generations。
python3 ~/.hermes/skills/img/scripts/remote_image.py \
--input /path/to/input.png \
--prompt "Only fix the text in the top-right badge; keep everything else unchanged." \
--mode localized-fix \
--profile photo-real \
--show-resolvedpython3 ~/.hermes/skills/img/scripts/remote_image.py \
--prompt "同风格再来一个版本,更有科技感" \
--profile official-like \
--variant-of /abs/path/to/run-record.json \
--record-run如果你想让图片单独走别的上游,可以显式设置:
OPENAI_BASE_URL_IMAGE=https://example.com/v1 \
OPENAI_API_KEY_IMAGE=sk-xxx \
python3 ~/.hermes/skills/img/scripts/remote_image.py --prompt "做一张海报"如果你不设置 OPENAI_BASE_URL_IMAGE,脚本会继续使用主配置中的:
model:
base_url: ...也就是:图片独立 base_url 是可选增强,不是必填项。
推荐作为 Hermes skill 放在:
~/.hermes/skills/img/
├── SKILL.md
├── scripts/
│ └── remote_image.py
└── fix-localized-text-in-attached-image-with-crop-and-composite/
└── SKILL.md
这样代理在收到图片相关请求时,可以:
- 不切模型;
- 不重写接口适配;
- 直接读取本地配置;
- 默认用
gpt-image-2发图像请求; - 再把结果回传到 Telegram 或其他渠道。
--best-of N:显式多候选,不默认开启--record-run:保存run-record.json- 更细尺寸策略:支持 banner / wallpaper / social-cover 倾向
- 错误分类:stderr JSON 会附带
error_type
--mode generate|edit|localized-fix--variant-of /path/to/run-record.json--compat-fallback:仅丢弃可选字段做一次兼容性重试- 局部修图提示增强
templates/profiles.yamltemplates/prompt-templates.yamlsocial-coverprofile--negative-hints--archive:输出result/+meta/+outputs.zip
--list-runs--cleanup-days N--cleanup-keep N--cleanup-all- 管理模式下不要求
--prompt
启用 --archive 后,每次运行目录会更成熟:
generated-images/<timestamp>/
├── result/
│ └── image-01.png
├── meta/
│ └── run-record.json
└── outputs.zip
后续如果继续扩展,也建议保持 result/ 与 meta/ 分层。
默认输出根目录是:
$HERMES_HOME/generated-images
如果没有单独设置 HERMES_HOME,通常就是:
~/.hermes/generated-images
在当前这台机器上,按前面的 dry-run 示例,对应路径通常会像:
/data/data/com.termux/files/home/.hermes/generated-images/20260423-211855
python3 ~/.hermes/skills/img/scripts/remote_image.py --list-runspython3 ~/.hermes/skills/img/scripts/remote_image.py --list-runs --list-runs-limit 10python3 ~/.hermes/skills/img/scripts/remote_image.py --cleanup-days 7 --dry-runpython3 ~/.hermes/skills/img/scripts/remote_image.py --cleanup-days 7python3 ~/.hermes/skills/img/scripts/remote_image.py --cleanup-keep 20python3 ~/.hermes/skills/img/scripts/remote_image.py --cleanup-all建议在 Telegram 里先用自然语言让 Hermes 做
--dry-run预演,再决定是否真的删除。
你在 Telegram 机器人里可以直接这样说:
- “帮我看下图片缓存目录”
- “列出最近 10 个出图目录”
- “删掉 7 天前的图片”
- “先看看会删哪些旧图”
- “只保留最近 20 次生成”
- “清空图片缓存”
skill 会自动路由到 remote_image.py 的目录管理模式,而不是要求你手工记 CLI 参数。
目录管理返回 JSON 中还会带一个 data.summary,适合 Hermes/TG 先用它生成第一句自然语言回复,再补充细节列表。
- Telegram 里临时说一句“帮我生成个图”
- 要求明确使用
gpt-image-2 - Hermes 当前主模型不是图像模型,但仍需发图
- 需要读取现有配置而不是单独再配一套图片客户端
- 需要局部修图、原图打包、稳定返回本地路径
MIT