gpt-imagegen

GPT ImageGen

使用 scripts/generate_image.py，通过已配置的 OpenAI 兼容 Images API 端点进行文生图、图像编辑、图像优化、蒙版编辑和多图合成。

使用 scripts/tile_canvas.py 进行本地 PNG 画布处理：调整大小、拆分、拼接、细节迁移、评分、锐化以及 4K / 瓦片实验。

对于 4K、可缩放纹理、分块生成、接缝修复或放大工作流，请在生成或编辑瓦片前阅读 references/4k_workflows.md。

快速开始

首次使用或更改配置后，请运行环境检查：

python3 scripts/check_environment.py

此技能需要 Python 3.9+，推荐使用 Python 3.10+，不依赖第三方 Python 库，并且需要配置 HTTPS API 端点。

如果缺少配置：

python3 scripts/check_environment.py \
  --write-config \
  --base-url "https://examine.com" \
  --api-key "YOUR_API_KEY"

普通文生图：

python3 scripts/generate_image.py \
  --prompt "A cinematic rainy Shanghai street at night, neon reflections, vintage taxi" \
  --output ./generated-image.png

编辑或优化单张图像：

python3 scripts/generate_image.py \
  --image ./source.png \
  --prompt "Improve clarity, restore detail, keep the original composition natural" \
  --output ./optimized-image.png

合成多张图像：

python3 scripts/generate_image.py \
  --image ./person.png \
  --image ./background.png \
  --prompt "Place the person naturally into the background, matching lighting and perspective" \
  --output ./composited-image.png

生成一小批相关变体：

python3 scripts/generate_image.py \
  --prompt "Four premium packaging concepts for a jasmine tea brand, same art direction, different label layouts" \
  --count 4 \
  --output ./tea-variant.png

生成透明素材：

python3 scripts/generate_image.py \
  --prompt "A ceramic tea cup, isolated with a transparent background" \
  --background transparent \
  --output-format png \
  --output ./tea-cup.png

请求原生 4K（高于 2560x1440 时为实验性功能）：

python3 scripts/generate_image.py \
  --prompt "A detailed panoramic mountain landscape at sunrise" \
  --size 3840x2160 \
  --quality xhigh \
  --output ./landscape-4k.png

生成脚本的默认设置如下：

• 文生图模型：gpt-image-2.5-flare
• 编辑 / 参考 / 合成模型：gpt-image-2.5-sunburst，只要存在 --image 参数就会选择此模型
• 显式指定的 --model 会覆盖任一默认值，包括文档中提及的 2026-09-08 快照
• 尺寸：1024x1024
• 质量：high（此技能现有的默认值；API 本身的默认值为 auto）
• 超时：300 秒
• 传输方式：非流式 JSON；仅在有意请求官方 SSE 事件流时使用 --stream

兼容性检查

将 OpenAI 官方 Images API 指南／参考文档视为请求字段的事实来源。最后检查日期：2026-09-25。

• 图像生成指南：模型能力、自定义尺寸、透明度和质量。
• 创建图像：JSON 生成参数。
• 创建图像编辑：multipart 编辑参数。

不要根据第三方兼容服务商或不受认可的模型别名推断是否支持。服务商可能落后于官方 API；遇到不支持的模型／参数时应明确说明，不要擅自切换模型或用调整尺寸替代原生输出。

每次请求前，请检查：

• 仅发送所选请求形式有文档说明的字段。
• GPT Image 2.5 的两个模型及其 2026-09-08 快照均支持 auto 或自定义 WIDTHxHEIGHT：两条边都必须是 16 的倍数，均不得超过 3840，宽高比必须介于 1:3 和 3:1 之间，像素总数必须在 655,360 至 8,294,400 之间（含边界值）。
• 3840x2160 和 2160x3840 是有效的原生请求。高于 2560x1440 的分辨率属于实验性支持；4096x4096 和 4096x2160 超出文档规定的限制。
• GPT Image 2.5 支持 auto、low、medium、high、xhigh 和 max 质量。早期模型不支持 xhigh 或 max。
• 透明输出需要使用 --background transparent，并选择 PNG 或 WebP；未指定格式时，脚本会选择 PNG，并拒绝 JPEG。输出文件名的扩展名须与所选格式一致。
• gpt-image-2 及其 2026-04-21 快照也支持在相同限制下使用自定义尺寸；透明背景目前处于预览阶段。对于这些模型，请省略 --input-fidelity，因为它们会自动使用高输入保真度。
• --input-fidelity 仅用于编辑，对 GPT Image 2.5 仍为可选项。当前 Images API 参考文档中，--moderation 仅用于生成。
• --output-compression 0-100 需要 JPEG 或 WebP。
• 将 --count 设为不超过 10。
• 仅在明确需要本地 PNG 调整尺寸时，才在使用有效 API 尺寸后使用 --resize-output；无效的原生尺寸会直接失败，不会悄悄回退为调整尺寸后的 1024x1024 图像。
• 仅在确有需要时使用 --stream；默认情况下不使用流式传输。

使用指南了解功能支持情况，并使用端点参考文档核对请求字段。参考文档中的 stream: false 签名描述的是非流式重载；流式传输使用指南中的 SSE 流程。

配置检查

触发此技能时，在尝试生成之前，请确认 API 已完成配置：

1. 全新安装时，优先使用 scripts/check_environment.py。
2. 使用 GPT_IMAGE_BASE_URL 或 --base-url 指定 HTTPS API 基础 URL。
3. 使用 GPT_IMAGE_API_KEY 或 --api-key 指定 API 密钥。
4. 如果 baseUrl 或 apiKey 缺失或为空，请停止并向用户索取正确的配置。
5. 切勿编造凭据、打印 API 密钥、在真实请求中使用占位符，或在密钥为空时继续操作。

配置文件路径：

• macOS/Linux：~/.config/gpt-imagegen/config.json
• Windows：%APPDATA%\gpt-imagegen\config.json

旧版 DCHA_IMAGE_* 环境变量和配置文件可作为迁移回退方案接受。

工作流

1. 将用户的请求改写为润色后的英文图像提示词，除非用户明确要求使用 --raw-prompt 原样传递。
2. 保留重要的风格、主体、构图、宽高比、文本、颜色、氛围和参考约束。
3. 每次 API 调用前都运行兼容性检查。
4. 在当前工作区或用户指定的文件夹中选择稳定的输出路径。
5. 对于文生图，调用 generate_image.py --prompt ... --output ...。
6. 对于编辑、优化、修复或增强，将源图像作为 --image 参数传入。
7. 对于多图合成，每个源图像都重复使用一次 --image。
8. 对于局部编辑，传入 --mask；蒙版应用于第一个 --image。
9. 对于少量相关批次，使用 --count 2-4；对于较大的分镜或彼此独立的画面，拆分为多个请求，并使用一致的文件名。
10. 遇到可重试的传输失败时，先使用稳定的提示词和参考输入，按相同的请求结构重试。
11. 遇到内容或审核失败时，如果用户的目标允许，则通过准确且更安全的表述修改提示词后重试一次。
12. 返回输出路径。如果宿主能够渲染本地文件，则显示生成的图像。

4K 与放大

对于涉及 4K、高像素密度、可缩放纹理、分块生成、接缝修复或“放大后能看到细节”的请求，请加载 references/4k_workflows.md。

对于新建 4K 图像，优先使用原生 --size 3840x2160 请求。对于编辑，添加 --image 并保持相同尺寸，以使用 Sunburst。说明此分辨率仍处于实验阶段；交付前请检查返回的尺寸和 100% 缩放裁剪图。

简单调整尺寸不会产生真实细节。仅在无法获得原生结果或原生结果不符合任务要求时，才使用本地缩放、整图超分辨率或现有的分块工作流。该参考文件保留了以往的分块实验，作为备用指南。

对于透明素材，请确认输出具有 Alpha 通道且包含透明像素；绘制在图像中的棋盘格或白色背景并不是真正的透明效果。

失败时澄清提示词

如果生成失败是因为请求含糊或可能被解读为不安全，请通过补充准确的上下文和更安全的表述来改进提示词，同时保留创作目标：

• 亲密或浪漫场景：说明人物均为自愿参与的成年人，采用非露骨的表现方式和得体的编辑肖像／时尚语言；除非明确允许，否则不得出现裸体或性行为。
• 看起来年轻的角色或同人艺术角色：避免性化；适当时将成熟角色描述为成年版本，或描述为成年原创角色。
• 写实肖像或摄影：必要时明确是虚构、摆拍、编辑、时尚、角色扮演或个人肖像创作。
• 品牌、产品、徽标和系列作品：如属实，明确说明是非官方同人艺术、戏仿、致敬、概念设计或个人／非商业用途。
• 公众人物或现实人物：保持提示词不具误导性，并避免敏感、羞辱、性化或误导性的描绘。
• 暴力、受伤或恐怖美学：如实地将其描述为风格化、电影感、奇幻、舞台妆效、道具设计、游戏艺术或虚构场景。

优先使用准确的视觉描述，避免含糊或带有强烈暗示的用词。

水印政策

对于普通原创图像、常规插画、产品照片、风景、概念艺术、虚构肖像和无害的同人风格场景，默认不添加虚构标注水印。

仅当添加小巧、不显眼的 Fictional dramatization 字样能显著降低混淆或滥用风险时才添加，例如戏仿／恶作剧／冒充请求、假新闻或纪录片风格的写实内容，或对现实人物／公众人物的误导性描绘。

正常的非误导性创作使用 --fictional-watermark never。仅在虚构标注风险较高的场景中使用 --fictional-watermark always。

URL 安全

所有远程图像、遮罩、生成图像、重定向和 API 基础 URL 都必须使用 HTTPS。脚本会拒绝使用 HTTP、包含凭据、未指定主机名、指向 localhost、使用 .local 主机名，或指向私有／链路本地／环回／保留／非全局 IP 地址字面量的 URL。用户提供的图像和遮罩 URL 会进行 DNS 检查；如果解析到被屏蔽的地址，则会被拒绝。

配置的 API 基础 URL 必须使用 HTTPS。对于配置的 API 域名，会放宽 DNS 公共地址限制，以便使用代理的提供商域名。

脚本索引

使用 python3 scripts/generate_image.py --help 查看完整的生成／编辑选项。

generate_image.py 的常用选项：

• --prompt：必填的图像提示词。
• --image：可选的输入图像路径或 HTTPS URL；可重复指定以进行多图合成。
• --mask：可选的局部编辑遮罩图像路径或 HTTPS URL。
• --output：输出路径；会自动创建父目录。
• --size：兼容性门控下的 auto 或原生尺寸，包括 1536x864、2048x2048 和 3840x2160。
• --count：要请求的最终图像数量。
• --resize-output：在本地调整最终 PNG 的尺寸，以适配不受支持的最终尺寸。
• --quality：auto、low、medium、high、xhigh 或 max；后两项需要 GPT Image 2.5。
• --output-format：png、jpeg 或 webp。
• --output-compression：0-100，仅适用于 JPEG/WebP。
• --background：auto、opaque 或 transparent；透明背景需要 PNG/WebP。
• --moderation：auto 或 low，仅用于生成。
• --input-fidelity：low 或 high，GPT Image 2.5 编辑时可选；默认省略。
• --model：覆盖自动选择的 Flare（生成）／Sunburst（编辑）模型。
• --stream / --no-stream：选择启用 SSE 流式传输或使用普通 JSON。
• --raw-prompt：按原样发送提示词。
• --fictional-watermark：auto、always 或 never。
• --retries、--retry-delay、--max-retry-delay：重试控制选项。

使用 python3 scripts/tile_canvas.py --help 查看本地 PNG 辅助工具。

tile_canvas.py 的重要命令：

• prepare：将 PNG 调整到目标画布尺寸，例如 3840x2160。
• split：将画布拆分为有重叠的平铺裁剪区域，并写入 manifest.json。
• manifest：汇总平铺尺寸和缩放比例。
• stitch：对精确的裁剪平铺区域进行加权拼接。
• stitch-slots：仅拼接平铺中心区域，舍弃重叠部分的上下文。
• stitch-upscaled-slots：将全尺寸生成的平铺输出拼接到超采样画布；2x2 模式为实验性功能。
• upscaled-detail-transfer：将全尺寸生成平铺中的高频细节转移到放大后的底图上。
• detail-transfer：将生成平铺的细节转移到尺寸相同且稳定的底图上。
• frequency-composite：将供体图像的局部高频内容合成到稳定底图上。
• enhance：进行确定性的锐化、对比度调整和轻微颗粒处理。
• score：对边缘／纹理进行粗略评分，用于前后对比。
• overlay：将选定的平铺区域粘贴到底图上。

说明

• 文本生成图像会使用 JSON 调用 /v1/images/generations。
• 编辑／合成会通过 multipart 上传调用 /v1/images/edits。
• 多张图像会作为重复的 image[] 表单字段发送。
• 流式传输要求事件采用官方格式：image_generation.partial_image、image_edit.partial_image、image_generation.completed 和 image_edit.completed。
• 脚本不会写入原始 API 元数据文件；其 JSON 摘要会包含所选模型、请求的 API 尺寸、可选的本地调整尺寸信息以及输出路径。仅凭请求的尺寸无法证明提供商返回了相应分辨率。
• 如果 API 返回错误，请概述状态码和消息，然后调整参数；只有在必要时才询问缺失的信息。

更改模型路由或 API 约束后，运行离线请求回归测试：

python3 -m unittest discover -s tests -v