GPT Image CLI
使用 gpt-image CLI 生成用户请求的图像并返回其本地路径。需要 Node.js 22+。默认模型为 gpt-image-2.6-flare；质量默认为 API 的 auto。除非用户选择不同的设置，否则请保留这些默认值。
查找 CLI 和配置
在可用时使用已安装的 gpt-image 命令。否则，使用 npm 直接从公共仓库运行发布的 CLI：
npx --yes --package=github:zsio/openai-image-cli#v1.0.0 gpt-image --help
在后续示例中使用相同的前缀代替 gpt-image。当技能安装在未单独安装 CLI 的机器上时，此方法同样有效。它不需要代码检出或特定于机器的路径。
使用 gpt-image config show 检查配置。只需要 OPENAI_API_KEY；大小、模型、质量、格式和输出位置都有默认值。CLI 首先读取环境变量，然后读取位于 ${XDG_CONFIG_HOME:-$HOME/.config}/gpt-image/.env 的用户配置。gpt-image config path 打印解析后的路径。请尊重显式指定的 --config 或 GPT_IMAGE_CONFIG。
如果没有配置密钥，必要时运行 gpt-image config init，并告知用户在该本地文件中填写 OPENAI_API_KEY。将密钥保存在源码仓库和技能文件之外；不要要求用户将其粘贴到聊天中、打印出来或放在命令参数中。使用 config show 检查存在性，切勿通过显示配置文件来检查。不要仅仅为了检查配置而生成示例图像；使用 --dry-run 进行请求预览。
生成或编辑
对于新图像，将提示词作为单个参数传递。对于长提示或多行提示，编写一个 UTF-8 提示文件并使用 --prompt-file。
gpt-image generate "一只戴着红围巾的水彩小猫" --name kitten --json
gpt-image generate --prompt-file ./prompt.txt --out-dir ./assets --name cover --json
对于编辑或基于参考的生成，使用 edit 并重复 --image 以提供多个参考。输入顺序很重要：第一个图像是用于蒙版或标记层的主图像。
gpt-image edit "将背景改为雪山；保留人物的面部和衣物" \
--image ./portrait.png --name snowy-portrait --json
gpt-image edit "将两个产品放在一个白底产品照片中" \
--image ./product-a.png --image ./product-b.jpg --name product-pair --json
gpt-image edit "将透明蒙版区域替换为一个蓝色花瓶" \
--image ./room.png --mask ./mask.png --name blue-vase --json
使用 --background transparent --format png 进行透明抠图或贴纸。对于对现有透明资源的编辑，如果请求中要求保留透明度，则保留透明度。--mask 和 --markup 接受 PNG 文件且不能组合使用；它们的尺寸必须与第一个图像匹配。最多支持 16 个参考图像，包括本地 PNG/JPEG/WebP、图像 URL 和 OpenAI 文件 ID。
提示词应保留用户的主题、确切请求的文本、风格和约束。对于编辑，同时说明所需更改和需要保留的细节。不要静默更改请求的图像数量、模型或质量。每次 CLI 调用生成一张最终图像；重试已禁用，因此在决定是否值得发起另一个计费请求之前，请检查失败原因。
输出和有用选项
- 默认输出位于系统临时目录中一个唯一的
name-YYYYMMDD-HHmmss-SSS-suffix文件夹。使用--name提供有用的短文件名。 - 使用
--output FILE指定确切的文件路径，或使用--out-dir DIR --name NAME指定目标目录。这些选项不能组合使用。现有输出文件将被保留。 - 使用
--json读取image_path、metadata_path、prompt_path、request_id和 API 使用情况。进度信息输出到 stderr。返回实际保存的图像路径；在有用时使用可用的本地图像查看器预览图像。 --size WIDTHxHEIGHT、--quality auto|low|medium|high|xhigh|max、--background auto|opaque|transparent和--format png|jpeg|webp|gif|svg映射到 API 设置。模型/项目支持仍然适用。- 当用户选择用于详细视觉工作的分支时，使用
--model gpt-image-2.6-sunburst。对于没有模型偏好的普通请求，保留使用 Flare。 --stream --partial-images 1保存一个预览图加上最终图像。只有完成的图像才是最终结果。--params '{"complexity":"medium"}'或--params @params.json传递额外的 API 字段。n固定为 1。在使用不常见选项前，请阅读gpt-image --help。--timeout SECONDS覆盖整个请求。在超时/取消时，服务可能已经接受了该请求。不要自动重新提交。
CLI 和 API 详情：https://github.com/zsio/openai-image-cli