Back to Details

gpt-image

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

gpt-image

gpt-image

Agent runbook for GPT Image 2 generation/editing. Use the prompt library + packaged CLI. Do not reimplement image API code.
GPT Image 2生成/编辑的Agent运行手册。使用提示词库+打包好的CLI工具。请勿重新实现图像API代码。

Operating loop

操作流程

  1. Classify request: 
    generate
    , 
    edit
    , 
    inpaint
    , or 
    multi-reference
    ; identify asset type, exact text, aspect ratio, references, safety constraints, and budget/quality.
  2. Search references first: open 
    references/gallery.md
    ; load/search the closest 
    references/gallery-<category>.md
    file(s). Read actual 
    **Prompt**
    text before choosing a pattern.
  3. Refine with craft: load 
    references/craft.md
    for dense text, diagrams, UI, data visualization, multi-panel layouts, weak prompts, or no close gallery match.
  4. Confer when useful: before costly/ambiguous/high-polish calls, present 1–3 matched directions plus planned size/quality; ask at most one concise question. Skip long discussion for precise “generate now” requests.
  5. Preflight, no side effects: use existing CLI/skill if present. Check command availability (
    command -v gpt-image
    ), installed tool lists when the tool manager exists, or the runtime’s own skill registry when available. Do not assume a local home path in cloud/hosted runtimes.
  6. No blind setup: do not reinstall, overwrite skill folders, create/modify 
    .env
    , or write API keys unless the user explicitly requested setup. Global/shared installs are opt-in only.
  7. Execute via CLI only: call 
    gpt-image
    or 
    scripts/generate.py
    . Do not create a new 
    generate.py
    , SDK wrapper, or ad-hoc script for normal image requests.
  8. Report: output file path(s), key flags, and one concise refinement suggestion if useful.
Fast path: precise prompt + explicit “generate now” → quick reference/craft check, then CLI.
  1. 请求分类：判断请求类型为
    generate
    （生成）、
    edit
    （编辑）、
    inpaint
    （修复）或
    multi-reference
    （多参考）；确定资产类型、精确文本、宽高比、参考素材、安全约束以及预算/质量要求。
  2. 优先搜索参考素材：打开
    references/gallery.md
    ；加载并搜索最匹配的
    references/gallery-<category>.md
    文件。选择模式前请查看实际的
    **Prompt**
    文本内容。
  3. 结合技巧优化：若涉及密集文本、图表、UI、数据可视化、多面板布局、弱提示词或无匹配图库内容，加载
    references/craft.md
    文件。
  4. 必要时确认方向：在执行高成本/模糊/高精度生成请求前，提供1-3个匹配方向以及计划的尺寸/质量参数；最多提出一个简洁问题。对于明确要求“立即生成”的精准请求，跳过冗长讨论。
  5. 预检查，无副作用：优先使用现有CLI/技能。检查命令可用性（
    command -v gpt-image
    ），若存在工具管理器则查看已安装工具列表，或使用运行时自带的技能注册表。在云/托管运行时中请勿假设本地主目录路径。
  6. 禁止盲目配置：除非用户明确要求配置，否则请勿重新安装、覆盖技能文件夹、创建/修改
    .env
    文件或写入API密钥。全局/共享安装需用户主动选择。
  7. 仅通过CLI执行：调用
    gpt-image
    或
    scripts/generate.py
    。对于常规图像请求，请勿创建新的
    generate.py
    文件、SDK包装器或临时脚本。
  8. 结果报告：输出文件路径、关键参数，必要时提供一条简洁的优化建议。
快速路径：精准提示词+明确“立即生成”指令 → 快速检查参考素材/技巧文件，然后调用CLI。

CLI resolution

CLI调用优先级

Preferred call order:
bash
undefined
推荐调用顺序：
bash
undefined

Existing CLI on PATH

PATH中的现有CLI

gpt-image -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]
gpt-image -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

Installed skill folder; use runtime-provided skill path when available

已安装的技能文件夹；优先使用运行时提供的技能路径

uv run "$SKILL_DIR/scripts/generate.py" -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]
uv run "$SKILL_DIR/scripts/generate.py" -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

Direct transient CLI when the user requested setup/one-off CLI execution

用户要求配置/一次性CLI执行时，直接使用临时CLI

uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image -p "PROMPT" [options]

`scripts/generate.py` is a launcher: repo-local `src/gpt_image_cli` → installed `gpt-image` → PATH `gpt-image` → transient `uvx`/`uv` fallback.
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image -p "PROMPT" [options]

`scripts/generate.py`是启动器：优先使用仓库本地的`src/gpt_image_cli` → 已安装的`gpt-image` → PATH中的`gpt-image` → 临时`uvx`/`uv`作为备选。

Key and cost rules

密钥与成本规则

  • CLI reads 
    OPENAI_API_KEY
    from process env, then 
    .env
    , then 
    ~/.env
    without overriding existing env; successful API calls may bill the user’s OpenAI account.
  • If host/runtime has native platform-managed image generation and the user wants that path, use the host tool instead of this CLI.
  • If 
    OPENAI_API_KEY
    is unset, report missing key or use host-native generation when requested; do not write secrets.
  • If user wants to avoid local-key use, respect 
    unset OPENAI_API_KEY
    ; if a key exists in 
    .env
    /
    ~/.env
    , tell them to remove/rename it for the session rather than working around it.
  • Never print secret values.
  • CLI会从进程环境变量读取
    OPENAI_API_KEY
    ，其次是
    .env
    文件，最后是
    ~/.env
    文件，但不会覆盖现有环境变量；成功的API调用可能会从用户的OpenAI账户扣费。
  • 若宿主/运行时具备原生平台托管的图像生成功能且用户希望使用该方式，则优先使用宿主工具而非本CLI。
  • 若
    OPENAI_API_KEY
    未设置，报告密钥缺失，或在用户要求时使用宿主原生生成功能；请勿写入密钥信息。
  • 若用户希望避免使用本地密钥，需遵守
    unset OPENAI_API_KEY
    的要求；若
    .env
    /
    ~/.env
    中存在密钥，请告知用户在本次会话中移除/重命名该文件，而非绕过此限制。
  • 绝对禁止打印密钥等敏感信息。

Flags

参数选项

FlagValuesUse
-p, --prompt
stringRequired prompt/edit instruction
-f, --file
pathOutput path; auto-named if omitted
-i, --image
repeatable pathUse edits endpoint; supports multiple references
-m, --mask
PNG pathInpaint with alpha mask; requires 
-i
--model
default 
gpt-image-2
Image model
--size
1k
, 
2k
, 
4k
, 
portrait
, 
landscape
, 
square
, 
wide
, 
tall
, or literal		Canvas size
--quality
low
, 
medium
, 
high
, 
auto
Cost/quality dial
-n, --n
integerNumber of images
--background
auto
, 
opaque
Generation background
--moderation
auto
, 
low
Generation moderation setting
--format
png
, 
jpeg
, 
webp
Output encoding
--compression
0-100
JPEG/WebP compression
--user
stringOptional end-user identifier
Quality policy:
  • low
    : cheap drafts, broad exploration, many variants.
  • medium
    : normal exploration, style probing, balanced cost.
  • high
    : final assets, Chinese text, posters, diagrams, UI, paper figures, dense labels.
Size policy:
  • default/social square: 
    1k
    / 
    1024x1024
  • poster/mobile/beauty: 
    portrait
  • landscape/gameplay/photo: 
    landscape
  • print/paper figure: 
    2k
  • widescreen hero: 
    4k
  • vertical story/banner: 
    tall
参数取值用途
-p, --prompt
string必填的提示词/编辑指令
-f, --file
path输出路径；省略时自动命名
-i, --image
可重复传入路径使用编辑端点；支持多个参考图像
-m, --mask
PNG路径使用Alpha蒙版进行图像修复；需配合
-i
使用
--model
默认值
gpt-image-2
图像生成模型
--size
1k
, 
2k
, 
4k
, 
portrait
, 
landscape
, 
square
, 
wide
, 
tall
或自定义尺寸		画布尺寸
--quality
low
, 
medium
, 
high
, 
auto
成本/质量调节
-n, --n
integer生成图像数量
--background
auto
, 
opaque
生成背景设置
--moderation
auto
, 
low
生成内容审核设置
--format
png
, 
jpeg
, 
webp
输出编码格式
--compression
0-100
JPEG/WebP压缩率
--user
string可选的终端用户标识符
质量策略：
  • low
    ：低成本草稿、广泛探索、多版本变体。
  • medium
    ：常规探索、风格测试、成本与质量平衡。
  • high
    ：最终资产、中文文本、海报、图表、UI、论文插图、密集标签。
尺寸策略：
  • 默认/社交平台正方形：
    1k
    / 
    1024x1024
  • 海报/移动端/人像：
    portrait
    （竖版）
  • 风景/游戏画面/照片：
    landscape
    （横版）
  • 印刷/手办模型：
    2k
  • 宽屏横幅：
    4k
  • 竖版故事/广告条：
    tall
    （长竖版）

Endpoint routing

端点路由

ModeTriggerEndpoint
Text-to-imageno 
-i
/v1/images/generations
Reference editone or more 
-i
/v1/images/edits
Inpaint
-i
+ 
-m
/v1/images/edits
with mask
Surface API errors verbatim enough for debugging; exit codes: 
0
success, 
1
API/refusal, 
2
bad args/missing key.
模式触发条件端点
文本转图像未传入
-i
/v1/images/generations
参考图像编辑传入一个或多个
-i
/v1/images/edits
图像修复同时传入
-i
和
-m
带蒙版的
/v1/images/edits
需完整呈现API错误信息以便调试；退出码：
0
表示成功，
1
表示API拒绝，
2
表示参数错误/密钥缺失。

Reference loading

参考文件加载

  • references/gallery.md
    : routing index for the 162-prompt Reference Gallery Atlas. Load first.
  • references/gallery-*.md
    : concrete prompts, previews, paths, metadata, attribution. Load 1 category for normal requests; 2–3 for hybrids.
  • references/craft.md
    : prompt-craft checklist. Load for prompt repair, exact text, UI/data/diagram grammar, edit invariants, and multi-panel consistency.
  • references/openai-cookbook.md
    : official parameter/model semantics. Load for API behavior or model capability questions.
Reference loading policy: load the smallest useful slice; never load all category files by default.
  • references/gallery.md
    ：包含162个提示词的参考图库索引，优先加载。
  • references/gallery-*.md
    ：具体提示词、预览图、路径、元数据、来源信息。常规请求加载1个分类；混合场景加载2-3个分类。
  • references/craft.md
    ：提示词优化清单。用于提示词修复、精确文本、UI/数据/图表语法、编辑规则、多面板一致性调整。
  • references/openai-cookbook.md
    ：官方参数/模型语义说明。用于查询API行为或模型能力相关问题。
参考文件加载规则：加载最小必要的内容片段；默认情况下请勿加载所有分类文件。

Verification

验证步骤

  • Before API call: confirm endpoint mode, size, quality, output path, and required reference/mask files.
  • After CLI call: report path(s) printed by the CLI and surface stderr on failure.
  • For edits/inpaints: verify 
    -i
    paths exist; verify 
    -m
    exists when used.
Preserve 
Curated
vs 
Author + Source
metadata when adapting examples. Add new collected prompts to the Reference Gallery before README promotion.
  • API调用前：确认端点模式、尺寸、质量、输出路径以及所需的参考/蒙版文件是否存在。
  • CLI调用后：报告CLI输出的文件路径，若调用失败则显示stderr内容。
  • 编辑/修复场景：验证
    -i
    对应的路径是否存在；使用
    -m
    时需验证蒙版文件是否存在。
调整示例时请保留
Curated
（精选）与
Author + Source
（作者+来源）元数据。将新收集的提示词添加到参考图库后，再更新README文档。