Ergouzi Studio

一个可供多个 Agent 使用的 Ergouzi Studio 技能包，同时提供只依赖 Python 标准库的命令行工具，用于生成、编辑、放大、动画化和转换图片与视频。

特性

• 支持 Ergouzi 的 9 个图片与视频模型
• scripts/studio.py 统一处理提交、轮询、恢复、取消、结果下载和本地回执
• 提交请求使用有限次数的幂等重试，避免网络抖动造成重复任务
• 下载结果会校验 HTTPS、公网地址、内容类型和文件大小
• 不需要第三方 Python 包，不需要 pip install
• API Key 只从环境变量读取，不写入仓库、日志、JSON 或生成文件

使用前准备

需要准备：

• Python 3.10 或更高版本
• 有效的 ERGOUZI_API_KEY
• 能访问 https://ergouzi.life 的网络环境

提交生成、编辑、试衣、放大、动画、头像或人物替换任务可能产生费用。只有在用户明确要求执行媒体任务时，Agent 才应调用 API。

快速开始

克隆仓库并进入目录：

git clone https://github.com/Astyyym/ergouzi-studio.git
cd ergouzi-studio

PowerShell 示例：

$env:ERGOUZI_API_KEY = '你的 API Key'
python .\scripts\studio.py --model ergouzi/e-image --prompt '白色桌面上的红苹果' --output .\apple.jpg
Remove-Item Env:ERGOUZI_API_KEY

Linux 或 macOS 示例：

export ERGOUZI_API_KEY='你的 API Key'
python3 ./scripts/studio.py --model ergouzi/e-image --prompt '白色桌面上的红苹果' --output ./apple.jpg
unset ERGOUZI_API_KEY

查看完整参数：

python .\scripts\studio.py --help

生成成功后，工具会输出生成文件路径、prediction id，并在输出文件旁写入一个不含密钥的 JSON 回执。

在不同 Agent 中使用

GitHub 仓库地址本身不会自动安装或激活技能。先克隆仓库，再按目标 Agent 的发现机制放置目录。无论使用哪个 Agent，都要保持 SKILL.md 位于 ergouzi-studio 根目录，并在运行环境配置自己的 ERGOUZI_API_KEY。

Codex

Codex 技能目录通常为：

~/.codex/skills/ergouzi-studio/

将整个仓库目录放入该位置后，Codex 可以通过 $ergouzi-studio 发现技能。仓库中的 SKILL.md 是主要技能说明，agents/openai.yaml 提供 Codex 的显示名称、简介和默认提示词；AGENTS.md 提供仓库级使用与安全规则。

在 Windows 上，实际路径可能类似：

C:\Users\<用户名>\.codex\skills\ergouzi-studio\

Claude Code

可以安装为项目级技能：

<项目>/.claude/skills/ergouzi-studio/

也可以放入 Claude Code 已配置的用户级 skills 目录。打开仓库或使用该技能前，Claude Code 应先阅读根目录的 CLAUDE.md；该文件再指向 AGENTS.md 和 SKILL.md。Claude Code 不使用 agents/openai.yaml 作为主要入口，因此该文件不是 Claude Code 的必需配置。

Hermes Agent

放入当前 Hermes 配置所使用的 skills 目录，并保持目录名为 ergouzi-studio。Hermes 通过技能目录中的 SKILL.md 建立技能索引；如果当前安装没有自动发现机制，就在对话中明确提供仓库路径并要求 Agent 阅读 SKILL.md、AGENTS.md 和 references/api.md。

Hermes 的技能目录由本机配置决定，不要假设所有用户都使用同一个绝对路径。可以把仓库复制到目标 skills 目录，或在该目录中维护一个指向此仓库的链接（具体取决于操作系统和权限）。

OpenClaw 或其他 Agent

放到该 Agent 配置的 skills 目录，或项目约定的技能目录。若 Agent 没有自动发现机制，直接要求它依次阅读：

1. AGENTS.md：通用执行与安全规则
2. SKILL.md：模型、参数和工作流
3. references/api.md：模型专用字段和枚举值

这类 Agent 不应把 Codex 专用的 $ergouzi-studio 调用语法当成通用语法；直接执行 scripts/studio.py 是跨 Agent 都可用的后备方式。

跨 Agent 通用提示词

请使用这个仓库：https://github.com/Astyyym/ergouzi-studio

先阅读 AGENTS.md、SKILL.md 和 references/api.md。
从环境变量读取 ERGOUZI_API_KEY，不要打印、保存或提交密钥。
只有在我明确要求生成或处理媒体时才调用 API。
使用 scripts/studio.py 完成任务，并返回生成文件的绝对路径和 prediction id。

文件与 Agent 的关系

文件	作用	主要使用者
SKILL.md	技能行为、模型和工作流的主要说明	所有 Agent
AGENTS.md	通用执行、安全和安装规则	Codex、Claude Code、其他 Agent
CLAUDE.md	Claude Code 打开仓库时的入口提示	Claude Code
agents/openai.yaml	Codex 的技能元数据和默认提示词	Codex
README.md	人类安装、配置和跨 Agent 使用说明	人类与所有 Agent

支持的模型

模型	功能
ergouzi/e-image	文生图
ergouzi/e-image-edit	参考图编辑
ergouzi/e-image-ideogram	支持高质量文字渲染的文生图
ergouzi/e-image-try-on	虚拟试衣
ergouzi/e-image-upscale	图片放大与细节增强
ergouzi/e-video	文生视频、图生视频、音频生视频，可选首尾帧
ergouzi/e-video-animate	使用视频驱动参考图动画
ergouzi/e-video-avatar	使用音频或语音脚本驱动头像
ergouzi/e-video-replace	替换视频中的人物

常用示例

编辑图片：

python .\scripts\studio.py --model ergouzi/e-image-edit --image .\input.jpg --prompt '只把背景改成干净的米色摄影棚墙面' --output .\edited.jpg

虚拟试衣：

python .\scripts\studio.py --model ergouzi/e-image-try-on --person-image .\person.jpg --garment-image .\shirt.png --garment-image .\trousers.png --output .\try-on.jpg

放大图片：

python .\scripts\studio.py --model ergouzi/e-image-upscale --image .\input.jpg --factor 2 --enhance-details --output .\input-2x.jpg

生成视频：

python .\scripts\studio.py --model ergouzi/e-video --prompt '镜头缓慢穿过下雨的城市街道' --duration 5 --resolution 720p --output .\street.mp4

本地图片、视频和音频可以通过 --image、--video 和 --audio 传入，也支持 HTTP(S) URL 和 data URI。模型专用字段和完整参数请参阅 references/api.md。

任务恢复、取消与回执

任务中断后，使用原 prediction id 恢复，不要重新创建替代任务：

python .\scripts\studio.py --model ergouzi/e-video --prompt '...' --output .\video.mp4 --prediction-id <prediction-id>

只有在明确要求取消指定任务时才使用 --cancel：

python .\scripts\studio.py --model ergouzi/e-video --output .\video.mp4 --prediction-id <prediction-id> --cancel

成功完成后，输出目录会出现类似下面的回执文件：

video.<prediction-id>.json

回执包含 prediction id、模型、状态和绝对输出路径，不包含 API Key。

配置与安全限制

默认 API 地址为 https://ergouzi.life/v1。如需使用兼容端点，可以设置：

$env:ERGOUZI_BASE_URL = 'https://example.com/v1'

安全规则：

• API Key 只能放在 ERGOUZI_API_KEY 环境变量中
• 不要把 Key 写入 README、JSON、脚本、日志、提示词或生成文件
• 本地媒体小于工具限制时会转为 data URI；较大的媒体应提供 HTTPS URL
• 输出下载要求 HTTPS，禁止指向本机或私有地址
• 不会把 Ergouzi Authorization header 转发到外部输出地址
• 使用匹配的 .jpg、.png 或 .mp4 输出扩展名

目录结构

• SKILL.md：跨 Agent 技能说明
• AGENTS.md：通用使用和安全规则
• CLAUDE.md：Claude Code 入口说明
• scripts/studio.py：九个模型共用的统一入口
• scripts/generate.py：请求、轮询和安全下载辅助代码
• scripts/edit.py：图片编辑与放大辅助脚本
• references/api.md：API 和模型参数参考
• agents/openai.yaml：Codex 技能发现所需的元数据

许可证

MIT，详见 LICENSE。