GPT Image 2 CLI 使用说明（skills）

本文档说明当前目录下 gpt_image2_client.py 的安装与使用方式。

说明：当前只包含 1 个 Python 脚本，通过两个子命令实现两种能力：

• generate：文生图
• edit：图像编辑

---

1. 环境与依赖安装

Python 版本

• 建议 Python 3.10+

第三方依赖

• 无第三方依赖（仅使用 Python 标准库）

你可以直接运行：

python3 --version
python3 gpt_image2_client.py --help

---

2. 安全配置（推荐使用环境变量）

为了避免在命令行历史中暴露密钥，推荐先向用户确认并固化这两项：

• API 密钥（API_KEY）
• 接口地址（BASE_URL）

固化时注意使用合理的方案，可以放入某些配置文件，或者系统环境变量。

脚本支持以下环境变量读取顺序：

• API Key：GPT_IMAGE_API_KEY → OPENAI_API_KEY → API_KEY
• Base URL：GPT_IMAGE_BASE_URL → OPENAI_BASE_URL → BASE_URL

2.1 一次性设置（当前终端会话有效）

export GPT_IMAGE_API_KEY="你的密钥"
export GPT_IMAGE_BASE_URL="https://api.openai.com/v1"

2.2 持久化配置（推荐）

将环境变量写入 shell 配置文件（macOS zsh 默认 ~/.zshrc）：

echo 'export GPT_IMAGE_API_KEY="你的密钥"' >> /Users/peter/.zshrc
echo 'export GPT_IMAGE_BASE_URL="https://api.openai.com/v1"' >> /Users/peter/.zshrc
source /Users/peter/.zshrc

2.3 项目级配置（可选）

也可以在项目里维护 .env（注意加入 .gitignore，避免泄露）：

GPT_IMAGE_API_KEY=你的密钥
GPT_IMAGE_BASE_URL=https://api.openai.com/v1

然后在执行前手动导入（纯 shell 方式）：

set -a
source .env
set +a

---

3. 参数说明（通用）

适用于 generate 和 edit：

• --api-key：API 密钥（可选，未提供时自动读环境变量）
• --base-url：OpenAI 兼容 API 基础地址（可选，未提供时自动读环境变量）
  • 示例：https://api.openai.com/v1
• --prompt：提示词（必填）
• --auto-expand-prompt / --no-auto-expand-prompt：是否自动扩展短 prompt（默认开启）
  • 当 prompt 较短（约少于 3050 字）时，会自动扩展到更完整描述（目标约 200400 字）
  • 如需完全使用原始 prompt，可添加 --no-auto-expand-prompt
• --model：模型名（默认 gpt-image-2）
• --size：图片尺寸（默认 2160x3840）
  • 该默认值即 9:16 竖屏 4K（计算：宽 2160，高 3840）
  • 常见值（以服务端支持为准）：2160x3840、1024x1024、1536x1024、1024x1536
• --n：生成数量（默认 1，脚本仅保存第 1 张）
• --timeout：请求超时时间（秒，默认 300）
• --output：输出文件路径（默认 generated.png）

edit 专属参数：

• --image：要编辑的本地图片路径（必填）
• --mask：可选蒙版本地路径（透明区域通常可编辑）

📐 GPT-Image-2 分辨率约束条件

必须同时满足以下 4 个约束：

约束项	限制值
最大边长	≤ 3840px
边长倍数	两边都必须是 16 的倍数
长宽比	长边 ÷ 短边 ≤ 3:1
总像素数	655,360 ~ 8,294,400（约 1024×640 到 4K 之间）

🎯 常用推荐分辨率（精确像素值）

尺寸	长 × 宽	说明
正方形	1024 × 1024	通用默认
竖屏	1024 × 1536	标准竖版
横屏	1536 × 1024	标准横版（HD landscape）
2K 正方形	2048 × 2048	2K
2K 横屏	2560 × 1440	QHD
4K 横屏	3840 × 2160	实验性，效果不稳定
4K 竖屏	2160 × 3840	实验性

若用户提出的目标尺寸不符合上述规则（例如 4096×3072），应当先明确指出不合法，再重新询问用户选择一个合法尺寸。

---

4. 前置推理 / 使用方案（Prompt 不足时先询问）

如果用户只给出非常简短的 prompt（例如“画一张城市”），建议先补充澄清，至少覆盖以下维度：

1. 主体与场景：想画什么，在哪里（人物/物体/环境）
2. 风格：写实、二次元、插画、赛博朋克、国风、油画等
3. 镜头与构图：近景/中景/远景，俯拍/仰拍，是否需要留白
4. 光线与色调：白天/夜晚、暖色/冷色、霓虹/自然光
5. 质量与用途：壁纸、海报、社媒封面，是否要求 9:16 4K

可直接使用的询问模板：

为了让结果更贴近你的预期，我需要补充几个点：
1) 你想要的画面主体和场景是什么？
2) 偏好什么风格（写实/插画/动漫/赛博朋克/国风...）？
3) 画面氛围和色调（明亮、暗黑、暖色、冷色）？
4) 是否固定 9:16 竖屏 4K（2160x3840）？

当用户指定了尺寸诉求时，先执行尺寸合法性检查；若不合法，建议使用如下询问模板：

你给的尺寸不符合 GPT-Image-2 约束（最大边长≤3840、边长16倍数、长宽比≤3:1、总像素范围限制）。
请从这些合法尺寸中选一个，或给我一个满足约束的新尺寸：
1024x1024 / 1024x1536 / 1536x1024 / 2048x2048 / 2560x1440 / 3840x2160 / 2160x3840

4.1 短 Prompt 自动扩展策略（推荐）

当用户输入过短（例如少于 80~100 字，或仅一句模糊描述）时，可先自动扩展为一个结构完整的提示词，再执行请求。

建议目标：

• 扩展到约 200~400 字（推荐区间）
• 保留用户核心意图，不擅自改变主体与用途
• 优先补齐以下维度：主体、场景、动作、风格、镜头、光线、细节、质量要求

推荐流程：

1. 用户给出短 prompt；
2. 助手先给出“扩展后版本”；
3. 让用户确认“直接执行/再微调”；
4. 再调用 generate 或 edit。

默认行为：

• CLI 已内置 --auto-expand-prompt，且默认开启。
• 如需关闭自动扩展，请显式添加 --no-auto-expand-prompt。

可复用扩展示例模板：

请将以下简短需求扩写为可直接用于 GPT-Image-2 的高质量提示词，长度控制在 200~400 字，保持原意不跑题：
原始需求：<用户原文>

要求补全：
- 主体与场景
- 动作与构图
- 光线与氛围
- 材质与细节真实感
- 输出风格与清晰度要求

---

5. CLI 用法

5.0 执行与反馈默认策略

为提升可用性，默认遵循以下流程：

1. 成功保存后给出预览方式

   • 若环境允许，可直接调用系统工具打开图片进行预览（例如 macOS 使用 open <文件路径>）。
   • 若不便直接打开，则至少明确返回本地文件绝对路径，方便用户手动查看。

2. 单步失败后先停下来汇报，不连续盲重试

   • 一次调用失败后，应先反馈完整失败信息（HTTP 状态码/错误文本）。
   • 给出失败原因分析（如尺寸非法、审核拦截、超时、鉴权问题等）。
   • 然后让用户选择下一步方案（修改 prompt / 改尺寸 / 提高 timeout / 更换策略），避免未经确认频繁重试。

3.1 查看帮助

python3 gpt_image2_client.py --help
python3 gpt_image2_client.py generate --help
python3 gpt_image2_client.py edit --help

3.2 文生图（generate）

python3 gpt_image2_client.py generate \
  --prompt "a futuristic city at sunrise" \
  --model "gpt-image-2" \
  --size "2160x3840" \
  --timeout 300 \
  --n 1 \
  --output "outputs/gen_4k_vertical.png"

若你已配置环境变量，上面命令可以不带 --api-key 和 --base-url。

如需临时覆盖环境变量，也可显式传参：

python3 gpt_image2_client.py generate \
  --api-key "YOUR_API_KEY" \
  --base-url "https://api.openai.com/v1" \
  --prompt "a futuristic city at sunrise" \
  --size "2160x3840" \
  --output "outputs/gen_4k_vertical.png"

3.3 图像编辑（edit）

python3 gpt_image2_client.py edit \
  --prompt "add cinematic lighting and neon reflections" \
  --image "inputs/source.png" \
  --mask "inputs/mask.png" \
  --size "2160x3840" \
  --timeout 300 \
  --output "outputs/edited_4k_vertical.png"

3.4 关闭自动扩展（可选）

若你希望严格使用原始 prompt，不做自动补全：

python3 gpt_image2_client.py generate \
  --prompt "city" \
  --no-auto-expand-prompt \
  --output "outputs/raw_prompt.png"

---

6. 常见问题

• HTTP 4xx/5xx：优先检查 api-key、base-url、模型名、尺寸是否被服务端支持。
• The read operation timed out：可提高 --timeout，例如 --timeout 300 或更高。
• 接口未返回图片数据：说明返回体中没有 data 或 b64_json，可能是网关格式不兼容。
• 原图不存在/蒙版不存在：确认 --image / --mask 填写的是本机真实路径。

---

7. 失败处理与决策分流（推荐）

当单次调用失败时，建议按下面模板反馈并等待用户决策：

本次调用失败：<错误摘要>
可能原因：<1~3条>
你希望我下一步怎么做？
1) 调整尺寸
2) 调整提示词
3) 提高超时
4) 其他（你指定）