image-inpainting

原文：🇺🇸 英文

已翻译

通过`runcomfy` CLI在RunComfy上实现掩码驱动的图像修复。当存在掩码时，将请求路由至通义千问MAI Z-Image Turbo Inpainting（支持掩码、强度和控制尺度的专用修复端点）；当没有可用掩码且需通过描述指定区域时，则路由至保留身份的编辑模型（Nano Banana 2 Edit、GPT Image 2 Edit、FLUX Kontext Pro）。适用于对象移除、水印去除、区域替换、瑕疵修复，以及任何由二进制掩码定义目标区域的受控局部编辑场景。触发关键词包括“inpaint”“inpainting”“image inpaint”“remove from image”“fill region”“mask-driven edit”“remove watermark”“remove object”“patch the photo”“fill the hole”，或任何明确要求编辑静态图像特定掩码区域的请求。

348.3k次下载

来源prime-skills/runcomfy-agent-skills

添加于2026-08-08

NPX安装

npx skill4agent add prime-skills/runcomfy-agent-skills image-inpainting

SKILL.md 内容（中文）

查看翻译对照 →

图像修复

通过

runcomfy

CLI在RunComfy上实现掩码驱动的区域编辑——移除对象、填补空白、替换掩码区域。当存在掩码时，该技能会路由至Z-Image Turbo Inpainting；当需通过文字描述指定区域时，则路由至指令驱动的编辑模型。

runcomfy.com · Z-Image Inpainting · CLI文档

基于RunComfy CLI实现

bash

# 1. 安装（详见runcomfy-cli技能说明）
npm i -g @runcomfy/cli      # 或：npx -y @runcomfy/cli --version

# 2. 登录
runcomfy login              # 或在CI环境中：export RUNCOMFY_TOKEN=<token>

# 3. 执行图像修复
runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{"image": "...", "mask_image": "...", "prompt": "..."}' \
  --output-dir ./out

CLI深度解析：

runcomfy-cli

技能。

选择合适的模型

按区域定位精度排序（先需掩码的模型，后基于描述的模型）。

Z-Image Turbo Inpainting —

tongyi-mai/z-image/turbo/inpainting

（默认选项——需掩码）

支持掩码、强度和控制尺度的专用修复端点。开源权重，处理时间从亚秒级到数秒不等。适用场景：通过二进制掩码实现精准区域编辑——对象移除、水印清理、全区域替换。不适用场景：无掩码的编辑——使用Nano Banana 2 Edit（基于描述）。

Z-Image Turbo Inpainting LoRA —

tongyi-mai/z-image/turbo/inpainting/lora

支持LoRA适配器的修复端点——在修复过程中应用微调后的风格。适用场景：品牌风格固定的图像修复（LoRA捕捉风格，掩码定义区域）。不适用场景：通用图像修复——使用基础修复端点。

Nano Banana 2 Edit —

google/nano-banana-2/edit

（基于描述的备选方案）

由空间语言驱动的保留身份编辑（如“右下角的水印”“头顶的线缆”）。无需掩码。适用场景：无可用掩码但可通过描述指定区域的情况。不适用场景：需精准像素级区域边缘的编辑——使用Z-Image Inpainting。

GPT Image 2 Edit —

openai/gpt-image-2/edit

支持多参考图的编辑，遵循布局精准指令；可执行“仅移除X”的指令。适用场景：复杂提示+参考图组合，且掩码区域需要其他图像上下文的情况。不适用场景：简单单图像掩码驱动任务——使用Z-Image Inpainting。

FLUX Kontext Pro —

blackforestlabs/flux-1-kontext/pro/edit

单指令局部编辑，最大程度保留其他所有内容。适用场景：无需掩码的“保留所有内容除了X”风格局部编辑。不适用场景：明确的掩码驱动工作流——使用Z-Image Inpainting。

路径1：Z-Image Turbo Inpainting——默认选项

模型：

tongyi-mai/z-image/turbo/inpainting

目录：Z-Image Inpainting

数据结构

字段	类型	是否必填	说明
`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	否	用于结果复现

调用示例

对象移除（低强度）：

bash

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "移除头顶线缆；保留屋顶线条和天空渐变；生成干净简洁的天空。",
    "image": "https://your-cdn.example/street.jpg",
    "mask_image": "https://your-cdn.example/cables-mask.png",
    "strength": 0.5,
    "control_scale": 0.8
  }' \
  --output-dir ./out

区域替换（高强度）：

bash

runcomfy run tongyi-mai/z-image/turbo/inpainting \
  --input '{
    "prompt": "将杂乱背景替换为光滑浅灰色工作室背景纸；仅掩码背景区域。",
    "image": "https://your-cdn.example/product.jpg",
    "mask_image": "https://your-cdn.example/bg-mask.png",
    "strength": 0.9
  }' \
  --output-dir ./out

提示词技巧

必须提供掩码URL。灰度图，白色=修复区域，黑色=保留区域。掩码边缘轻微模糊（1–3像素）比锐利的二进制边缘融合效果更好。
按意图选择强度:
- ```
0.3–0.5
```
  润色/瑕疵修复
- ```
0.6–0.7
```
  风格匹配的对象替换
- ```
0.8–1.0
```
  全区域替换

在提示词中明确掩码外需要保留的内容：例如

"保留屋顶线条和天空渐变"

、

"匹配砖块图案和砂浆色调"

。

即使有掩码，空间标签仍有帮助：例如
```
"左侧架子"
```
、
```
"右上象限"
```
——当掩码覆盖多个对象时可消除歧义。

路径2：基于描述的备选方案（无掩码）

当没有掩码时，使用Nano Banana 2 Edit结合空间语言。模型会根据你的提示词识别目标区域：

bash

runcomfy run google/nano-banana-2/edit \
  --input '{
    "prompt": "移除右下角的水印。其他内容完全保留原样。",
    "image_urls": ["https://your-cdn.example/photo.jpg"]
  }' \
  --output-dir ./out

如需更丰富的基于描述的编辑，请查看

image-edit

。

常见使用场景

水印去除

若有掩码：使用路径1（强度0.5）
若无掩码：使用路径2，提示词为"移除右下角的水印。其他内容完全保留原样。"

背景完全替换

给背景添加掩码 → 使用路径1，设置
```
strength: 0.9
```
并描述新背景

向空白区域添加对象

给空白区域添加掩码 + 描述新对象 → 使用路径1，设置
```
strength: 0.8
```

品牌风格固定的图像修复

使用Z-Image Inpainting LoRA变体，搭配通过
```
/trainer
```
训练的品牌风格LoRA

复杂布局重定位（将元素从X移至Y）

难以清晰定义掩码 → 使用GPT Image 2 Edit结合多参考图+方向语言。详见
```
image-edit
```
。

本技能不支持的场景

图像扩展（Outpainting）（超出原始画布范围）：查看
```
image-outpainting
```
。
视频修复（Video inpainting）（逐帧掩码编辑）：查看
```
video-inpainting
```
。

浏览完整模型目录

掩码创建工具（Photoshop、GIMP、SAM模型）是本技能的上游工具；CLI仅接收掩码URL，不生成掩码。

退出码

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

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

工作原理

当存在掩码时，技能选择Z-Image Inpainting；否则回退到基于描述的编辑，并调用

runcomfy run

传入匹配的JSON参数。CLI向模型API发送POST请求，轮询请求状态，并将结果下载至

--output-dir

目录。

安全与隐私

仅通过已验证的包管理器安装。使用
```
npm i -g @runcomfy/cli
```
或
```
npx -y @runcomfy/cli
```
。Agent不得代表用户将任意远程安装脚本通过管道输入shell。
令牌存储：
```
runcomfy login
```
会将API令牌写入
```
~/.config/runcomfy/token.json
```
，权限为0600。在CI/容器环境中设置
```
RUNCOMFY_TOKEN
```
环境变量。
输入边界（Shell注入）：提示词和图像/掩码URL通过
```
--input
```
以JSON字符串形式传递。CLI不会对提示词内容进行Shell扩展。无Shell注入风险。
间接提示注入（第三方内容）：源图像和掩码URL是不可信的；嵌入的指令可能影响填充结果。Agent缓解措施：
- 仅处理用户为本次修复明确提供的URL。
- 当填充结果与提示词不符时，怀疑源图像（如嵌入文字、隐藏EXIF信息）。
掩码来源验证：确认用户确实希望替换掩码区域。复用其他图像的掩码是修复失败的常见原因。
出站端点（白名单）：仅允许访问
```
model-api.runcomfy.net
```
和
```
*.runcomfy.net
```
/
```
*.runcomfy.com
```
。无遥测数据。
生成文件大小限制：CLI会中止任何超过2 GiB的单个文件下载。
Bash使用范围：仅允许
```
Bash(runcomfy *)
```
。

image-inpainting

NPX安装

标签

SKILL.md 内容（中文）

图像修复

基于RunComfy CLI实现

选择合适的模型

路径1：Z-Image Turbo Inpainting——默认选项

数据结构

调用示例

提示词技巧

路径2：基于描述的备选方案（无掩码）

常见使用场景

水印去除

背景完全替换

向空白区域添加对象

品牌风格固定的图像修复

复杂布局重定位（将元素从X移至Y）

本技能不支持的场景

浏览完整模型目录

退出码

工作原理

安全与隐私

相关技能