generating-images

生成图像（OpenAI gpt-image-2）

每当用户要求生成或编辑图像时，都使用此技能。它通过 Python 脚本调用 OpenAI 的 gpt-image-2 模型，支持纯文本提示词和一张或多张参考图像，并将生成的 PNG/JPEG/WebP 文件写入磁盘。

硬性规则（不得违反）

1. 始终使用 gpt-image-2。 不得退回使用 gpt-image-1、dall-e-3 或任何其他模型。脚本没有 --model 标志，正是出于这个原因。
2. 遇到任何错误都要立即停止。 不要重试、不要更换模型、不要试图绕过缺失的凭据，也不要悄悄降低质量。如果脚本以非零状态码退出，请原样向用户呈现错误并停止。
3. 除非用户明确要求，否则不要通过读取 .env 文件、1Password 等方式“修复”缺失的 OPENAI_API_KEY。 如果缺少此环境变量，请询问用户希望如何提供它（或让用户将其 export），然后停止。

使用场景

• 用户要求生成图像：图标、徽标、插图、模型图、OG 图、博客主视觉图、营销素材、概念艺术、图表风格图像等。
• 用户提供一张或多张图像，并要求编辑、改变风格、合并图像或将其用作参考。
• 用户要求移除或替换图像中的某个部分（使用 --mask）。

请勿将此技能用于：

• 图表／绘图／数据可视化（改用代码生成）。
• 寻找现有照片（如有可用的图库照片技能，请使用该技能）。
• 用户应用的屏幕截图（如有可用的截图技能，请使用该技能）。

前置条件

1. OpenAI API 密钥

需要在环境中 export 一个 OPENAI_API_KEY。请前往 platform.openai.com/api-keys 获取。

此技能附带一个 .env.example，与此 SKILL.md 位于同一目录。复制该文件并填写密钥：

cp .env.example .env
# then edit .env and put your real key in

然后在运行脚本前将其导出：

set -a && source .env && set +a

或者直接在 shell 中导出：

export OPENAI_API_KEY="sk-..."

如果未设置 OPENAI_API_KEY，脚本会立即以代码 2 退出。未经用户明确许可，不要尝试从其他任何位置读取该密钥。

2. 组织验证

你的 OpenAI 组织必须通过 gpt-image-2 的验证，验证页面为 platform.openai.com/settings/organization/general。 如果看到提及“organization must be verified”的 403 错误，请将错误呈现给用户并停止——不要切换模型。

3. Python 依赖项

pip install --upgrade openai

脚本位置

Python 脚本位于此 SKILL.md 同级目录下的 scripts/generate_image.py。当此技能安装在 ~/.cursor/skills/generating-images/ 时，脚本路径为 ~/.cursor/skills/generating-images/scripts/generate_image.py。

脚本会将已写入图像的绝对路径输出到 stdout。错误会输出到 stderr，并以非零状态码退出；脚本遇到第一个错误时会立即退出。

调用方式

始终通过 Shell 工具运行。请在用户当前工作区中选择合适的输出路径（例如，Web 项目使用 ./public/generated/<slug>.png，其他项目使用 ./<slug>.png）。

1. 文本生成图像

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Minimal flat-vector app icon for a note-taking app, indigo gradient, rounded square, soft shadow" \
  --size 1024x1024 \
  --quality high \
  --out ./icon.png

2. 图像生成图像（单张参考图）

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Restyle this photo as a watercolor painting with warm tones" \
  --image ./photo.jpg \
  --out ./photo-watercolor.png

3. 多张参考图像

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Photorealistic flat-lay product shot combining all of these items on a white background" \
  --image ./a.png --image ./b.png --image ./c.png \
  --out ./flatlay.png

4. 蒙版编辑（局部重绘）

蒙版必须与第一张输入图像的尺寸和格式相同，并通过 alpha 通道标记可编辑区域。

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --prompt "Replace the sky with a vivid sunset" \
  --image ./scene.png --mask ./sky-mask.png \
  --out ./scene-sunset.png

5. 批处理 / 并行模式（一次生成多张不同的图片）

当你需要一次生成多张不同的图片（例如一组博客主图、使用不同提示词的多个图标变体，或多个页面的 OG 图片）时，请使用 --batch，而不是运行脚本 N 次。它会在单个 Python 进程中并行运行所有任务——比串行调用快得多，也能避免重复的 SDK 启动开销。

编写一个描述所有任务的 JSON 文件，然后调用一次脚本：

cat > /tmp/img-jobs.json <<'EOF'
[
  {
    "prompt": "Minimal flat-vector app icon for a note-taking app, indigo gradient, rounded square",
    "out": "./public/icons/notes.png",
    "size": "1024x1024",
    "quality": "high"
  },
  {
    "prompt": "Photoreal blog hero: a cozy library with warm afternoon light, 5:3 ratio",
    "out": "./public/static/blog/library.png",
    "size": "1600x960",
    "quality": "medium"
  },
  {
    "prompt": "Restyle this product photo as a watercolor painting with warm tones",
    "image": ["./public/products/mug.jpg"],
    "out": "./public/products/mug-watercolor.png"
  }
]
EOF

python3 ~/.cursor/skills/generating-images/scripts/generate_image.py \
  --batch /tmp/img-jobs.json --concurrency 5

每个任务对象接受与 CLI 标志相同的字段：prompt（必填）、out、size、quality、format、n、image（字符串或字符串数组）、mask。默认值与单次调用的 CLI 相同。

行为：

• 所有任务会并发运行，最多同时运行 --concurrency 个（默认为 4）。合理范围为 3–8；OpenAI 会按组织进行速率限制，因此不要设置得太激进。
• 每张成功写入的图片完成任务后，都会立即将其绝对路径打印到 stdout，每行一个。
• 如果任何任务失败，其错误会打印到 stderr（ERROR: job <i> failed: ...），并且脚本会在其余任务完成后以代码 1 退出。其他任务不会被取消——保留部分输出没有问题，你可以只重试失败的任务。
• --batch 不能与 --prompt / --image / --mask 同时使用。

**何时优先使用 --batch，而不是并行 Shell 调用：**只要你在同一轮中要生成 ≥2 张不同的图片，就应使用 --batch。不要并行调用多个 Shell 来运行此脚本——改用一次批处理调用。

不要与 --n 混淆。--n 会在一次 API 调用中为同一个提示词生成多个变体（成本更低，但所有变体的创意相同）。--batch 会并行运行不同的提示词。两者可以组合使用：批处理中的一个任务可以设置 "n": 4，为该提示词生成 4 个变体。

标志参考

标志	默认值	说明
--prompt	必填*	除非使用 --batch，否则必填。即使是编辑图片，也必须包含。
--image	无	多次传入以指定多个参考图。会触发 images.edit。
--mask	无	可选的局部重绘蒙版（带 alpha 通道的 PNG）。
--out	./image.png	输出路径；当 --n > 1 时会添加索引后缀。
--size	auto	1024x1024、1536x1024、1024x1536、2048x2048、3840x2160 等。边长必须是 16 的倍数，最大为 3840px，宽高比 ≤ 3:1。
--quality	auto	low（快速草稿）、medium、high（最终素材）。
--format	png	png、jpeg、webp。
--n	1	在一次调用中生成同一个提示词的多个变体。
--batch	无	任务对象 JSON 数组的路径；并行运行这些任务。
--concurrency	4	--batch 模式下的最大并行工作线程数。

这里有意不提供 --model 标志。模型固定为 gpt-image-2。

尺寸指南

• 应用图标 / 方形缩略图 → 1024x1024
• 着陆页主图 / OG 图片 → 1536x1024
• 博客主图（5:3）→ 1600x960（两条边均为 16 的倍数，宽高比 = 5:3）
• 移动端 / 竖版插画 → 1024x1536
• 营销海报 / 4K 素材 → 3840x2160

质量指南

• 快速探索 / 草稿使用 low（成本最低、速度最快）。
• medium 是不错的默认选择。
• 仅对最终交付、可直接发布的素材使用 high——成本明显更高，耗时可能长达约 2 分钟。

如果用户只说“生成一张图片”，没有表明需要最终成品，则默认使用 --quality medium。

提示词编写技巧

为获得最佳效果，请在提示词中说明：

• 主体（图片中有什么）
• 风格（扁平矢量、水彩、照片级真实、等距、线描、3D 渲染……）
• 构图 / 摄像机视角（特写、俯视、广角镜头）
• 配色 / 氛围
• 背景（白色、渐变、场景——注意：gpt-image-2 不支持透明背景）
• 必须出现在图片中的任何文字，并用引号括起来（gpt-image-2 的文字渲染效果很好）

如果用户的提示词比较模糊，请根据合理的默认设定对其进行补充，而不是反问，除非请求确实存在歧义。

生成后

1. 将输出路径返回给用户。
2. 不要将图片嵌入 Markdown 中 — Cursor 会在生成的文件写入工作区后自动显示。
3. 如果结果用于网站／应用，且文件大小很重要，可以考虑使用优化工具（例如 pngquant、cwebp）进行处理。

生成前收集上下文

除非用户已明确说明具体需求（主题、风格、配色、尺寸、用途），否则先快速收集一下上下文。目标是让生成的图片看起来适合其使用场景，而不是像随意放进项目的素材。跳过这一步，是这项技能生成的结果不符合品牌风格的首要原因。

大致按以下顺序查看：

1. 目标位置的同类图片。 如果图片将放在 public/static/blog/、public/static/marketing/、assets/ 等目录中，使用 Read 工具打开该目录下的一两张现有图片。使图片与它们的以下特征相符：

   • 插画风格（3D 卡通、扁平矢量、照片级真实感、线稿、等距视角……）
   • 配色与光线
   • 主题惯例（例如“始终包含产品吉祥物”“始终使用隐喻，绝不使用真实截图”等）
   • 宽高比与分辨率

2. 展示图片的界面。 阅读相关文件：

   • 博客文章 → 阅读 MDX／Markdown（标题、标签、开篇段落、关键隐喻）。
   • 落地页版块 → 阅读组件、标题及周边文案。
   • README → 阅读 README 开头部分。
   • 组件 → 阅读组件，了解其代表的内容。

   根据实际内容提炼图片的含义，不要只看文件名。

3. 品牌／设计令牌。 如果项目有明确的配色方案、标志或吉祥物，生成图片时应与之呼应。可快速查看以下位置：

   • tailwind.config.* 中的品牌颜色
   • globals.css／主题文件中的 CSS 变量
   • public/ 中的标志／吉祥物素材
   • 现有的 OG 图片或营销素材

4. 宽高比／尺寸。 根据使用场景选择 --size：博客主视觉、OG 图片、方形头像、手机竖版图片等。尽量与现有素材保持一致。

然后编写提示词，将从内容中提炼的主题、从同类素材和品牌令牌中提取的风格与配色，以及与使用场景相符的构图融入其中。

如果用户确实给出了明确指示（风格、颜色、具体主题），请遵循指示并跳过上下文收集。如果用户只给出了部分指示，则收集其未明确说明部分的上下文。

不要针对可以从代码库中合理推断的信息向用户追问 — 先自行推断，只有在确实存在歧义时才询问（例如项目中已有两种同样合理的风格）。

放置并接入，而不只是丢个文件

当用户要求为特定位置（博客文章、落地页、OG 卡片、README、组件等）制作图片时，你要负责完成整个工作，而不只是生成 PNG。始终按以下顺序执行：

1. 为该位置选择正确的磁盘路径。查看现有文件并遵循已有做法。例如：

   • 博客主图 → 放在现有博客图片所在位置（例如： apps/<app>/public/static/blog/<slug>.png）。
   • 落地页素材 → 放在其他落地页素材所在位置（例如： apps/<app>/public/static/marketing/...）。
   • README / 文档图片 → 放在 docs/images/、assets/ 或文档旁边。
   • 组件专属素材 → 放在组件旁边，或其 public//assets/ 文件夹中。

   文件名使用文件的 slug、组件名称或章节名称。如果已有命名约定，不要另创一套。

2. 接入图片，确保它确实显示在用户指定的位置。这不是可选项。例如：

   • 博客文章 MDX → 更新 image:（或等效的）frontmatter 字段，使其指向新路径。替换任何占位 Unsplash / 素材图片 URL。
   • 落地页板块 → 在相关组件 / JSX 中导入或引用新素材。
   • OG 图片 → 更新 <meta property="og:image"> / 元数据配置。
   • README → 添加相应的 Markdown 图片标签。

3. 遵循现有约定，包括路径（相对路径、/static/... 或 @/assets/...）、文件格式（png/webp/jpg）以及包装组件（next/image、自定义 <Image> 等）。

4. 不要先询问。如果用户要求为已知位置制作图片，就自动完成放置和接入，并在最后告知他们所做的更改。只有在目标位置确实不明确时才询问。

错误——如实报告，不要隐瞒

如果发生以下任何情况，立即停止并向用户报告错误。不要重试，不要更换模型，也不要更改提示词。

• OPENAI_API_KEY is not set → 询问用户如何提供该密钥。
• openai package not installed → 告知用户运行 pip install --upgrade openai。
• 403 "organization must be verified" → 告知用户前往 platform.openai.com/settings/organization/general 完成验证。 不要切换模型。
• 400 尺寸错误 → 报告错误，让用户选择有效尺寸。
• 关于透明背景的 400 错误 → 报告错误；gpt-image-2 不支持透明背景。
• 任何其他 API 错误 → 原样报告并停止。