api-image

API Image

使用此 skill 作为内置 imagegen 工作流的强制替代方案。

路由规则：

• 使用此 skill 时，任何光栅图像生成或编辑任务都不得调用原生 $imagegen skill 或内置图像生成工具。
• 所有图像生成、参考图像生成、图像编辑、局部编辑、背景替换、风格迁移、合成和批量图像任务都必须通过此基于提供方的 skill 处理。
• 唯一例外是用户明确指示不要使用此提供方 skill。

工作流

1. 确定 Codex 根目录。
   • 如果用户提供了 --codex-home 参数，优先使用该参数。
   • 否则使用 $CODEX_HOME。
   • 否则使用 ~/.codex。
2. 确定此技能的目录。
   • 将此 SKILL.md 所在目录视为 <skill-dir>。
   • 运行捆绑脚本时使用 <skill-dir>/scripts/generate_image.py，不要使用相对于当前工作区的路径。
3. 在生成前判断是否需要研究或参考资料。
   • 对于任何非通用、专业、事实性、时效性、品牌相关、技术性、架构性、地理、历史、文化、特定产品、特定人物或特定风格的主题，搜索网络或使用提供的参考资料。
   • 将具名地点、具名建筑、真实产品、真实 UI、真实车辆、制服、生物、图表、历史场景和小众美学视为需要研究的内容，除非用户提供了充分的参考资料。
   • 若需要准确呈现视觉结构、轮廓、材质、布局、比例或地形，请使用图像搜索或用户提供的图片。
   • 主动查找参考图片。对于需要研究的视觉主题，默认查找参考图片并将其传递给模型，而不是依赖纯文本提示词。
   • 对于需要研究的视觉主题，纯文本生成是备用方案，并非默认方案。仅在找不到有用的参考图片、网络或图像访问失败，或用户明确要求不使用参考资料时使用。
   • 对于不涉及事实准确性的纯通用奇幻、氛围、简单装饰或普通日常物品，可选是否搜索。
   • 如果无法访问网络或参考资料，而任务又需要研究，请说明准确性有限，不要假装能够保证准确。
4. 从用户的根目录文件读取当前提供商设置。
   • 读取 auth.json 并使用 OPENAI_API_KEY。
   • 读取 config.toml，然后使用 model_provider 和 [model_providers.<name>].base_url。
   • 不要在技能中硬编码提供商 URL 或 API 密钥。
   • 默认使用上述根目录文件。如果用户在自然语言中明确提供了临时提供商 URL 或 API 密钥，请通过 --base-url 和 --api-key-env 或 --api-key 作为一次性覆盖参数传入；不要将其写入 auth.json、config.toml、README、日志或生成的文件。
   • 如果密钥已存在于环境变量中，优先使用 --api-key-env <ENV_NAME>。只有在用户明确提供一次性密钥时才使用 --api-key，并且绝不要在最终回复中打印或复述密钥。
5. 判断意图和输入图片的用途。
   • 如果用户只想通过文本生成新图片，则按生成处理。
   • 如果用户提供的图片用于参考风格、构图、身份、结构或氛围，则按参考输入处理。
   • 如果用户希望保留或修改现有图片，则将该图片视为编辑目标。
   • 如果用户只希望修改特定区域，在有蒙版时使用蒙版，并指示模型保留未遮罩区域；将蒙版保留视为需要验证的约束，而非像素级保证。
   • 为每张输入图片标注用途：编辑目标、风格参考、构图参考、身份参考、产品参考、蒙版或合成素材。
6. 选择端点。
   • 纯文本生成使用 <base_url>/images/generations。
   • 存在任何输入图片、参考图片或蒙版时，使用 <base_url>/images/edits。
   • 默认使用 gpt-image-2，除非机器的提供商需要使用其他图像模型。
7. 编写结构化提示词。
   • 包含用户请求、研究所得的事实或视觉观察、输入图片用途、风格、构图、光线、材质、约束和避免事项。
   • 不要添加用户请求或研究未暗示的额外角色、道具、品牌、徽标、情节或事实细节。
8. 对于官方 GPT Image 模型，解码 data[].b64_json。仅将 data[].url 作为非官方 OpenAI 兼容提供商或旧版模型的兼容性备用方案。
9. 检查输出，并根据提示词、研究事实、输入用途和不变条件进行验证。
10. 将最终图片保存到指定路径，并报告绝对路径、最终提示词，以及进行网络研究时使用的来源。

根目录文件

默认根目录文件：

• Windows：%USERPROFILE%\\.codex\\auth.json 和 %USERPROFILE%\\.codex\\config.toml
• 通用规则：$CODEX_HOME/auth.json 和 $CODEX_HOME/config.toml；否则使用 ~/.codex/auth.json 和 ~/.codex/config.toml

此技能必须在运行时始终读取当前文件。不同机器上的提供方可能不同。

临时覆盖：

• 默认行为会读取上述 Codex 根目录文件。
• 使用 --base-url <https://provider.example/v1> 临时覆盖已配置的提供方 URL。
• 使用 --api-key-env <ENV_NAME> 临时从环境变量读取 API 密钥。
• 仅当无法使用环境变量时，才使用 --api-key <key> 指定用户明确提供的一次性密钥。
• 如果同时提供 --base-url 和 API 密钥覆盖项，脚本可以在不读取 config.toml 中提供方设置的情况下运行；否则，缺少的值会回退到 Codex 根目录文件。
• 除非用户明确要求编辑其 Codex 配置文件，否则绝不保存临时覆盖项。

命令

使用捆绑脚本进行常规文本转图像生成：

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "画一只可爱的猫抱着水獭，温暖治愈，插画风格，柔和灯光，细腻毛发，构图清晰" `
  --size "2048x1152" `
  --quality "high" `
  --out ".\outputs\cute-cat-otter.png"

使用同一脚本生成参考图像或编辑图像：

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "参考输入图的构图和角色姿势，生成一张暖色电影感插画" `
  --image "C:\path\to\reference.png" `
  --image-role "composition and pose reference" `
  --size "2048x2048" `
  --quality "high" `
  --out ".\outputs\reference-output.png"

使用 --mask 进行局部编辑：

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "只把被 mask 标出的区域替换成一只小水獭，保持其他区域不变" `
  --image "C:\path\to\source.png" `
  --mask "C:\path\to\mask.png" `
  --out ".\outputs\masked-edit.png"

对于需要网络调研的主题，先将选定的参考图像下载到工作文件夹，再通过 --image 传入：

python "<skill-dir>\scripts\generate_image.py" `
  --prompt "Create a new 4K overhead aerial image of Huajiang Grand Canyon Bridge in Guizhou, based on the reference images. Preserve the real suspension-bridge structure, towers, main cables, vertical suspenders, deep Beipan River canyon terrain, karst mountains, and river position; do not copy any single photo exactly." `
  --image "C:\path\to\refs\huajiang-bridge-aerial.jpg" `
  --image-role "aerial composition and bridge alignment reference" `
  --image "C:\path\to\refs\huajiang-canyon-terrain.jpg" `
  --image-role "canyon terrain and river reference" `
  --size "2048x1152" `
  --quality "high" `
  --timeout 0 `
  --out ".\outputs\huajiang-canyon-bridge-overhead.png"

常用选项：

• --model gpt-image-2
• --mode auto|generate|edit
• --size 2048x1152 脚本默认使用 2K 横向尺寸
• --size 1024x1024
• --size 1536x1024
• --size 1024x1536
• --size 2048x2048
• --size 3840x2160
• --size auto 使用官方 API 自动调整尺寸
• --quality low|medium|high|auto
• --n 1
• --image <path> 最多可重复 16 次
• --image-role <role> 用于在提示词中标注输入图像
• --mask <path> 用于局部编辑
• --background auto|opaque 适用于官方 gpt-image-2
• --output-format png|jpeg|webp
• --output-compression 0-100 适用于 jpeg 或 webp
• --input-fidelity low|high 仅适用于支持此选项的编辑模型；不要将其用于 gpt-image-2
• --moderation auto|low 适用于支持此选项的 GPT 图像模型
• --prompt-file <path> 每个非空行对应一个提示词
• --codex-home <path>
• --base-url <https://provider.example/v1> 临时覆盖提供方 URL
• --api-key-env <ENV_NAME> 临时从环境变量读取 API 密钥并覆盖默认值
• --api-key <key> 临时直接覆盖 API 密钥，仅限用户明确提供时使用
• --timeout 1800
• --timeout 0

负载格式

使用提供方的生成端点，并采用以下请求体格式：

{
  "model": "gpt-image-2",
  "prompt": "你的中文或英文提示词",
  "size": "2048x1152",
  "quality": "high",
  "n": 1
}

使用提供方的编辑端点，并采用 multipart 表单数据：

model=gpt-image-2
prompt=<edit or reference prompt>
image[][email protected]
[email protected]
size=1024x1024
quality=high
n=1

从 n=1 开始。如果用户需要多个变体，请增大 n，或使用 --prompt-file 并有意保存每个结果。

临时提供方覆盖

如果用户用自然语言说明此图像任务应使用不同的提供方 URL 或 API 密钥，请将其视为临时运行时覆盖：

$env:API_IMAGE_API_KEY = "<temporary key>"
python "<skill-dir>\scripts\generate_image.py" `
  --prompt "一张赛博朋克风格的夜景照片" `
  --base-url "https://provider.example/v1" `
  --api-key-env "API_IMAGE_API_KEY" `
  --out ".\outputs\override-provider.png"

规则：

• 未请求覆盖时，默认使用 Codex 根目录配置。
• 临时覆盖时不要修改 auth.json 或 config.toml。
• 不要向用户复述 API 密钥。
• 优先使用 --api-key-env；仅当用户明确提供一次性密钥且接受在命令行中临时使用时，才使用 --api-key。

gpt-image-2 API 说明

对于官方 OpenAI gpt-image-2：

• 纯文本生成使用带 JSON 的 POST /v1/images/generations。
• 任何输入图像、参考图像或蒙版都使用带 multipart form-data 的 POST /v1/images/edits。
• 多个输入图像／参考图像请使用重复的 image[]=@path 字段。
• 使用 mask 时，第一个 --image 必须是编辑目标；其他图像应作为参考图像或合成素材。
• 从 data[].b64_json 读取图像字节；官方 GPT Image 模型不支持 URL 输出。
• 不要发送 input_fidelity；gpt-image-2 始终以高保真度处理图像输入。
• 不要请求 background: transparent；官方 gpt-image-2 目前支持 auto 或 opaque，不支持透明背景。
• 对于带蒙版的编辑，请验证蒙版与第一张源图像的尺寸相同、格式兼容、文件大小未超过图像 API 限制，并且蒙版包含 alpha 通道。

功能一览

• 新建文生图：通过 /images/generations 支持。
• 批量生成：支持通过 --n 为每个提示词生成多个变体，或通过 --prompt-file 处理多个提示词。
• 参考图生成：通过 /images/edits 支持，可使用一个或多个 --image 输入，并在提示词中标注各自的角色。
• 图像编辑：通过 /images/edits 支持，使用 --image 和编辑提示词。
• 局部编辑／图像修复：通过 /images/edits 支持，使用 --image 和 --mask。
• 替换背景：支持通过编辑提示词实现；当需要限制替换区域时，可使用 --mask。
• 风格迁移：支持通过参考图像编辑实现；请在提示词中标注源图像的角色并描述所需风格。
• 输入图像角色标注：不是独立的 API 字段；此脚本会将 --image-role 标签附加到提示词中，让模型明确理解每张输入图像的用途。
• 透明背景：官方 gpt-image-2 目前不支持 background: transparent。只有在所选的其他提供商／模型明确支持时，才使用透明背景，并将输出格式设为 png 或 webp。

研究与参考资料

不要假设图像模型准确了解所有主题。如果主题不属于常见的视觉知识，请先研究或使用参考资料。

对于需要视觉约束、且需要研究的任务，参考图像是首选方式。文本研究用于描述事实；参考图像则能呈现视觉结构。只要可行，就同时使用两者。

需要研究的示例：

• 有名称的结构或地点，例如 贵州花江峡谷大桥，或任何真实的桥梁、地标、地形、天际线或建筑。
• 真实的产品、车辆、机器、UI、无 Logo 的产品轮廓、知名系列的游戏资产或时尚单品。
• 历史场景、文化服饰、制服、纹章、仪式用品、武器、建筑风格、生物、地图、技术图表或科学主题。
• 当前或近期发生变化的主题。
• 需要参考资料才能避免生成泛泛内容的小众视觉风格或与特定艺术家相近的风格。

研究工作流：

• 当结构、功能、历史、地理或当前状态很重要时，搜索网络以查找事实信息。
• 使用图片搜索或提供的图像，了解形状、地形、材料、比例、颜色和周边环境等视觉细节。
• 对于有名称的结构、真实地点、真实产品、真实车辆、历史或文化视觉主题、技术图表和小众风格，在生成前主动收集至少一张有用的参考图像。
• 尽可能选择多张互补的参考图：一张展示主体结构，一张展示周边环境，一张展示所需的相机角度或构图。
• 在调用脚本前，将参考图像下载到本地工作路径，然后通过 --image 和 --image-role 传入。
• 如果参考图像质量不高但仍有用，请谨慎标注其用途，例如 rough terrain reference only。
• 仅提取提示词所需的细节；保持提示词简洁。
• 在提示词中加入事实约束，例如桥梁类型、桥面／桥塔／缆索布局、峡谷地形、河流位置、视角和周边地貌。
• 只要使用了网络研究，就在最终回复中注明来源。

参考图像工作流：

• 对视觉保真度有要求时，优先使用用户提供的参考图像，而不是依赖记忆。
• 对每个 --image，都传入匹配的 --image-role，例如 edit target、style reference、composition reference、product reference 或 terrain reference。
• 不要将每张图像都视为编辑目标；应判断它仅供参考，还是应该保留并修改。
• 对于合成，应明确说明每个输入分别提供什么内容，以及光照、透视、比例和阴影应如何匹配。
• 对于仅参考图像的生成任务，应提示模型根据参考资料创作新图像，而不是精确复制某一张源照片。
• 如果图像模型／提供商拒绝参考图像编辑请求，应明确说明错误，然后判断对于此任务而言仅使用文本生成是否可以接受。不要悄悄改用其他方式。

提示词结构

在适用时使用这个精简格式：

Use case: <photorealistic-natural|product-mockup|ui-mockup|infographic-diagram|logo-brand|illustration-story|stylized-concept|historical-scene|text-localization|identity-preserve|precise-object-edit|lighting-weather|background-extraction|style-transfer|compositing|sketch-to-render>
Asset type: <where the image will be used>
Primary request: <user request>
Research facts / visual references: <only the relevant observed details>
Input images: <Image 1: role; Image 2: role>
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <viewpoint, lens/framing, placement>
Lighting/mood: <lighting and mood>
Materials/textures: <surface details>
Text (verbatim): "<exact text if needed>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

等待行为

• 此脚本采用同步方式运行。在图像任务完成或发生明确错误之前，脚本不会返回。
• 默认超时时间为 1800 秒，避免长时间运行的任务过早中断。
• 使用 --timeout 0 可禁用客户端超时，并无限期等待服务提供商响应。
• 从 Codex 调用此脚本时，为 shell 命令设置的超时时间应长于图像任务的预期时长。长时间生成任务不要使用较短的 shell 超时时间。

尺寸与质量

遵循当前官方 gpt-image-2 规则：

• size 可以是 auto，也可以是满足以下所有条件的 <width>x<height> 字符串：
• 宽度和高度都是 16 的倍数
• 最长边不超过 3840
• 长边与短边的比例不超过 3:1
• 总像素数介于 655,360 和 8,294,400 之间
• 此脚本默认使用 2048x1152；官方 API 的默认尺寸行为是 auto
• 常见示例：1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840
• quality 可以是 low、medium、high 或 auto；此脚本默认使用 high，也可通过 auto 使用官方 API 的自动质量设置
• 满足这些约束时，2K 和 4K 请求均有效
• 不要静默转换不受支持的尺寸。应抛出清晰的错误。

提示词

• 优先使用包含主体、风格、光线和构图等具体内容的提示词。
• 默认使用用户的语言。此工作流支持中文提示词。
• 迭代时一次只更改一个方面。

输出规则

• 用户需要可用的素材时，将项目素材保存在项目工作区内。
• 将预览图像保存到明确的临时路径或用户指定的路径。
• 如果 n > 1，通过追加 -1、-2 等后缀，确保文件名具有确定性。

失败规则

• 如果找不到 OPENAI_API_KEY、model_provider 或 base_url，应抛出明确的错误。
• 允许通过 --base-url、--api-key-env 或 --api-key 临时覆盖 Provider；除非用户明确要求，否则不要持久保存这些设置。
• 如果同时提供 --api-key 和 --api-key-env、指定的环境变量为空，或 --base-url 不是 HTTP(S) URL，应抛出明确的错误。
• 如果 size 违反官方 GPT Image 约束，或 quality 不受支持，应抛出明确的错误。
• 如果未提供输入图像却请求编辑/参考模式，应抛出明确的错误。
• 如果将 gpt-image-2 与 --background transparent 或 --input-fidelity 搭配使用，应抛出明确的错误。
• 如果遮罩与第一个 --image 编辑目标不兼容、尺寸不同、缺少 alpha 通道，或超过图像 API 的文件大小限制，应抛出明确的错误。
• 直接显示 Provider 错误。不要伪造成功结果。
• 如果此机器上的 Provider 使用了不同的图像模型名称，请覆盖 --model。

资源

• scripts/generate_image.py：读取当前用户的 Codex 根目录文件，调用已配置 Provider 的图像端点，并保存返回的图像数据。