OpenAI Image API

一句话说明

使用用户自己的 OpenAI 或兼容 /v1 图像接口来生成和编辑图片，并把最终图片保存到本地、检查后展示给用户。

适合谁用

• 想用自己的 API key 或中转服务生成图片的人。
• 想生成海报、插画、头像、商品图、封面、缩略图、社交媒体图、UI mockup 图片的人。
• 想用参考图、mask、局部编辑、透明背景、指定尺寸或高质量输出的人。
• 想避免每次手写 OpenAI 图片接口调用、文件保存和结果校验流程的人。

能做什么

• 文生图：一句话生成图片。
• 图生图 / 图像编辑：上传图片后修改画面内容。
• 参考图生成：用一张或多张图控制形状、风格、地形、产品或构图。
• 局部编辑：配合 mask 只修改指定区域。
• 带文字图片：生成包含中文或英文文字的海报、邀请函、标签图等。
• 透明背景：对 gpt-image-2 使用纯色色键生成加本地去背景；对支持透明背景的模型按需使用原生透明输出。
• 尺寸校验：检查提供方返回的真实宽高，避免把小图误称为 2K / 4K。
• 流式预览：在支持的接口上获取部分生成预览。

使用前配置

新用户优先阅读 references/quickstart.md。如果用户不知道怎么配置，先询问图像接口 base URL 和 API key，再运行 scripts/configure_provider.py 自动写入专用配置文件 ~/.workbuddy/openai-image-api.json。配置完成后运行 scripts/check_provider.py 检查 key、base URL 和模型列表；默认自检不会生成图片，也不会消耗图片生成额度。

至少准备以下一种配置方式：

1. Skill 专用配置，推荐给普通用户：
   - 运行 scripts/configure_provider.py。
   - 保存到 ~/.workbuddy/openai-image-api.json。
   - 只影响此技能，不改聊天模型配置。
2. 环境变量：
   - OPENAI_IMAGE_API_KEY：图像接口 API key。
   - OPENAI_IMAGE_BASE_URL：图像接口 base URL，例如 https://api.openai.com/v1 或兼容中转的 https://example.com/v1。
3. WorkBuddy 模型配置：
   - 在 ~/.workbuddy/models.json 中配置 vendor: Custom、url 和 apiKey。
   - url 必须是完整 /v1 base URL，不要写成 /v1/chat/completions。
4. Codex 配置：
   - 在 ~/.codex/auth.json 中放置 OPENAI_IMAGE_API_KEY。
   - 只有 OPENAI_API_KEY 时，调用前临时复制为 OPENAI_IMAGE_API_KEY。

不要把真实 API key 写进项目文件、提交到仓库或放进 Skill 包。

配置读取优先级：显式命令参数 > OPENAI_IMAGE_* 环境变量 > ~/.workbuddy/openai-image-api.json > 通用 OPENAI_* / WorkBuddy 模型配置。专用图像配置必须优先于通用聊天配置，避免图片请求误发到聊天端点。

用户可以怎么说

这些请求都应触发此技能：

• “生成一张科幻城市图片”
• “做一张赛博朋克风格头像”
• “根据这张参考图生成一张商品海报”
• “把这张图里的杯子换成红色”
• “给我做一张带中文标题的活动海报”
• “生成一个透明背景的猫咪贴纸”
• “用我的中转接口生成 1024x1024 图片”

WorkBuddy 执行原则

使用此技能作为普通栅格图像生成 / 编辑请求的默认路径。除非用户明确要求系统内置 imagegen，或任务更适合 SVG、HTML、CSS、canvas、矢量图或可编辑 UI 代码，否则不要绕开此技能。

沿用完整图像工作流：判断意图，必要时研究或使用参考图，整理提示词，选择生成或编辑端点，保存到 outputs/，检查输出，再把图片展示给用户。不要只返回 API 响应或文件路径。

路由规则

需要严格尺寸时使用 --size-policy warn|error|resize，必要时配合 --expected-size。默认优先保存图片并报告真实尺寸，避免误判生成失败。

提示词规则

构建提示词时包含：需求、主体、风格、构图、光照、材质、参考图角色、精确文字、约束和避免项。

带文字图片要特别处理：

• 使用 Text (verbatim): 列出所有必须出现的文字。
• 要求每条文字直接渲染在图中，且只出现一次。
• 不得遗漏、改写、添加多余文字或生成乱码。
• 最终带文字资产使用 --quality high。
• 只有当用户明确要求可编辑排版、精确字体或本地合成文字时，才改用“无文字背景 + 本地叠字”。

不要凭空添加品牌、logo、标语、人物身份、事实细节或不在用户请求里的元素。

快速命令

<skill-dir> 是占位符。Windows 默认安装路径通常是 %USERPROFILE%\.workbuddy\skills\openai-image-api。WorkBuddy 执行命令时必须替换成真实绝对路径，不要把 <skill-dir> 原样传给终端。

新手配置向导，推荐：

python "<skill-dir>\scripts\configure_provider.py" --check

WorkBuddy 代用户配置时使用非交互方式：

$env:OPENAI_IMAGE_API_KEY = "..."
python "<skill-dir>\scripts\configure_provider.py" `
  --base-url "https://provider.example/v1" `
  --api-key-env "OPENAI_IMAGE_API_KEY" `
  --model "gpt-image-2" `
  --check

如果用户同意消耗一次图像请求来确认完整链路，可追加：

  --generate-test --test-out ".\outputs\provider-check.png"

先自检配置，不生成图片：

python "<skill-dir>\scripts\check_provider.py"

确认端点可生成测试图，会消耗一次图片请求：

python "<skill-dir>\scripts\check_provider.py" `
  --generate-test `
  --out ".\outputs\provider-check.png"

普通文生图：

python "<skill-dir>\scripts\raw_image_generate.py" `
  --prompt "A cinematic sci-fi city at dusk; no text; no logos; no watermark" `
  --size "1024x1024" `
  --quality "medium" `
  --out ".\outputs\sci-fi-city.png"

中文带文字海报：

$prompt = @'
Asset type: text-bearing community event poster
Primary request: 社区读书会活动海报，温和、清爽、适合公共公告栏
Scene/backdrop: quiet library corner, wooden table, open books, soft afternoon light
Style/medium: clean modern poster design, crisp Chinese typography, balanced spacing
Composition/framing: vertical poster; large centered title; event details below; host line at the bottom
Text (verbatim):
- "社区读书会"
- "周六下午 3:00"
- "城市图书馆二楼"
- "一起阅读，一起交流"
- "社区文化中心"
Constraints: render the listed Chinese text directly inside the image; preserve every character; each listed string appears exactly once; no omitted text; no invented text; no extra captions; no garbled characters; no watermark
'@

python "<skill-dir>\scripts\image_api.py" `
  --prompt $prompt `
  --size "1024x1536" `
  --quality "high" `
  --size-policy "warn" `
  --out ".\outputs\community-reading-poster.png"

参考图生成：

python "<skill-dir>\scripts\image_api.py" `
  --prompt "Generate a new realistic product poster inspired by the reference; preserve product shape language; no text; no logo; no watermark" `
  --image ".\inputs\product-reference.jpg" `
  --image-role "product shape reference" `
  --size "1024x1024" `
  --quality "high" `
  --out ".\outputs\product-poster.png"

局部编辑：

python "<skill-dir>\scripts\image_api.py" `
  --prompt "Change only the masked area into one red paper lantern; keep all unmasked pixels unchanged" `
  --image ".\inputs\room.png" `
  --mask ".\inputs\lantern-mask.png" `
  --quality "high" `
  --out ".\outputs\room-lantern.png"

透明抠图：

python "<skill-dir>\scripts\image_api.py" `
  --prompt "Clean product cutout of one ceramic mug on perfectly flat solid #00ff00 chroma-key background; no shadows; no gradients; no text; no watermark" `
  --size "1024x1024" `
  --quality "high" `
  --out ".\outputs\mug-key.png"

python "<skill-dir>\scripts\remove_chroma_key.py" `
  --input ".\outputs\mug-key.png" `
  --out ".\outputs\mug-transparent.png" `
  --auto-key border `
  --soft-matte `
  --transparent-threshold 12 `
  --opaque-threshold 220 `
  --despill

常用参数

• --model gpt-image-2
• --mode auto|generate|edit
• --size auto|1024x1024|1536x1024|1024x1536|2048x2048|2048x1152|3840x2160|2160x3840
• --quality low|medium|high|auto
• --n 1
• --prompt-file <path>：每个非空行一条提示词
• --image <path>：可重复，最多 16 张图
• --image-role <role>：标记输入图像角色
• --mask <path>：用于局部编辑
• --background auto|opaque：不要在 gpt-image-2 上使用 transparent
• --output-format png|jpeg|webp
• --output-compression 0-100：用于 jpeg/webp
• --input-fidelity low|high：仅在支持的模型上使用；不要发给 gpt-image-2
• --base-url <https://provider.example/v1>
• --base-url-env <ENV_NAME>
• --api-key-env <ENV_NAME>
• --api-key <key>：只用于用户明确提供的一次性 key
• --timeout 1800；长任务可用 --timeout 0
• --max-retries 2 和 --retry-delay 1.0：重试 429、5xx 和网络失败
• --expected-size <WIDTHxHEIGHT>：独立校验返回尺寸
• --size-policy ignore|warn|error|resize
• --allow-upscale：只有用户明确批准或已要求放大时使用
• --dry-run：打印请求结构，不发送请求

模型选择

• 默认使用 gpt-image-2。
• 只有在用户明确要求原生透明背景，或已经选择该路径时，才使用 gpt-image-1.5。
• 只有在用户或提供方要求时，才使用 gpt-image-1 或 gpt-image-1-mini。
• 如果提供方使用不同模型名，显式覆盖 --model 并说明原因。
• 不要静默降级模型。

输出与展示

CLI 成功时 stdout 输出 JSON，进度和警告写 stderr。成功 JSON 至少包含 ok、path 或 paths、model、base_url_host、warnings；失败 JSON 至少包含 ok: false、error_type、message、hint、retryable。

示例成功输出：

{
  "ok": true,
  "path": "C:/workspace/outputs/image.png",
  "width": 1024,
  "height": 1024,
  "format": "PNG",
  "model": "gpt-image-2",
  "base_url_host": "provider.example",
  "warnings": []
}

示例失败输出：

{
  "ok": false,
  "error_type": "http_error",
  "message": "...",
  "hint": "检查 API key、base URL 和模型。",
  "retryable": false
}

生成完成后必须：

1. 确认输出文件存在。
2. 检查文件可打开、主体正确、尺寸合理、没有不需要的文字 / logo / 水印。
3. 对带文字图逐条核对 Text (verbatim)。
4. 在回复中展示图片或通过文件结果面板交付图片。
5. 报告保存路径、实际尺寸，以及必要的偏差说明。

Windows 下用于 Markdown 展示的路径要写成正斜杠绝对路径，例如 C:/Users/name/output.png。

排错指南

• 用户不知道如何配置：让用户提供 base URL 和 API key，运行 scripts/configure_provider.py --check，配置会保存到 ~/.workbuddy/openai-image-api.json。写入前会显示脱敏 key 片段和保存路径，已有配置会保留 .bak 备份。
• 缺少 Pillow：安装 Pillow>=10,<12。WorkBuddy 环境优先使用隔离 Python 环境安装，不污染用户全局环境。
• 没有 API key：优先运行 scripts/configure_provider.py；或设置 OPENAI_IMAGE_API_KEY；或在 ~/.workbuddy/models.json / ~/.codex/auth.json 中配置。
• base URL 写错：使用 https://provider.example/v1，不要写 /chat/completions。
• 模型不可用：先请求 /v1/models，确认是否存在 gpt-image-2、gpt-image-1.5 或提供方自定义模型名。
• 端点响应慢：先用短 prompt 探测；不要因为终端暂时没输出就重复发起付费请求。
• 脚本提示尺寸不符：查看实际输出文件。提供方可能返回近似尺寸或不同格式；用 --size-policy warn 记录偏差，必要时用 resize。
• 中文文字不准：先用更严格的 Text (verbatim) 重试一次，再询问是否接受本地叠字方案。
• 透明背景失败：对 gpt-image-2 使用纯色色键背景加 remove_chroma_key.py；不要直接发送 background=transparent。

资源

• scripts/provider_config.py：共享配置解析和 base URL 归一化模块。
• scripts/cli_utils.py：共享 JSON 输出、错误输出、安全下载和严格 base64 解码工具。
• scripts/configure_provider.py：新手配置向导，保存 ~/.workbuddy/openai-image-api.json 并可选自检。
• scripts/check_provider.py：配置自检 CLI，默认只检查 /models，加 --generate-test 才实际生成测试图。
• scripts/raw_image_generate.py：轻量文生图 CLI。
• scripts/image_api.py：主 Image API CLI，支持生成、编辑、参考图、mask、流式和尺寸策略。
• scripts/responses_image.py：Responses API image_generation CLI。
• scripts/smoke_test.py：离线回归验证脚本，不消耗图像生成额度。
• scripts/remove_chroma_key.py：本地色键转 alpha 工具。
• scripts/resize_image.py：跨平台缩放工具。
• scripts/resize_image.ps1：Windows 缩放备用方案。
• references/quickstart.md：给新用户的配置、自检和第一张图流程。
• references/prompting.md：提示词规则。
• references/sample-prompts.md：提示词范例。
• references/official-image-api.md：官方 API 参数说明。
• references/raw-http.md：原始 HTTP 调用说明。