企业官网建设流程全解析

• AI 技能
• 媒体生成
• AI 应用

本文围绕 GPT-Image2-Skill 仓库中的 openai-image-2.5-editing.md 展开，系统讲解 GPT Image 2.5 在"参考编辑"（reference edits）、翻译、inpainting 与透明抠图四类任务上的正确姿势：如何在本地通过gpt-imageCLI 编排多输入参考、如何使用 mask、如何用--background transparent获得真正的透明 PNG，以及如何在接受结果前按验收清单核查。读完本文，你将掌握一套"角色分配 → 变更/不变分离 → 显式建模 → 输出验证"的完整可执行工作流，并了解其背后的 CLI 源码与离线测试实现。

1. 参考编辑的核心事实：保真改进 ≠ 像素锁定

GPT Image 2.5 在官方文档中被定位为"参考与保真（references and preservation）"能力增强的版本，但仓库文档开门见山地给出了一个重要的边界：

• 改进的保真不是像素锁定（not a pixel lock）：模型会尽力保留参考图的构图、身份、文字等要素，但不会逐像素复制；
• 重复编辑会漂移（repeated edits can drift）：一次编辑保留得很好，不代表第二次、第三次编辑依然精确；
• 需要"精确未变区域"时，必须依赖合成（compositing）而非提示词：如果某个区域要求像素级原样不动，正确做法是单独做合成步骤，而不是指望生成式编辑自带该保证。

这一判断贯穿本文所有小节：提示词里的"保留列表"（preservation list）只是请求，不是保真证明；任何输出都必须靠人工/视觉 QA 验证。

2. 本地工作流：用现有 CLI 编排参考编辑

仓库为编辑任务提供了完整的本地工作流，共四步，全部围绕 scripts/generate.py 或已安装的gpt-image命令展开：

2.1 第一步：为每个输入分配角色

先检查实际输入文件（-i参数），为每个输入分配一个明确角色：基础场景（base scene）、身份（identity）、服装（garment）、风格（style）或插入对象（inserted object）。角色的分配必须与-i的重复顺序保持一致——CLI 会按-i出现的先后把文件依次传给编辑端点，顺序即"Image 1、Image 2……"的语义。

2.2 第二步：把"请求的变更"与"不变项"分开

把一次编辑严格限定为"只改什么"，并显式声明"其余全部不变"。不要因为要做一个小编辑就顺手做一次 restyle（重风格化）。如果对"如何分离变更与不变项"有疑问，只查阅 craft.md 的第 13 节（Edit endpoint prompts must preserve invariants），不要整篇加载。

craft 第 13 节给出的编辑提示词模式是：先命名目标变换 → 显式声明要保留的身份/布局/位置/可读性 → 用-i挂参考图、用-m做局部修改。多参考场景下要按序号和角色标识每个输入，例如Image 1: product photo、Image 2: style reference、Image 3: logo/packaging，并说明它们如何交互（把 Image 2 的风格套用到 Image 1 的主体上、把 Image 3 的 logo 放到包装上、保留 Image 1 的布局）。

2.3 第三步：显式指定模型，不臆测参数

模型必须显式传递：使用 models.md 核对 API 参数契约。不要臆断 2.5 需要--input-fidelity high——input_fidelity默认省略，2.5 上的显式low/high只是被转发到 API 的"选择性请求"，并非已验证的支持（详见第 5.2 节）。同时不要臆断"GPT 2.5"这个名字对应某个 API 模型 ID——裸的gpt-image-2.5不是文档化的 API 别名，模型选择必须在对话中解决后经--model显式传入。

2.4 第四步：对比变更区域与未变区域

拿到输出后，把被请求变更的区域与其余部分逐一对比。如果要做下一次经授权的编辑，把本次实际通过验收的输出文件通过-i传回去。这里有一个必须理解的 CLI 事实：CLI 不保留会话（conversation），也不会仅仅因为 prompt 里写了某个文件名就附加该图片——每次调用都是独立请求，参考图只能靠-i实际传文件。这一点在 cli.py 的实现中可以确认：编辑请求的image参数由-i解析出的文件句柄构成，prompt 只是普通字符串。

2.5 五类任务的验收清单

原文档给出的验收检查表是编辑任务的核心交付物，完整继承如下：

3. 命令行实现：-i与-m的源码级行为

3.1 端点路由：何时走/v1/images/edits

SKILL.md 定义了端点路由规则，与 cli.py 的实现一一对应：

路由判定就是call_edit(client, args) if args.image else call_generate(client, args)这一行——只要-i出现即切到编辑端点。离线测试 tests/test_cli.py 验证了该路由：带-i时请求路径为/v1/images/edits，不带时为/v1/images/generations。

3.2 多参考输入的次序与文件校验

-i是 repeatable 参数（action="append"），多次出现即构成多参考输入。call_edit在发起请求前会逐个检查-i文件是否存在，缺失即以退出码 2 终止且不发请求（见 cli.py）。测试 test_missing_edit_file_no_request 专门断言了"文件缺失 → 退出码 2 → 零请求"这一行为。但请注意：CLI 只检查文件存在性，不证明文件格式、alpha 通道或尺寸有效——这在 models.md 中明确提示，实际调用前仍需人工校验输入与 mask 的真实约束。

3.3 mask 的正确姿势

mask 是编辑指导（edit guidance），不是保证的硬像素边界：

• 多个输入同时存在时，mask作用于第一张图片（即第一个-i对应的输入）；
• mask 的尺寸必须与该图片匹配，并检查其 alpha 通道——透明区域表示要重新生成，不透明区域表示保留（CLI 帮助文本：Alpha-channel PNG mask (opaque = preserved, transparent = regenerated)）；
• 使用方式为-i 图片路径 -m 掩码路径；
• CLI 强制--mask必须伴随--image，否则直接报错退出（cli.py），测试 test_invalid_parameters_stop_before_request 覆盖了该校验；
• 还需核对官方对 mask 输入的格式约束（尺寸、alpha、通道数等）——这些约束属于 API 契约，CLI 不代为校验。

在测试 test_edit_and_multi_reference_mask_serialization 中可以看到：编辑请求以 multipart 形式序列化，-m的文件名会出现在请求体里，且编辑请求不会携带input_fidelity与moderation字段（与 models.md 中"编辑请求不要添加 moderation"的提示一致——Python 编辑签名不支持该参数）。

3.4 相关参数校验与退出码

从 cli.py 可以看到一组与编辑场景直接相关的硬校验：

• --quality xhigh/max仅允许 GPT Image 2.5 的 Flare/Sunburst（含带日期的快照）；
• --background transparent与--format jpeg冲突（透明必须 PNG 或 WebP）；
• --n限定 1–10；
• --compression限定 0–100，且 PNG 输出时该参数被忽略（output_compression仅在 jpeg/webp 时发送，见 cli.py 与测试 test_png_compression_omitted）；
• 尺寸必须为 16 的倍数、最长边 ≤3840px、长宽比 ≤3:1、总像素落在 655,360–8,294,400 之间（4K 快捷方式实际解析为3840x2160，见 cli.py 的SIZE_SHORTCUTS）。

退出码约定：0成功，1API 错误/拒绝，2参数错误或缺少密钥（cli.py）。另外客户端以OpenAI(max_retries=0)创建（cli.py），禁用自动重试，避免对可能计费的请求静默重发；测试 test_api_errors_no_fallback_or_output 验证了 403/429 时不会回退、不会切换模型、不会产出文件。

4. 透明输出与真实抠图

抠图（cutout）任务使用 2.5 专属的透明背景能力，命令形如：

gpt-image --model gpt-image-2.5-sunburst -p "给参考图 1 中的产品做透明抠图" \ -i product.jpg -f cutout.png --background transparent --format png

要点（来自原文档与 CLI 校验双重确认）：

• 必须用--background transparent --format png（或 webp），不能用 JPEG——这是 cli.py 中的硬性校验，transparent+jpeg组合直接报错；
• 检查解码后的 alpha 通道：一个画出来的棋盘格（checkerboard）图案不是透明度——常见错误是把"棋盘格底纹"当成透明底；
• 提示词里的保留列表本身不证明任何东西被保留；
• 如果任务要求"精确未动像素"，要向用户说明需要单独的合成步骤（把生成结果与原图按 alpha 蒙版合成），不要声称生成式编辑自带该保证。

5. 模型与参数选择：2.5 的保真旋钮

5.1 三个模型怎么选

按 models.md 与 SKILL.md 的模型表：

两个 2.5 模型也都有-2026-09-08结尾的快照 ID。两者都能生成和编辑，Sunburst 不是"编辑专用"模型。CLI 默认模型仍是gpt-image-2（兼容性默认），但这个默认值不能替代 Agent 对模型选择的解析——模型选择必须经--model显式传递。

5.2input_fidelity的"省略优先"

这是编辑任务最容易踩的坑，源码逻辑在 cli.py 与 cli.py：

• model_rejects_input_fidelity用正则匹配gpt-image-2及其带日期快照——只有 Image 2 及快照会被丢弃该参数，不是所有以gpt-image-2开头的名字；
• 2.5 上显式传入的low/high会被透传给 API，但这是"选择加入的请求"，官方文档并未将其宣传为 2.5 已验证支持；
• 因此默认策略是省略，直到确认所选模型的行为。测试 test_fidelity_only_dropped_for_image2 精确验证了"只对 gpt-image-2 及快照丢弃、对 2.5 透传"的分界行为。

5.3 quality 与 size 的约束

2.5 的quality取值扩大到low/medium/high/xhigh/max/auto（Image 2 到high为止，CLI 默认high）。起点建议（非保证）：

• low：廉价草稿与广泛探索，多变体需用户授权；
• medium：常规探索、风格试探、成本均衡；
• high：CLI 默认，适合最终资产、密集文字、图表与 UI；
• xhigh/max：2.5 专属，用于更高质量工作，但不应自动使用——预算敏感请求不要自动抬高质量档。

尺寸方面，文案里写"4K"不会设置 API 尺寸，尺寸由--size决定（auto、快捷方式或WIDTHxHEIGHT，含上述 16 倍数/3840/3:1/像素范围约束）。注意文档明确提示：高于 2560×1440 属于实验性，且同一 token 单价不意味着单图成本相同——请用返回的 usage 对比不同模型/尺寸/质量的真实开销。

6. 可复用的"单点变更保真编辑"模板

对于"可复用的 change-only 提示词"，原文档指向社区模板中的Single-change preservation edit（见 templates-gpt-image-2.5.md），模板全文如下：

Edit reference image 1. Change only [TARGET OBJECT OR REGION]: [PRECISE REQUESTED CHANGE]. Preserve the subject's identity, expression, pose, framing, camera viewpoint, lighting, background, and all existing text unless the requested change requires otherwise. Maintain the original material texture and image character. Do not add unrelated objects, crop, or restyle the scene.

该模板的起点配置为：用基础图做 edit、size=auto、quality=medium，且要检查返回的实际尺寸，不要假设它等于输入尺寸。注意模板的验证边界：它改编自社区作者（原帖模型为 GPT Image 1.5）的经验，未被本仓库在 2.5 上本地复现，且"保留指令"只是请求，不是保真保证。视觉 QA 要点：先对比请求区域的编辑前后，再检查本应不变的一切——尤其文字、身份、纹理、构图与尺寸；确认成功要靠视觉，不要把一个提示词约束描述成像素级锁定。

7. 仓库里的真实验证证据：Sunburst 单参考编辑

仓库的 sunburst-samples.md 记录了 2026-09-09 的五次已授权 live 运行（SDK 2.32.0、gpt-image-2.5-sunburst、quality=high、n=1、PNG、禁用自动重试），其中两次是编辑端点：

• Cafe cutaway：以既有等距咖啡馆插画为参考做剖面图编辑（/v1/images/edits，2048x2048）；
• Winter chess edit：以 chess-midgame.png 为参考做"雪夜棋盘"编辑（/v1/images/edits，1536x1024），即下方展示的输出：

运行记录显示：五次请求全部 HTTP 200、无重试、无模型切换；三次生成请求用moderation=auto，两次编辑各带一个参考，mask、input_fidelity 与编辑 moderation 均省略。视觉复核结论很值得借鉴：雪景效果可见、棋盘与棋子的可见排布"视觉上"得到保留，但仓库明确标注这不是像素级保真检查，且棋局合法性同样不在该视觉复核范围内——这与第 1 节"保真 ≠ 像素锁定"的立场完全一致。同一运行还记录了"元数据查询 404 但生成成功"的现象：models.retrieve返回404 model_not_found，随后的图像请求却全部成功——因此诊断生成失败应以实际图像端点的响应为准，而不是模型元数据。

这些样例同样展示了可复用的 QA 视角：编辑输出必须核对参考遵循度（cafe 只渲染了两层封闭楼层、少于要求的三个）与提示词一致性（poster 的刀形阴影方向与提示不符），并把这些作为可见局限记录在案。

8. 官方示例与验证边界

8.1 官方示例：选择性查阅

原文档列出 OpenAI 官方 Image Prompting 指南中与编辑相关的五类示例，可按需选择性地查阅（不是必读清单）：

• 翻译并保留布局（Translate while preserving layout）；
• 保留身份、更换服装（Preserve identity and change clothing）；
• 组合多个参考（Combine references）；
• 透明产品抠图（Create a transparent product cutout）；
• 跨轮保持角色一致（Keep a character consistent）。

对待这些示例的态度：它们是任务示例，不是拼写或事实准确性的保证，也不代表该变体一定在用户的具体需求上胜出。官方迁移提示同样强调：改进的保真不是像素锁定，重复编辑会漂移，精确未变区域需要合成而不是依赖提示词。

8.2 验证边界：哪些已验证、哪些待验证

• 离线测试：运行PYTHONPATH=src python -m unittest discover -s tests -v可执行离线套件（进程内 HTTP 响应，无凭据、无付费生成）。sunburst-samples.md 说明该套件含13 个请求/CLI 测试 + 5 个凭据来源测试，依赖下限为openai>=2.32.0，在 2.32.0 与 3.10.0（httpx2）两对版本上均通过；
• live 验证范围：仅覆盖Sunburst 生成与单参考编辑；Flare、mask、透明度、xhigh/max、2.5 显式 input_fidelity 与社区模板仍需要各自的 live 验证（见 models.md）；
• 证据纪律：不要用 mocked 请求、模型列表或他人示例当作本地成功生成；每次 release 测试前核验有效密钥来源、端点、项目与组织，记录精确的模型、提示词、尺寸、质量、响应/错误与输出路径，并对透明度、精确文字、请求的编辑与保留区域逐一检查。

9. 一句话总结这套方法论

GPT Image 2.5 的参考编辑能力在 GPT-Image2-Skill 中落成了一条可执行的流水线：分配输入角色 → 分离变更与不变项 → 显式选模型与参数（省略 input_fidelity）→ 用-i/-m组织输入 → 按任务验收清单做视觉 QA → 需要像素级保真时走独立合成。记住三件事：保真不是像素锁定、prompt 保留列表不是保真证明、CLI 不会因为提示词里写了文件名就附加图片。配套的 cli.py 实现与 tests/test_cli.py 离线测试，为这套流程提供了可复现、可审计的工程支撑。

• AI 技能
• 媒体生成
• AI 应用