🧩 它做什么，和“重新生成一张”有什么不同

gpt-image-edit 调用的核心是 OpenAI Images API 的 /v1/images/edits 端点。它和文生图的 /v1/images/generations 是两条不同的路：你上传一张已经存在的图，用自然语言告诉它改哪里，它在保留图片原有结构的前提下做出修改，而不是从零画一张新的。

这个区别在实际使用中非常关键。用文生图端点，你说“一张产品图放在白色背景上”，模型每次都会画出一个全新的产品——形状、比例、标签位置都可能有变化。用编辑端点，你上传手里已经拍好的产品图，说“把背景换成纯白”，模型只动背景，产品本身的像素保持不变。

gpt-image-edit 这个封装在底层能力之上加了几层实用的东西：

  • 自动缩放输入图片。超过 4MB 或 1024px 的输入图会被自动调整到安全尺寸再上传，避免 API 超时或 413 错误。你不需要手动压缩参考图。
  • 蒙版局部重绘。除了纯文本指令，它支持传入 mask 图片来精确指定编辑区域。蒙版的透明区域就是可编辑区域，其余部分保持原样。
  • 多参考图融合。最多可以同时传入 10 张参考图，让模型从多张图中提取元素合成到一张新画面里。
  • 结果直接落盘。生成的图片会保存到本地路径并返回文件地址，即使 MCP 层因为超时断开连接，图片依然会写入磁盘，不会因为 60 秒超时而丢掉结果。

它同时内置了 OpenAI 官方文档化的 prompting 模式。这意味着你不需要自己去翻文档搞清楚“编辑指令该怎么写”，skill 会把对应的模板和参数建议一并交给模型，输出质量比直接拼 prompt 更稳定。

📦 两条安装路线，按你的工具选

路线一：Claude Code / Codex Skill（最省事）

如果你用 Claude Code 或 Codex CLI，这是最快的路径。RunComfy 维护了 gpt-image-edit 的 skill 封装，在项目根目录执行：

npx skills add https://github.com/agentspace-so/runcomfy-agent-skills --skill gpt-image-edit

或者全局安装：

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

这个 skill 通过 RunComfy CLI 执行，底层命令是 runcomfy run openai/gpt-image-2/edit。安装前确保本机有 RunComfy CLI 并完成登录。

路线二：MCP 服务器（适合 Cursor / Claude Desktop / VS Code）

如果你用的不是 Claude Code，或者想跨多个客户端共用一套配置，MCP 路线更灵活。有两个主流的 gpt-image MCP server 可以选择。

方案 A：openai-image-mcp-server（功能最全）

这个 npm 包直接封装了 OpenAI 官方 API，提供 gpt_image_edit、gpt_image_generate 等多个工具。在 Claude Code 中执行：

claude mcp add openai-image -e OPENAI_API_KEY=sk-... -- npx -y openai-image-mcp-server@latest

在 Cursor 的 ~/.cursor/mcp.json 中手动配置：

{
  "mcpServers": {
    "gpt-image-gen": {
      "command": "npx",
      "args": ["-y", "openai-image-mcp-server@latest"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

gpt_image_edit 工具接受 image_path（源图绝对路径）、prompt（编辑描述）和可选的 mask_path（蒙版路径）。

方案 B：@runapi.ai/gpt-image-mcp（API 密钥统一管理）

如果你已经在用 RunAPI 平台的其他服务，用这个更统一。一个 RUNAPI_API_KEY 就能覆盖 GPT Image 的编辑和生成。在 Claude Code 中：

claude mcp add gpt-image -s user -- npx -y @runapi.ai/gpt-image-mcp

这个 server 暴露了 edit_image、text_to_image、get_task 和 check_pricing 四个工具，其中 check_pricing 不需要密钥就能查价格。

🛠️ 装好之后怎么用：核心是“说清楚改什么、保什么”

gpt-image-edit 的触发词包括 gpt-image-edit、GPT Image、ChatGPT image edit，以及任何明确要求编辑已有图片的表述。在 Claude Code 里你可以直接说：

用 gpt-image-edit 把这张图的背景换成暖灰色摄影棚，人物、姿势和品牌标识保持原样。输出 1536x1024。

Agent 会把你的描述组装成 images.edit 请求提交，拿到结果后保存到本地。

提示词的核心公式只有三个槽位：改什么、保什么、限制条件。这个公式来自社区大量实践总结，在实际使用中比随意描述有效得多。

Change [要改的部分] to [目标状态], keep [必须保持不变的东西] unchanged, [限制条件]。

举个例子。不要写“把背景换一下”，要写：

将背景替换为黎明时分雾气弥漫的松树林。保持人物的面部比例、姿势、服装和光影方向完全不变。不要添加任何新的人物。

“保什么”这一句比你想象的重要。gpt-image 的编辑端点在处理纯文本指令时，如果模型不确定哪些东西该保留，它可能重新生成整张画面，导致人脸、产品标签或构图发生意外变化。明确列出“保持不变”的清单——身份、面部比例、姿势、相机角度、裁切、产品几何形状、标签拼写、光照方向、阴影、反射——能大幅提高结果的可预测性。

蒙版局部重绘是另一个值得掌握的能力。如果你手里有图像编辑工具（Photoshop、Figma、甚至画图工具），可以自己做一张 PNG 蒙版，把需要编辑的区域涂成透明，其余区域保持不透明。上传原图加蒙版加 prompt，模型只在透明区域生效。蒙版必须是 PNG 格式，且和原图分辨率一致，小于 4MB。如果你不想手动做蒙版，纯文本指令在很多场景下也能工作——GPT Image 2 之后，模型对“只改这一块”的自然语言理解已经明显改善，不一定需要蒙版才能做局部编辑。

💡 几个让出图更稳的技巧

  • 换背景时把“光影匹配”写进 prompt。这是换背景类编辑最容易翻车的地方——新背景的光照方向和人物的阴影对不上，看起来就是贴上去的。加一句“将新背景的光照匹配到人物现有的阴影方向”，合成感会明显降低。
  • 改文字用引号锁定原文。如果你要替换图片里的文字内容，不要只描述新文字，先把原文引出来：“将图片中标题文字 ‘保持好奇’ 替换为 ‘持续探索’，字体、大小和颜色保持不变”。引号告诉模型这是一次精确的文本替换，不是语义改写。
  • input_fidelity 参数在处理人脸和产品细节时值得打开。OpenAI API 提供了 input_fidelity 参数，设为 "high" 时模型会花更多算力保留输入图的高频细节，尤其适合编辑带人脸或精细纹理的图片。如果你的 MCP 配置或 skill 参数里能指定这个值，处理人像和产品图时建议打开。
  • 复杂编辑拆成多步，不要一次写一大段。先改背景，跑一版；确认效果后再改光线；最后调整颜色。每一步的 prompt 都很短，模型不容易在多个目标之间顾此失彼。gpt-image-edit 的结果可以逐次链式传递——上一轮的输出作为下一轮的输入。
  • 多参考图按“主体—场景—风格”的顺序上传。如果你在做多图融合，参考图的排列顺序会影响模型的理解。把主体图放第一位，场景图放第二位，风格参考图放最后。prompt 里用“image 1 的主体”“image 2 的背景”来点名引用，比用模糊的“第一张”“那张图”清晰得多。

🔀 和同目录其他编辑模型的分工

RunComfy 目录里和 gpt-image-edit 定位相近的还有 flux-kontext 和 nano-banana-2。什么时候选哪个，有一个简单的判断逻辑：

选 gpt-image-edit：需要在图片里精确渲染大量文字（海报、广告图、带文案的产品图），或者需要多参考图融合。GPT Image 2 的文本渲染能力目前是同类模型里最强的之一。

选 flux-kontext：需要极致的角色一致性保持，或者只需要做非常克制的局部修改，不希望模型在 prompt 理解上有太多“自由发挥”。Flux Kontext 的编辑行为更保守、更可预测。

选 nano-banana-2：需要挂 10 张以上参考图做复杂合成，或者需要精确控制“主体分割跳过”这类高级编辑操作。Nano Banana 2 在参考图容量和主体分割上有独特优势。

这三者不是替代关系，而是覆盖了编辑场景的不同角落。skill 的提示词里通常会带上模型路由判断，如果你的需求明显更适合另一个模型，它会给出建议。

🤖 适合哪些 AI 工具

gpt-image-edit 的 skill 版本明确兼容 Claude Code、Codex CLI 和 Cursor。MCP 服务器路线的兼容面更宽，经过验证的客户端包括 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Cline、Roo Code、Codex CLI，以及任何遵循 MCP 协议的宿主。

在 Claude Code 中，安装 skill 后输入 /gpt-image-edit 即可手动触发，Agent 检测到编辑意图时也会自动调用。在 Cursor 中，MCP 服务器注册后 Agent 的工具列表里会出现对应的编辑工具，直接描述需求即可。

需要留意的是，gpt-image-edit 走的是 OpenAI API，不是本地模型，需要有效的 OpenAI API key。如果你用的是 RunAPI 路线，则需要 RunAPI 的 key。两条路线的底层模型是一样的，区别只在于密钥管理和计费方式。另外，如果你的 OpenAI 账号没有完成组织验证，可能无法使用 GPT Image 2，skill 会自动回退到 GPT Image 1，功能基本一致但文本渲染质量稍有差距。