GPT Image 2 API Key

概述

通过运行 scripts/generate_image.py，使用独立配置的 gpt-image-2 提供商生成或编辑图像。当图像生成需要使用独立的 API 密钥进行计费、认证并与 Codex 当前的 OpenAI/Codex 凭据隔离时，请使用此技能。

该技能刻意不读取 OPENAI_API_KEY、Codex 认证文件或 ChatGPT/Codex 会话凭据。它仅读取由 --config 指定的私有配置文件，或下方记载的默认配置文件。

解决的问题

此技能解决了一个常见的 Codex 工作流问题：当前 Codex 会话可能已使用一个 API 密钥进行了认证，而图像生成需要使用另一个密钥、另一个账户、另一个配额或一个兼容 OpenAI 的代理。

使用此技能可以：

将图像生成凭据与 Codex 自身的凭据分开。
从 Codex 调用 gpt-image-2 或兼容的图像端点，而无需在提示词、命令或仓库文件中暴露密钥。
通过 /v1/images/generations 生成图像。
通过 /v1/images/edits 使用多部分上传编辑现有图像。
使用一个或多个参考图像进行编辑、重样式、徽标处理、产品模型转换及图像到图像的转换。
可选地为限定区域的编辑提供蒙版图像。
将生成的结果保存到明确的本地路径，以便 Codex 显示、检查或传递给后续步骤。

用例

对于以下请求，请使用此技能：

"生成一个带有确切文本 JunXxxxi 的徽标。"
"使用此参考图像，并将字标改为斜体。"
"将此徽标文本更改为银黑渐变金属效果。"
"使用 gpt-image-2 创建产品图像，但使用我独立的图像 API 密钥。"
"编辑此图像，同时保留原始构图。"
"使用自定义基础 URL 的兼容 OpenAI 的图像提供商。"

当所需的更改是简单的像素级转换，且必须保留精确几何形状（例如裁剪、缩放、Alpha 通道转换或完全确定性的颜色重映射）时，请优先使用确定性的本地图像处理，而不是此技能。当用户希望进行基于模型的视觉解释、重样式或生成时，请优先使用此技能。

内容

gpt-image-2-apikey/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_image.py

SKILL.md：面向 Codex 的工作流和面向用户的使用文档。
agents/openai.yaml：可选的 Codex UI 元数据。
scripts/generate_image.py：零依赖 Python 3 脚本，用于调用生成或编辑端点。

该脚本同时支持 b64_json 和 URL 形式的图像响应。URL 响应会立即下载并写入请求的输出路径。

私有配置

默认配置路径：

~/.config/gpt-image-2-apikey/config.json

配置中必须包含图像提供商的密钥，而不是 Codex 当前的 API 密钥：

{
  "api_key": "put-image-provider-key-here",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-image-2"
}

创建文件后，设置私有权限：

chmod 600 ~/.config/gpt-image-2-apikey/config.json

仅当用户明确需要另一个私有配置文件时，才使用 --config /path/to/config.json。

配置字段

api_key：必需。图像提供商的密钥。除非明确需要，否则不要使用 Codex 当前的 API 密钥。
base_url：可选。默认为 https://api.openai.com/v1。对于兼容 OpenAI 的提供商，请保留在 API 根路径，例如 https://example.com/v1。
model：可选。默认为 gpt-image-2。
extra_body：可选对象。这些值将合并到请求体中，用于提供商特定的字段。

base_url 的好示例：

{
  "base_url": "https://api.openai.com/v1"
}

{
  "base_url": "https://www.packyapi.com/v1"
}

除非您有意固定一个确切的端点，否则不要在 base_url 中包含 /images/generations 或 /images/edits。该脚本通常会自动附加正确的端点。

用法

从技能目录运行：

python3 scripts/generate_image.py \
  --prompt "A clean product photo of a matte black mechanical keyboard on a walnut desk" \
  --out /absolute/path/to/output.png \
  --size 1024x1024 \
  --quality high

如果省略 --edit-image，脚本调用：

POST <base_url>/images/generations

通过添加 --edit-image 来编辑一个或多个参考图像：

python3 scripts/generate_image.py \
  --prompt "Turn this logo into italic silver-to-black gradient text while preserving the exact spelling" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/edited.png \
  --size 1024x1024 \
  --quality high

如果提供了 --edit-image，脚本调用：

POST <base_url>/images/edits

对于蒙版编辑，添加 --mask /absolute/path/to/mask.png：

python3 scripts/generate_image.py \
  --prompt "Only change the background to a clean studio gray, preserving the subject" \
  --edit-image /absolute/path/to/source.png \
  --mask /absolute/path/to/mask.png \
  --out /absolute/path/to/edited.png \
  --quality high

重复 --edit-image 以进行多图像编辑：

python3 scripts/generate_image.py \
  --prompt "Combine the product from image 1 with the background mood from image 2" \
  --edit-image /absolute/path/to/product.png \
  --edit-image /absolute/path/to/background-reference.png \
  --out /absolute/path/to/combined.png

当用户需要文件放在特定位置时，始终提供绝对路径的 --out。如果省略，脚本会在当前工作目录写入一个带有时间戳的 PNG。

命令参考

--prompt       必需的图像提示或编辑指令。
--out          输出图像路径。额外输出会在扩展名之前使用 -2、-3 等。
--config       私有配置路径。默认为 ~/.config/gpt-image-2-apikey/config.json。
--model        覆盖配置文件中的模型。
--size         提供商支持的图像尺寸。默认：1024x1024。
--quality      低、中、高或自动。默认：自动。
--n            图像数量。默认：1。
--format       png、jpeg 或 webp。默认：png。
--edit-image   用于 /v1/images/edits 的输入图像路径。可重复。
--mask         可选的编辑用 PNG 蒙版路径。
--timeout      HTTP 超时秒数。默认：600。
--dry-run      打印脱敏的端点、主体和文件列表，不调用 API。

在检查配置、端点路由或编辑是否将使用预期的输入文件之前，可以先使用 --dry-run 进行试运行：

python3 scripts/generate_image.py \
  --prompt "dry run only" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/output.png \
  --dry-run

试运行输出会将授权信息脱敏为 Bearer ***redacted***。

提示词指南

对于生成：

明确说明资产类型、主体、风格、布局和所需文本。
将确切的可见文本放在引号中。
在处理徽标、海报或 UI 图形时，包含 "no extra text, no watermark"。
对于最终徽标、文字密集的图像、产品照片和精加工交付件，使用 quality high。
对于低成本探索和快速草稿，使用 quality low。

对于编辑：

描述更改，而不是整个图像，除非整个图像需要重新诠释。
明确说明必须保留的内容：文本拼写、布局、构图、面部身份、产品形状、颜色或背景。
对于文字密集的图形，在提示词中重复确切的拼写和大小写。
在提供商支持的情况下，使用蒙版进行精准编辑。

编辑提示词示例：

Edit the provided logo image. Preserve the exact text "JunXxxxi" and the same wordmark layout. Make the lettering italic/slanted to the right. Change the letter fill to a metallic gradient from bright silver on the left/top to deep black on the right/bottom. Keep a clean white background. Do not add extra words, icons, watermarks, borders, or decorative elements.

隔离规则

不要将 Codex 当前的 API 密钥传递或复制到此技能中。
不要读取 OPENAI_API_KEY；该脚本有意忽略它。
不要打印 api_key 或配置内容。该脚本仅在使用 --dry-run 时报告脱敏的配置摘要。
如果配置文件缺失，请告知用户创建私有配置文件。除非用户明确要求，否则不要代其创建包含真实机密的文件。
如果提供商使用兼容 OpenAI 的端点，请在私有配置中设置 base_url。该脚本会为生成附加 /images/generations，为编辑附加 /images/edits。

配置注意事项

将 config.json 保留在 Git 之外。切勿提交真实的 API 密钥。
为私有配置文件设置文件模式 600。
除非提供商另有说明，否则将 base_url 保留在 API 根路径 (.../v1)。
如果提供商需要自定义请求字段，请将它们放在 extra_body 下。
如果提供商不支持 gpt-image-2，请将 model 设置为提供商兼容的模型名称。
如果提供商仅支持 URL 响应，该脚本将下载返回的 URL。
如果提供商在 b64_json 中返回 base64 图像，该脚本将直接解码。
网络调用可能会在配置的提供商账户上产生费用。

包含提供商特定字段的示例：

{
  "api_key": "put-image-provider-key-here",
  "base_url": "https://example.com/v1",
  "model": "gpt-image-2",
  "extra_body": {
    "moderation": "auto"
  }
}

故障处理

缺少配置或缺少 api_key：报告配置路径和必填字段。
HTTP 错误：显示状态码和提供商的错误主体，但绝不包含密钥。
不支持的提供商响应：报告顶层的响应键，不保存文件。
多图像：第一个图像使用 --out；其他图像在扩展名前使用 -2、-3 等。

局限性

此技能是一个 API 包装器，而非完整的图形编辑器。对于精确裁剪、缩放、矢量导出或保证像素级完美的排版更改，请使用确定性的本地工具。
基于模型的图像编辑可能会改变确切的文本、字间距或几何形状。对于徽标和字标，请在交付前检查结果。
多部分编辑的兼容性在不同的兼容 OpenAI 的提供商之间可能有所不同。如果编辑失败但生成成功，请检查提供商是否支持使用多部分 image 上传的 /v1/images/edits。
为支持多图像，该脚本目前使用多部分字段名 image[] 发送编辑图像。如果提供商需要不同的字段名，请修改 scripts/generate_image.py 以适应。
真正的透明背景行为取决于提供商/模型的支持。如果需要透明 PNG，请在生成后检查 Alpha 通道。

发布注意事项

当将此技能发布到 GitHub 时：

包含 SKILL.md、agents/openai.yaml 和 scripts/generate_image.py。
不要包含 ~/.config/gpt-image-2-apikey/config.json。
除非是特意示例，否则不要包含生成的图像。
如果此技能位于更大的仓库中，请为本地配置、输出和临时图像添加 .gitignore 条目。

GPT Image 2 API Key 技能