image-edit

图像编辑 — RunComfy 专业版

runcomfy.com · Nano Banana Edit · GPT Image 2 Edit · Flux Kontext · Z-Image Inpaint · GitHub

按意图路由的图像编辑。 此技能不会将你限制在单一模型上，而是根据用户的实际需求，从 RunComfy 目录中选择合适的编辑模型：批量保持主体身份、多语言文本改写、单次精确编辑，或基于蒙版的区域替换。

npx skills add agentspace-so/runcomfy-skills --skill image-edit -g

根据用户意图选择合适的模型

用户意图	模型	原因
一致地批量编辑 1–20 张图像（SKU 商品图库、A/B 版本）	Nano Banana Edit	每次调用最多输入 20 张图像；系列图像可锁定宽高比和分辨率
替换背景，同时保留主体身份	Nano Banana Edit	对“保持 X 不变”这类提示词，能很好地保留主体身份
使用空间描述（“左侧的物体”“右上角”）局部移除／添加物体	Nano Banana Edit	能遵循方向性空间范围
多语言／非拉丁字符的图内文本改写（日文假名、西里尔字母、阿拉伯文）	GPT Image 2 Edit	多语言排版能力在同类中最强
多参考图构图（主体来自 img1，场景来自 img2，调色板来自 img3）	GPT Image 2 Edit	按编号标注的参考图可正确传达线索
精确布局重定位（“将标题从右上角移到底部中央”）	GPT Image 2 Edit	能在布局层面遵循方向性描述
保留身份，同时生成不同翻译标题	GPT Image 2 Edit	同一源素材可生成多种语言版本，同时保持身份一致
单次精确局部编辑（“她现在拿着一把橙色雨伞”）	Flux Kontext Pro	单张参考图、单条指令，并能高保真地保留原图
基于蒙版移除物体（电缆、水印、干扰元素）	Z-Image Turbo Inpaint	必须提供蒙版，可调节强度，并保持边缘一致
基于蒙版替换区域（使用蒙版完全替换背景）	Z-Image Turbo Inpaint	较高强度配合干净的蒙版，可实现干净的替换效果
未指定时的默认选择	Nano Banana Edit	灵活性最高，支持单张和批量处理

Agent 会读取此表，对用户意图进行分类，并选择下方对应的小节。

前置条件

1. RunComfy CLI — npm i -g @runcomfy/cli
2. RunComfy 账户 — runcomfy login。
3. CI／容器 — 设置 RUNCOMFY_TOKEN=<token>。

---

路由 1：Nano Banana Edit — 通用编辑和批量处理的默认选择

模型：google/nano-banana-2/edit

参数结构

字段	类型	必填	默认值	备注
prompt	string	是	—	先说明保留目标，最后说明要做的修改。
image_urls	array	是	—	1–20 个可公开访问的 HTTPS URL。
number_of_images	int	否	1	每次调用输出 1–4 张图像。
aspect_ratio	enum	否	auto	auto 会沿用输入图像；批量处理时可锁定以保持一致。
resolution	enum	否	1K	0.5K / 1K / 2K / 4K。
output_format	enum	否	png	png / jpeg / webp。
seed	int	否	—	用于复现结果。
enable_web_search	bool	否	false	基于网络信息进行编辑（会增加延迟）。

调用

runcomfy run google/nano-banana-2/edit \
  --input '{
    "prompt": "Keep the subject identity, pose, and clothing unchanged. Convert the background into a rainy neon cyberpunk street.",
    "image_urls": ["https://.../portrait.jpg"]
  }' \
  --output-dir <absolute/path>

批量处理（锁定宽高比和分辨率）：

runcomfy run google/nano-banana-2/edit \
  --input '{
    "prompt": "Replace the watermark in the bottom-right with the text \"AURA\" in clean white sans-serif. Keep everything else exactly as in the input.",
    "image_urls": ["https://.../sku-1.jpg", "https://.../sku-2.jpg", "https://.../sku-3.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }' \
  --output-dir <absolute/path>

提示词技巧

• 优先保留："Keep [identity / pose / brand / framing] unchanged." 然后说明要做的更改。
• 明确空间范围：例如“仅背景”“左侧物体”“右上象限”——具体位置更容易得到遵循。
• 保持批次一致：整个批次固定 aspect_ratio 和 resolution。
• 小步迭代：将复合编辑拆分为多轮较短的处理。

---

路线 2：GPT Image 2 Edit — 多语言文本 + 多参考图合成

模型：openai/gpt-image-2/edit

Schema

字段	类型	必填	默认值	备注
prompt	string	是	—	编辑指令；优先说明要保留的内容。
images	string[]	是	—	最多 10 个 HTTPS URL。第一个是主图，其余为辅助图。
size	enum	否	auto	auto、1024_1024、1024_1536、1536_1024。仅限这些值。

调用

多语言文本改写：

runcomfy run openai/gpt-image-2/edit \
  --input '{
    "prompt": "Keep the photograph, layout, and brand mark exactly as in the input. Replace only the in-image headline. The new headline reads \"今日のおすすめ\" in bold Japanese kana, same position and font weight.",
    "images": ["https://.../poster-en.jpg"]
  }' \
  --output-dir <absolute/path>

多参考图合成：

runcomfy run openai/gpt-image-2/edit \
  --input '{
    "prompt": "Compose subject from image 1 into the room from image 2. Match the lighting and color palette of image 2. Keep image 1 subject identity unchanged.",
    "images": ["https://.../subject.jpg", "https://.../room.jpg"]
  }' \
  --output-dir <absolute/path>

提示词技巧

• 准确引用图片中的文字。 对非拉丁文字注明文字系统，例如：“日语假名”“西里尔字母”“阿拉伯语（从右向左）”。
• 为多张参考图编号：“使用图 1 中的主体、图 2 中的光线”。
• 使用方向描述布局：“将标题从右上方移至底部中央”“替换右下角的水印”。
• size: "auto" 会保留输入图像的比例——除非编辑需要改变构图，否则建议使用此选项。

---

路线 3：Flux Kontext Pro — 单次精准局部编辑

模型：blackforestlabs/flux-1-kontext/pro/edit

Schema（最简）

字段	类型	必填	备注
prompt	string	是	一条陈述式编辑指令。
image	string	是	单张源图 URL。
aspect_ratio	enum	否	从支持的宽高比值中选择。
seed	int	否	用于确保结果可复现。

仅支持单张图像，不支持数组。多图工作流请使用路线 1（Nano Banana Edit）。

调用

runcomfy run blackforestlabs/flux-1-kontext/pro/edit \
  --input '{
    "prompt": "Keep the person'\''s face, pose, and clothing unchanged. Add an orange umbrella in her left hand and a slight smile.",
    "image": "https://.../portrait.jpg"
  }' \
  --output-dir <absolute/path>

提示词技巧

• 使用一条陈述式指令。“她现在手里拿着一把橙色雨伞，面带微笑”——用祈使语气，只提出一项更改。
• 优先保留。 先写 "Keep [unchanged elements]"，然后说明要做的更改。
• 小步迭代。 复合编辑在单次处理中容易产生偏差；请拆分为连续多轮处理。

---

路线 4：Z-Image Turbo Inpaint — 由蒙版驱动的精准区域编辑

模型：tongyi-mai/z-image/turbo/inpainting

Schema

字段	类型	必填	备注
prompt	string	是	说明要填充或替换的内容；并注明蒙版区域以外的保留要求。
image	string	是	源图 URL。
mask_image	string	是	灰度蒙版 URL（白色 = 图像修复，黑色 = 保留）。
strength	float	否	0.3–0.6 用于润饰，0.7–1.0 用于完全替换。
control_scale	float	否	通常为 0.6–0.9。
aspect_ratio	enum	否	输出宽高比。
seed	int	否	用于确保结果可复现。

调用

移除物体（低强度）：

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "Remove overhead cables; preserve rooflines and sky gradient; thin clean sky.",
    "image": "https://.../street.jpg",
    "mask_image": "https://.../cables-mask.png",
    "strength": 0.5,
    "control_scale": 0.8
  }' \
  --output-dir <absolute/path>

替换区域（高强度）：

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "Replace busy backdrop with smooth light gray studio paper; mask background only.",
    "image": "https://.../product.jpg",
    "mask_image": "https://.../bg-mask.png",
    "strength": 0.9
  }' \
  --output-dir <absolute/path>

提示词技巧

• 必须提供蒙版 URL——蒙版为灰度图，白色 = 图像修复区域，黑色 = 保留区域。与锐利的二值蒙版相比，轻微模糊蒙版边缘（1–3px）能更好地融合。
• 按意图设置强度：润饰或清理使用 0.3–0.5，风格匹配的物体替换使用 0.6–0.7，完整区域替换使用 0.8–1.0。
• 在提示词中说明蒙版外要保留的内容：“保留屋顶线条和天空渐变”“匹配砖块图案和灰浆色调”。
• 空间方位描述仍有帮助，即使区域已由蒙版定义：“左侧货架”“右上象限”。

---

限制

• 每条路由都受其模型限制。 Nano Banana：1–20 个输入，1–4 个输出。GPT Image 2 Edit：最多 10 个参考图，4 种固定尺寸。Flux Kontext：单个参考图。Z-Image Inpaint：必须提供蒙版。
• 不支持多路由混合。 此技能每次调用只选择一个模型。
• 品牌专属覆盖 — 如果用户指定了特定模型，请路由到相应的品牌技能（gpt-image-edit、flux-kontext、nano-banana-edit），以获得更全面的处理。

退出代码

code	含义
0	成功
64	CLI 参数错误
65	输入 JSON 错误 / 架构不匹配
69	上游 5xx
75	可重试：超时 / 429
77	未登录或令牌被拒绝

完整参考：docs.runcomfy.com/cli/troubleshooting。

工作原理

此技能根据用户意图，从 Nano Banana Edit、GPT Image 2 Edit、Flux Kontext Pro、Z-Image Turbo Inpaint 中选择一个，并使用匹配的 JSON 请求体调用 runcomfy run <model_id>。CLI 会向 Model API 发送 POST 请求、轮询请求状态、获取结果，并将任何 .runcomfy.net / .runcomfy.com URL 下载到 --output-dir。按 Ctrl-C 可在退出前取消远程请求。

安全与隐私

• 令牌存储：runcomfy login 会将 API 令牌写入 ~/.config/runcomfy/token.json，并设置 0600 权限（仅所有者可读写）。在 CI / 容器中设置 RUNCOMFY_TOKEN 环境变量即可完全绕过该文件。
• 输入边界：用户提示词会作为 JSON 字符串，通过 --input 传递给 CLI。CLI 不会对提示词进行 shell 扩展；它会通过 HTTPS 直接向 Model API 发送 JSON 请求体。提示词内容不存在 shell 注入面。
• 第三方内容：你提供的图像 / 蒙版 / 视频 URL 由 RunComfy 模型服务获取，而非由你本机上的 CLI 获取。请将外部 URL 视为不可信；基于图像的提示词注入是任何图像编辑 / 视频编辑模型都已知的风险。
• 出站端点：仅 model-api.runcomfy.net（提交请求）和 *.runcomfy.net / *.runcomfy.com（生成结果的下载白名单）。无遥测，无回调。
• 生成文件大小上限：CLI 会中止任何超过 2 GiB 的单次下载，以防恶意或失控的模型输出占满磁盘。