imgen 是一个命令行图片工具，用 AI 模型生成或编辑图片并写入文件，同时提供本地抠除纯色背景和缩小 PNG 的能力。
一、用途 主要用于生成位图素材，包括照片、插画、海报、产品图、UI mockup、logo、icon、sprite、贴纸、纹理和透明背景素材；也用于在已有图片基础上改图，以及本地去绿幕、去纯色背景和缩小图片。
二、环境准备 命令不存在或 imgen version 低于 metadata.requires 要求的版本时，安装后重试一次：
curl -fsSL https://raw.githubusercontent.com/what1f/ls-skills/main/install.sh | sh -s -- imgen
Windows PowerShell：
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/what1f/ls-skills/main/install.ps1))) imgen
首次使用运行 imgen providers --format json，查看哪些 provider 已配置凭证（configured）、默认使用哪个（selected）、各模型支持哪些能力（改图、mask、原生透明、尺寸方式、最多输入几张图）。用户未指定时使用默认 provider，不要自行更换。
三、主要命令 用 imgen <command> --help 查看完整参数。
生成一张
imgen generate --prompt "..." --out assets/hero.png --format json
同一素材出多个候选：每个 variant 一张，并行请求
imgen generate --prompt "..." --variant "flat vector" --variant "3D clay" --out-dir out --format json
改图：输入图按顺序在 prompt 里叫 Image 1、Image 2…
imgen generate --prompt "Image 1: product photo. Replace only the background with pure white." --image in.jpg --out out/white.png --format json
透明背景
imgen generate --prompt "..." --background transparent --out icon.png --format json
画幅
imgen generate --prompt "..." --aspect 16:9 --out banner.png --format json
先看会发出什么请求，不花钱
imgen generate ... --dry-run --format json
多个不同素材
imgen batch --input jobs.jsonl --out-dir out --format json
本地抠掉纯色背景
imgen cutout --image green.png --out cut.png --format json
本地缩小
imgen resize --image big.png --out small.png --max-dim 512 --format json
核心参数： --model [provider/]name 选模型，如 gemini/gemini-3-pro-image、openai/gpt-image-2； --quality low|medium|high|auto：草稿用 low，定稿和带小字的图用 medium 或 high； --aspect W:H 与 --size WxH 二选一，模型不支持精确尺寸时会就近取并在 warnings 中说明； --n N 对同一 prompt 采样多次，variant 数 × n 不超过 10。
四、使用流程
- 判断意图：新生成还是修改现有图片。用户未明确要改时按新生成处理；仅把图片当风格或构图参考也算新生成，图通过 --image 传入。
- 标明每张输入图角色：在 prompt 中写 Image 1: edit target、Image 2: style reference，顺序与 --image 一致。
- 写 prompt：用户写得具体时只整理结构；写得笼统时才补充构图、用途等细节，不添加用户未暗示的人物、物件和文案。结构与素材要点见 references/prompting.md，现成模板见 references/sample-prompts.md。
- 选输出位置：项目素材直接写入项目目标路径；仅预览时放临时目录。已有文件不要覆盖，除非用户要求，此时加 --force。
- 生成后查看图片，检查主体、风格、构图、文字准确性和约束满足情况；不满意时一次只改一处 prompt 再生成，改图时每轮重复“保持不变”的约束。
- 汇报最终文件路径、使用的 prompt、provider 和模型，以及 warnings 中值得注意的内容。
variant 与 batch 的区别：同一素材要多个候选用 --variant 或 --n；一组不同素材（如一套图标、多张配图）用 batch。
五、batch 批量任务 jobs.jsonl 每行一个任务，只有 prompt 必填，例如： {"prompt":"App icon: a paper plane, flat vector","out":"icon-send.png"} {"prompt":"App icon: a magnifying glass, flat vector","out":"icon-search.png"} {"prompt":"Hero illustration of a city at dawn","aspect":"16:9","quality":"high"}
可用字段：prompt、variants、n、images、mask、provider、model、aspect、size、quality、background、chroma_key、output_format、compression、out。out 是 --out-dir 下的文件名，命令行 generate 参数作为每行默认值。任何一行有问题，整个 batch 在发请求前报错，message 以 line N: 开头。可重试错误（限流、超时、5xx）默认最多试 3 次（--max-attempts）；加 --fail-fast 后，出现第一个失败时不再启动新任务。
六、透明背景处理 --background transparent 时，data.transparent 说明使用哪种方式：native 表示模型原生输出透明 PNG；chroma-key 表示模型不支持透明时，imgen 让其画在纯色背景上再在本地抠除，此时 prompt 只描述主体，不要自己写背景要求；主体为绿色时加 --chroma-key '#ff00ff'。结果中每张图的 transparent_ratio 是透明像素占比。接近 0 或看图发现边缘色边、背景残留时，可换 --chroma-key 颜色或调整 prompt 让主体轮廓更干净后重新生成；也可改用 --background opaque，在 prompt 中写“perfectly flat solid #00FF00 background”，再用 imgen cutout 调参数：--key '#RRGGBB' 指定背景色，--contract 1 收掉色边，--feather 1 让边缘柔和，--hard --tolerance N 处理边缘锐利的像素画。cutout 和 resize 只接受 PNG；输入是 JPEG 时先转换，macOS 上可用 sips -s format png in.jpg --out in.png。
七、规则与限制 一律加 --format json，从 data.images[].path 读最终路径；返回格式与扩展名不符时 imgen 会改扩展名。顶层 ok 为 false 但有 data 时为部分失败，成功的图已写好，只需重新生成失败的那几张。content_policy 时不要原样重试，告知用户被拒，可在不改变意图前提下调整措辞后再试。exists 时换路径，或确认用户同意覆盖后加 --force。退出码 2 是参数错误或模型不支持某项能力，按 message 修正后重试；退出码 3 是缺凭证或凭证无效，停止重试并把 error.message 转告用户，由用户设置 API key 或运行 codex login。不要读取、打印或在命令行参数中传递 API key，凭证只通过环境变量、配置文件里的 api_key_command 或 Codex 登录提供。每次请求都会花钱和时间（单张常见 10–60 秒），不确定参数是否生效时先用 --dry-run，不要为多给选择擅自加大 --n。
八、适用场景 适合为项目批量生成或修改图片素材、制作图标与插画、处理透明背景素材以及本地抠图缩图；要求命令行环境，且调用 AI 模型需事先配置对应 provider 凭证。