前言¶
在 Cursor、Claude Code 等环境里做「生成一张图」「改这张图」「把多张图合成一张」时，常见做法是手写 HTTP 请求、自己拼 base64、再解析返回里的图片字段。模型侧若走 Gemini 3 Pro Image（Skill 文档中的 Nano Banana Pro），还要处理 chat completions 与 response_modalities 等细节。社区 Skill @user_9feec992/echoflow-banana（v1.0.0）把上述流程收成一份 SKILL.md 加捆绑脚本：经清云 EchoFlow 中转 API 调用图像模型，Agent 在用户提到图像生成、图片编辑、多图合成等意图时可按文档直接执行命令。
这是什么¶
一句话定位：通过清云 EchoFlow API（默认 https://api.echoflow.cn/v1）使用 Nano Banana Pro / Gemini 3 Pro Image 能力，完成文生图、单图编辑与多图合成。
维护与来源：SkillHub 社区发布，坐标 @user_9feec992/echoflow-banana，分类 design-media，来源 community，发布者 user_9feec992。SkillHub 页面标注 requires_api_key=true；密钥需在 EchoFlow 控制台申请（文档指向 https://api.echoflow.cn/）。
解决的问题：为 Agent 提供可复现的安装说明、环境变量约定，以及基于 uv 的 generate_image.py，避免每次从零对接 EchoFlow。
核心功能¶
以下能力均来自已安装的 Skill 包（v1.0.0）中的 SKILL.md 与 scripts/generate_image.py：
- 文生图：仅
--prompt与--filename，无输入图时走生成流程。 - 单图编辑：通过
-i/--input-image传入一张本地图，配合编辑类 prompt。 - 多图合成：
-i可重复指定，最多 14 张输入图。 - 分辨率：
--resolution支持1K、2K、4K（默认1K）。编辑模式下若未改默认1K，脚本会按最大输入边长自动选档（≥3000px → 4K，≥1500px → 2K，否则 1K）。 - 模型选择：默认
gemini-3.1-flash-image-preview；可选gemini-3-pro-image-preview（文档注明质量更高、可能遇到 429）。 - 触发语义：Skill 描述在用户请求生成/创建/编辑/组合图像，或使用「图像生成、图片生成、AI绘画、Nano Banana Pro、Gemini 图片生成」等表述时启用。
脚本通过 POST {api_base}/chat/completions 调用，请求体含 response_modalities 与 image_config.image_size；返回支持从 markdown 内嵌 base64、Gemini parts 或 OpenAI 风格 b64_json 中解析图片并保存为 PNG。
安装与启用¶
1. 安装 SkillHub CLI 并安装本 Skill¶
SkillHub 技能页建议：按 https://skillhub.cn/install/skillhub.md 安装 @user_9feec992/echoflow-banana。通用流程如下。
检查 CLI：
command -v skillhub && skillhub --version
未安装时可执行（完整安装含默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
将 Skill 装到当前 Agent 的 skills 目录（须使用 --dir，否则默认 ./skills/ 可能不被识别）：
skillhub install echoflow-banana --namespace user_9feec992 --dir <你的 skills 目录>
常用路径（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/
安装完成后，Skill 会落在类似 @user_9feec992/echoflow-banana/ 目录，内含 SKILL.md 与 scripts/generate_image.py。
2. 运行时依赖¶
Skill 元数据要求：
- 本机已安装
uv（用于uv run执行脚本并自动拉取httpx>=0.25.0、pillow>=10.0.0）。 - 环境变量
ECHOFLOW_API_KEY（或在命令行传--api-key，文档建议优先环境变量，避免进程列表与 shell 历史泄露）。
Linux 安装 uv 示例（文档要求先检查安装脚本再执行）：
curl -LsSf https://astral.sh/uv/install.sh | sh
设置密钥：
export ECHOFLOW_API_KEY="sk-..."
官方 Skill 分发地址（API 元数据）：https://api.skillhub.cn/user_9feec992/echoflow-banana
SkillHub 展示页：https://www.skillhub.cn/skills/user_9feec992/echoflow-banana
典型用法¶
将 {baseDir} 替换为技能目录下 scripts 的父路径（即 @user_9feec992/echoflow-banana 根目录）。
生成图片：
uv run {baseDir}/scripts/generate_image.py --prompt "a serene mountain landscape at sunset" --filename "mountain.png"
编辑单张图：
uv run {baseDir}/scripts/generate_image.py --prompt "add a rainbow in the sky" --filename "edited.png" -i "input.png"
多图合成（最多 14 张）：
uv run {baseDir}/scripts/generate_image.py --prompt "combine these into one scene" --filename "combined.png" -i img1.png -i img2.png -i img3.png
4K 与 Pro 模型：
uv run {baseDir}/scripts/generate_image.py -p "futuristic city" -f "city.png" -r 4K
uv run {baseDir}/scripts/generate_image.py -p "abstract art" -f "art.png" -m "gemini-3-pro-image-preview"
主要 CLI 参数：
| 参数 | 说明 | 默认 |
|---|---|---|
--prompt, -p |
描述或编辑指令（必填） | — |
--filename, -f |
输出 PNG 路径（必填） | — |
--input-image, -i |
输入图，可重复，≤14 | — |
--resolution, -r |
1K / 2K / 4K |
1K |
--model, -m |
模型名 | gemini-3.1-flash-image-preview |
--api-base |
API 根地址 | https://api.echoflow.cn/v1 |
成功时脚本会打印保存路径，并输出一行 MEDIA: <绝对路径>，便于 Agent 把结果文件交给后续步骤。
更底层的 OpenAI 兼容接口说明见技能包内 references/echoflow_api.md；捆绑脚本实际使用的是 chat completions 图像路径，与参考文档中的 /images/generations 示例并存，以 generate_image.py 行为为准。
适用场景与注意¶
适合谁
- 已在用 EchoFlow、希望 Agent 统一走
ECHOFLOW_API_KEY的团队或个人。 - 需要在对话里快速完成文生图、局部编辑或多图合成，且能接受第三方中转 API 与按量计费（定价以 EchoFlow 控制台为准）。
限制与注意
- 密钥：脚本只读取
ECHOFLOW_API_KEY或--api-key，不会回退到OPENAI_API_KEY/GEMINI_API_KEY。 --api-base：Authorization 会发往指定主机，文档要求仅使用默认可信端点或自建可信网关。- 限流：Pro 预览模型可能返回 429；参考文档建议退避重试。
- 输入图数量：超过 14 张时脚本直接报错退出。
- SkillHub 数据（抓取于编写日）：评分 100000，下载 2130，安装 85；安装前可在 SkillHub 页面核对版本与说明。
结尾¶
@user_9feec992/echoflow-banana 把 EchoFlow 上的 Nano Banana Pro（Gemini 3 Pro Image）图像能力封装成 Agent 可执行的 uv run 工作流：安装到对应 skills 目录、配置 ECHOFLOW_API_KEY 与 uv 后，即可用同一套参数覆盖生成、编辑与最多 14 图合成。详情与安装入口：
- https://www.skillhub.cn/skills/user_9feec992/echoflow-banana
- https://api.skillhub.cn/user_9feec992/echoflow-banana
