generate-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Image Skill

中文说明

功能概述

generate-image

用于通过兼容 OpenAI Images API 的接口生成图片。用户主要使用

/gi-setup

初始化配置，使用

/gi

输入 prompt 和参数生成图片。

默认行为：

默认模型：
```
gpt-image-2
```
（兼容旧配置里的
```
gpt-image2
```
/
```
auto
```
，helper 会映射为
```
gpt-image-2
```
）
默认出图比例：
```
custom
```
（从提示词获取；未获取到则使用 API
```
auto
```
）
默认清晰度：
```
1k
```
（指定明确比例时会换算为实际 API
```
size
```
）
默认输出目录：项目目录下
```
.claybe/.generate-image/
```
默认配置文件：
```
~/.claude/generate-image/config.json
```

generate-image

用于通过兼容 OpenAI Images API 的接口生成图片。用户主要使用

/gi-setup

初始化配置，使用

/gi

输入 prompt 和参数生成图片。

默认行为：

默认模型：
```
gpt-image-2
```
（兼容旧配置里的
```
gpt-image2
```
/
```
auto
```
，helper 会映射为
```
gpt-image-2
```
）
默认出图比例：
```
custom
```
（从提示词获取；未获取到则使用 API
```
auto
```
）
默认清晰度：
```
1k
```
（指定明确比例时会换算为实际 API
```
size
```
）
默认输出目录：项目目录下
```
.claybe/.generate-image/
```
默认配置文件：
```
~/.claude/generate-image/config.json
```

Slash 命令

斜杠命令

/gi-setup

/gi-setup

用于保存 API 配置。按步骤引导用户提供：

URL（API Base URL）
API Key
是否使用默认模型
```
gpt-image-2
```

如果用户已提供部分参数，只追问缺失项。也支持直接读取项目

setting.json

：

text

/gi-setup --use-settings

对应 helper：

bash

node skill/generate-image/scripts/generate-image.mjs setup --use-settings

或：

bash

node skill/generate-image/scripts/generate-image.mjs setup --url <url> --apikey <apikey> --model gpt-image-2

setting.json

可使用顶层字段

apiBaseUrl

apiKey

model

，也支持

url

apikey

，以及嵌套在

generateImage

或

generate-image

下。

用于保存 API 配置。按步骤引导用户提供：

URL（API Base URL）
API Key
是否使用默认模型
```
gpt-image-2
```

如果用户已提供部分参数，只追问缺失项。也支持直接读取项目

setting.json

：

text

/gi-setup --use-settings

对应 helper：

bash

node skill/generate-image/scripts/generate-image.mjs setup --use-settings

或：

bash

node skill/generate-image/scripts/generate-image.mjs setup --url <url> --apikey <apikey> --model gpt-image-2

setting.json

可使用顶层字段

apiBaseUrl

apiKey

model

，也支持

url

apikey

，以及嵌套在

generateImage

或

generate-image

下。

/gi

/gi

用于生成图片。支持 CLI 风格参数，也支持从自然语言中提取参数：

text

/gi 一张赛博朋克风格的上海夜景，出图比例 3:2，清晰度 1k，quality=high output-file=./.claybe/.generate-image/shanghai.png

当配置缺失时，不要只报错；进入

/gi-setup

引导用户配置 URL/API Key，或询问是否使用项目

setting.json

。

用于生成图片。支持 CLI 风格参数，也支持从自然语言中提取参数：

text

/gi 一张赛博朋克风格的上海夜景，出图比例 3:2，清晰度 1k，quality=high output-file=./.claybe/.generate-image/shanghai.png

当配置缺失时，不要只报错；进入

/gi-setup

引导用户配置 URL/API Key，或询问是否使用项目

setting.json

。

Agent 执行规则

从

/gi

输入中提取：

```
prompt
```
```
aspect-ratio
```
/
```
ratio
```
/
```
比例
```
```
resolution
```
/
```
清晰度
```
/
```
档位
```
```
model
```
```
output
```
```
output-file
```
```
index
```
```
url
```
/
```
apikey
```
其他
```
key=value
```
参数，作为
```
--param key=value
```
透传

如果未指定出图比例，使用
```
custom
```
：优先从提示词提取
```
16:9
```
、
```
9:16
```
、
```
3:2
```
、
```
4:3
```
、
```
1:1
```
；如果提示词没有比例，则使用 API
```
auto
```
。如果未指定清晰度，使用
```
1k
```
。
如果未指定
```
model
```
，使用
```
gpt-image-2
```
。

组织 prompt 时保留用户意图，并补齐资产描述结构：

[资产名称/用途] + [资产类型] + [具体主体] + [艺术风格] + [视角] + [光影细节] + [背景要求]

每张图只生成一个主体。不要把多个资产、多个变体或多个主体放在同一张图里；多个资产应分别调用
```
/gi
```
，生成独立贴图。
生成时启动名为
```
painter
```
的后台 subagent，让它运行 helper 的
```
generate
```
命令。helper 会创建占位图、调用 API、保存最终图并更新索引。
```
gpt-image*
```
模型默认先尝试流式生成：如果流式响应没有最终完成图但包含草稿/中间图，会使用最后一张可用图片；如果流式响应完全没有图片或接口拒绝 stream，会自动回退一次普通非流式生成。
```
painter
```
完成后，报告生成图路径、占位图路径和索引路径。
如果失败，报告明确错误，并说明占位图已保留。响应中没有图片数据通常表示接口/代理返回空
```
data
```
、流式事件缺少可用图片，或连接在最终图片事件前中断；生成请求本身不能续传，只能重新发起。

helper 调用格式：

bash

node skill/generate-image/scripts/generate-image.mjs generate --prompt "<prompt>" --aspect-ratio <custom|16:9|9:16|3:2|4:3|1:1> --resolution <1k|2k|4k> [other args]

从

/gi

输入中提取：

```
prompt
```
```
aspect-ratio
```
/
```
ratio
```
/
```
比例
```
```
resolution
```
/
```
清晰度
```
/
```
档位
```
```
model
```
```
output
```
```
output-file
```
```
index
```
```
url
```
/
```
apikey
```
其他
```
key=value
```
参数，作为
```
--param key=value
```
透传

如果未指定出图比例，使用
```
custom
```
：优先从提示词提取
```
16:9
```
、
```
9:16
```
、
```
3:2
```
、
```
4:3
```
、
```
1:1
```
；如果提示词没有比例，则使用 API
```
auto
```
。如果未指定清晰度，使用
```
1k
```
。
如果未指定
```
model
```
，使用
```
gpt-image-2
```
。

组织 prompt 时保留用户意图，并补齐资产描述结构：

[资产名称/用途] + [资产类型] + [具体主体] + [艺术风格] + [视角] + [光影细节] + [背景要求]

每张图只生成一个主体。不要把多个资产、多个变体或多个主体放在同一张图里；多个资产应分别调用
```
/gi
```
，生成独立贴图。
生成时启动名为
```
painter
```
的后台 subagent，让它运行 helper 的
```
generate
```
命令。helper 会创建占位图、调用 API、保存最终图并更新索引。
```
gpt-image*
```
模型默认先尝试流式生成：如果流式响应没有最终完成图但包含草稿/中间图，会使用最后一张可用图片；如果流式响应完全没有图片或接口拒绝 stream，会自动回退一次普通非流式生成。
```
painter
```
完成后，报告生成图路径、占位图路径和索引路径。
如果失败，报告明确错误，并说明占位图已保留。响应中没有图片数据通常表示接口/代理返回空
```
data
```
、流式事件缺少可用图片，或连接在最终图片事件前中断；生成请求本身不能续传，只能重新发起。

helper 调用格式：

bash

node skill/generate-image/scripts/generate-image.mjs generate --prompt "<prompt>" --aspect-ratio <custom|16:9|9:16|3:2|4:3|1:1> --resolution <1k|2k|4k> [other args]

参数表

参数	说明	默认值
`--prompt`	图片提示词，也可作为位置参数传入	必填
`--aspect-ratio`	出图比例： `custom` 、 `16:9` 、 `9:16` 、 `3:2` 、 `4:3` 、 `1:1` 。 `custom` 会从提示词获取，未获取到则使用 API `auto`	`custom`
`--resolution`	清晰度档位： `1k` 、 `2k` 、 `4k`	`1k`
`--model`	图片模型名称	`gpt-image-2`
`--url`	API base URL 覆盖值	初始化配置中的值
`--apikey` / `--api-key`	API Key 覆盖值	初始化配置中的值
`--output`	输出目录；如果以 `.png` 、 `.jpg` 、 `.jpeg` 、 `.webp` 结尾，则视为最终文件路径	`./.claybe/.generate-image`
`--output-file`	最终图片文件路径	无
`--index`	图片索引字典文件路径	`<输出目录>/image-index.json`
`--param key=value`	透传给生成接口的额外参数，可重复	无
`--config`	自定义配置文件路径	`~/.claude/generate-image/config.json`

参数	说明	默认值
`--prompt`	图片提示词，也可作为位置参数传入	必填
`--aspect-ratio`	出图比例： `custom` 、 `16:9` 、 `9:16` 、 `3:2` 、 `4:3` 、 `1:1` 。 `custom` 会从提示词获取，未获取到则使用 API `auto`	`custom`
`--resolution`	清晰度档位： `1k` 、 `2k` 、 `4k`	`1k`
`--model`	图片模型名称	`gpt-image-2`
`--url`	API base URL 覆盖值	初始化配置中的值
`--apikey` / `--api-key`	API Key 覆盖值	初始化配置中的值
`--output`	输出目录；如果以 `.png` 、 `.jpg` 、 `.jpeg` 、 `.webp` 结尾，则视为最终文件路径	`./.claybe/.generate-image`
`--output-file`	最终图片文件路径	无
`--index`	图片索引字典文件路径	`<输出目录>/image-index.json`
`--param key=value`	透传给生成接口的额外参数，可重复	无
`--config`	自定义配置文件路径	`~/.claude/generate-image/config.json`

输出行为

PNG 占位图：先写入最终图片路径
生成图：生成成功后用真实图片覆盖同一路径，路径默认会从资产名称/用途或具体主体生成，例如
```
小飞机-<timestamp>.png
```
或
```
--output-file
```
/ 文件型
```
--output
```
指定路径
索引字典：默认
```
<输出目录>/image-index.json
```

索引键为图片路径；成功时

placeholderPath

与

generatedPath

相同，值包含

prompt

、

placeholderPath

、

generatedPath

、

result

、

model

、

size

、

params

和时间戳。失败时会记录错误，并在同一路径保留占位图。

PNG 占位图：先写入最终图片路径
生成图：生成成功后用真实图片覆盖同一路径，路径默认会从资产名称/用途或具体主体生成，例如
```
小飞机-<timestamp>.png
```
或
```
--output-file
```
/ 文件型
```
--output
```
指定路径
索引字典：默认
```
<输出目录>/image-index.json
```

索引键为图片路径；成功时

placeholderPath

与

generatedPath

相同，值包含

prompt

、

placeholderPath

、

generatedPath

、

result

、

model

、

size

、

params

和时间戳。失败时会记录错误，并在同一路径保留占位图。

安全注意事项

不要把 API Key 写进项目代码、README、issue、PR 或聊天摘要。
临时覆盖 API Key 时优先使用命令参数。
helper 只把 API Key 写入用户目录
```
~/.claude/generate-image/config.json
```
。

不要把 API Key 写进项目代码、README、issue、PR 或聊天摘要。
临时覆盖 API Key 时优先使用命令参数。
helper 只把 API Key 写入用户目录
```
~/.claude/generate-image/config.json
```
。

English Guide

英文指南（翻译后）

Overview

概述

generate-image

generates images through an OpenAI Images API-compatible endpoint. Users configure the endpoint with

/gi-setup

and generate images with

/gi

Defaults:

Model:
```
gpt-image-2
```
(legacy
```
gpt-image2
```
/
```
auto
```
config values are mapped to
```
gpt-image-2
```
by the helper)
Aspect ratio:
```
custom
```
(extract from the prompt; if none is found, API
```
auto
```
is used)
Resolution tier:
```
1k
```
(converted to the actual API
```
size
```
when a concrete ratio is available)
Output directory:
```
.claybe/.generate-image/
```
under the project directory
Config file:
```
~/.claude/generate-image/config.json
```

generate-image

通过兼容 OpenAI Images API 的端点生成图片。用户使用

/gi-setup

配置端点，使用

/gi

生成图片。

默认设置：

模型：
```
gpt-image-2
```
（旧配置中的
```
gpt-image2
```
/
```
auto
```
会被 helper 映射为
```
gpt-image-2
```
）
出图比例：
```
custom
```
（从提示词提取；未提取到则使用 API
```
auto
```
）
清晰度档位：
```
1k
```
（指定明确比例时会换算为实际 API
```
size
```
）
输出目录：项目目录下的
```
.claybe/.generate-image/
```
配置文件：
```
~/.claude/generate-image/config.json
```

Slash commands

斜杠命令

/gi-setup

/gi-setup

Saves API settings. Guide the user step by step for:

URL (API Base URL)
API Key
Whether to keep the default model
```
gpt-image-2
```

If the user already provided some values, only ask for the missing ones. The project

setting.json

can also be used:

text

/gi-setup --use-settings

Helper command:

bash

node skill/generate-image/scripts/generate-image.mjs setup --use-settings

or:

bash

node skill/generate-image/scripts/generate-image.mjs setup --url <url> --apikey <apikey> --model gpt-image-2

setting.json

may contain top-level

apiBaseUrl

apiKey

model

, aliases

url

apikey

, or the same fields under

generateImage

generate-image

用于保存 API 设置。按步骤引导用户提供：

URL（API Base URL）
API Key
是否保留默认模型
```
gpt-image-2
```

如果用户已提供部分参数，仅询问缺失项。也可使用项目的

setting.json

：

text

/gi-setup --use-settings

对应 helper 命令：

bash

node skill/generate-image/scripts/generate-image.mjs setup --use-settings

或：

bash

node skill/generate-image/scripts/generate-image.mjs setup --url <url> --apikey <apikey> --model gpt-image-2

setting.json

可包含顶层字段

apiBaseUrl

apiKey

model

、别名

url

apikey

，或嵌套在

generateImage

或

generate-image

下的相同字段。

/gi

/gi

Generates an image. It accepts CLI-style parameters and can also extract parameters from natural language:

text

/gi a cyberpunk night view of Shanghai, aspect-ratio 3:2, resolution 1k, quality=high output-file=./.claybe/.generate-image/shanghai.png

If configuration is missing, do not only fail. Enter the

/gi-setup

flow and ask for URL/API Key, or ask whether to use the project

setting.json

用于生成图片。支持 CLI 风格参数，也可从自然语言中提取参数：

text

/gi a cyberpunk night view of Shanghai, aspect-ratio 3:2, resolution 1k, quality=high output-file=./.claybe/.generate-image/shanghai.png

如果配置缺失，不要直接报错。进入

/gi-setup

流程，请求用户提供 URL/API Key，或询问是否使用项目的

setting.json

。

Agent rules

Agent 执行规则

Extract from

/gi

input:

```
prompt
```
```
aspect-ratio
```
/
```
ratio
```
/
```
比例
```
```
resolution
```
/
```
清晰度
```
/
```
档位
```
```
model
```
```
output
```
```
output-file
```
```
index
```
```
url
```
/
```
apikey
```
other
```
key=value
```
pairs as passthrough
```
--param key=value
```

Use
```
custom
```
when aspect ratio is not specified: extract
```
16:9
```
,
```
9:16
```
,
```
3:2
```
,
```
4:3
```
, or
```
1:1
```
from the prompt first; if no ratio is found, use API
```
auto
```
. Use
```
1k
```
when resolution tier is not specified.
Use
```
gpt-image-2
```
when
```
model
```
is not specified.

Preserve the user's intent while completing this asset prompt structure:

[asset name/purpose] + [asset type] + [specific subject] + [art style] + [view angle] + [lighting details] + [background requirements]

Generate one subject per image. Do not put multiple assets, variants, or subjects into one image; call
```
/gi
```
separately for independent textures.
Start a background subagent named
```
painter
```
and have it run the helper
```
generate
```
command. The helper creates the placeholder, calls the API, saves the final image, and updates the index.
```
gpt-image*
```
models try streaming first by default: if the stream has no final completed image but includes draft/intermediate image data, the helper uses the latest available image; if the stream contains no image at all or the endpoint rejects streaming, it automatically retries once without streaming.
When
```
painter
```
finishes, report the generated image path, placeholder path, and index path.
On failure, report the clear error and mention that the placeholder remains available. No image data in the response usually means the endpoint/proxy returned empty
```
data
```
, stream events had no usable image, or the connection ended before the final image event; the generation request itself cannot be resumed and must be started again.

Helper command format:

bash

node skill/generate-image/scripts/generate-image.mjs generate --prompt "<prompt>" --aspect-ratio <custom|16:9|9:16|3:2|4:3|1:1> --resolution <1k|2k|4k> [other args]

从

/gi

输入中提取：

```
prompt
```
```
aspect-ratio
```
/
```
ratio
```
/
```
比例
```
```
resolution
```
/
```
清晰度
```
/
```
档位
```
```
model
```
```
output
```
```
output-file
```
```
index
```
```
url
```
/
```
apikey
```
其他
```
key=value
```
键值对，作为
```
--param key=value
```
透传

未指定出图比例时使用
```
custom
```
：优先从提示词提取
```
16:9
```
、
```
9:16
```
、
```
3:2
```
、
```
4:3
```
或
```
1:1
```
；未提取到则使用 API
```
auto
```
。未指定清晰度档位时使用
```
1k
```
。
未指定
```
model
```
时使用
```
gpt-image-2
```
。

保留用户意图的同时，补全资产提示词结构：

[资产名称/用途] + [资产类型] + [具体主体] + [艺术风格] + [视角] + [光影细节] + [背景要求]

每张图仅生成一个主体。不要将多个资产、变体或主体放入同一张图；多个资产需分别调用
```
/gi
```
，生成独立贴图。
启动名为
```
painter
```
的后台 subagent，让其运行 helper 的
```
generate
```
命令。helper 会创建占位图、调用 API、保存最终图片并更新索引。
```
gpt-image*
```
模型默认优先尝试流式生成：如果流式响应无最终完成图但包含草稿/中间图数据，helper 会使用最新可用图片；如果流式响应完全无图片或端点拒绝流式请求，会自动重试一次非流式生成。
```
painter
```
完成后，报告生成图片路径、占位图路径和索引路径。
生成失败时，报告明确错误并说明占位图已保留。响应中无图片数据通常表示端点/代理返回空
```
data
```
、流式事件无可用图片，或连接在最终图片事件前中断；生成请求无法续传，只能重新发起。

helper 调用格式：

bash

node skill/generate-image/scripts/generate-image.mjs generate --prompt "<prompt>" --aspect-ratio <custom|16:9|9:16|3:2|4:3|1:1> --resolution <1k|2k|4k> [other args]

Parameters

参数表

Parameter	Meaning	Default
`--prompt`	Image prompt; can also be positional text	Required
`--aspect-ratio`	Aspect ratio: `custom` , `16:9` , `9:16` , `3:2` , `4:3` , or `1:1` . `custom` extracts the ratio from the prompt; if none is found, API `auto` is used	`custom`
`--resolution`	Resolution tier: `1k` , `2k` , or `4k`	`1k`
`--model`	Image model name	`gpt-image-2`
`--url`	API base URL override	Config value
`--apikey` / `--api-key`	API key override	Config value
`--output`	Output directory; image-extension paths are treated as final file paths	`./.claybe/.generate-image`
`--output-file`	Final image file path	None
`--index`	Image index dictionary path	`<output directory>/image-index.json`
`--param key=value`	Extra API parameter; repeatable	None
`--config`	Custom config file path	`~/.claude/generate-image/config.json`

参数	说明	默认值
`--prompt`	图片提示词；也可作为位置文本传入	必填
`--aspect-ratio`	出图比例： `custom` 、 `16:9` 、 `9:16` 、 `3:2` 、 `4:3` 或 `1:1` 。 `custom` 从提示词提取比例；未提取到则使用 API `auto`	`custom`
`--resolution`	清晰度档位： `1k` 、 `2k` 或 `4k`	`1k`
`--model`	图片模型名称	`gpt-image-2`
`--url`	API base URL 覆盖值	配置值
`--apikey` / `--api-key`	API Key 覆盖值	配置值
`--output`	输出目录；带图片扩展名的路径会被视为最终文件路径	`./.claybe/.generate-image`
`--output-file`	最终图片文件路径	无
`--index`	图片索引字典路径	`<输出目录>/image-index.json`
`--param key=value`	额外 API 参数；可重复使用	无
`--config`	自定义配置文件路径	`~/.claude/generate-image/config.json`

Output behavior

输出行为

PNG placeholder: first written to the final image path
Generated image: on success, the real image overwrites the same path derived from the asset name/purpose or specific subject, for example
```
small-airplane-<timestamp>.png
```
or the path specified by
```
--output-file
```
/ file-style
```
--output
```
Index dictionary: defaults to
```
<output directory>/image-index.json
```

The index key is the image path. On success,

placeholderPath

and

generatedPath

are the same path. Values include

prompt

placeholderPath

generatedPath

result

model

size

params

, and timestamps. On failure, the error is recorded and the placeholder remains at that same path.

PNG 占位图：先写入最终图片路径
生成图片：成功生成后，真实图片会覆盖同一路径，该路径默认从资产名称/用途或具体主体生成，例如
```
small-airplane-<timestamp>.png
```
，或由
```
--output-file
```
/ 文件型
```
--output
```
指定路径
索引字典：默认路径为
```
<输出目录>/image-index.json
```

索引键为图片路径。生成成功时，

placeholderPath

与

generatedPath

为同一路径。值包含

prompt

、

placeholderPath

、

generatedPath

、

result

、

model

、

size

、

params

和时间戳。生成失败时，会记录错误并保留该路径下的占位图。

Security notes

安全注意事项

Do not commit API keys to source code, docs, issues, PRs, or summaries.
Prefer runtime overrides for temporary keys.
The helper only stores the API key in
```
~/.claude/generate-image/config.json
```
.

不要将 API Key 提交到源代码、文档、issue、PR 或摘要中。
临时使用其他 API Key 时，优先使用命令行参数覆盖。
helper 仅将 API Key 存储在
```
~/.claude/generate-image/config.json
```
中。