前言¶
在 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
