imgen

imgen

Generate or edit images with AI models and write them to files; it can also remove solid-color backgrounds locally and downscale PNGs.

Environment Setup

If the command does not exist, or imgen version is lower than the metadata.requires version in the frontmatter, install and retry once:

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

On first use, run imgen providers --format jsonto see which providers already have credentials configured (configured), which one is used by default (selected), and what each model supports (image editing, mask, native transparency, sizing method, maximum number of input images). When the user does not specify, use the default; do not switch providers on your own.

Commands

Use imgen <command> --help to view the full parameters.

# 生成一张
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

Core parameters:

• --model [provider/]name Select the model, e.g. gemini/gemini-3-pro-image、openai/gpt-image-2
• --quality low|medium|high|auto: for drafts use low, for final versions and images with small text use medium or high
• --aspect W:H and --size WxH choose one of the two. When the model does not support exact sizes, it picks the nearest one and explains in warnings explained here
• --n N Sample the same prompt several times; variant count × n must not exceed 10

Workflow

1. Determine intent: new generation, or editing an existing image. When the user does not explicitly ask for an edit, treat it as new generation. Providing an image only as a style or composition reference also counts as new generation; pass the image via --image .
2. Label the role of each input image: write in the prompt Image 1: edit target、Image 2: style reference. The order matches the order of --image .
3. Write the prompt: if the user's request is specific, just organize the structure; only supplement details such as composition and purpose when the request is vague, and do not add people, objects, or copy that the user did not imply. For structure and key points for each type of asset, see references/prompting.md; for ready-made templates, see references/sample-prompts.md。
4. Choose the output location: write assets intended for the project directly to the target path in the project directory; put preview-only images in a temporary directory. Do not overwrite existing files unless the user asks; in that case add --force。
5. View the image after generation: check the subject, style, composition, text accuracy, and whether constraints are met. If unsatisfied, change only one aspect of the prompt at a time and regenerate; when editing, repeat the "keep unchanged" constraints every round.
6. Report: the final file path, the prompt used, the provider and model, and anything in warnings that the user should know.

Difference between variant and batch: to get several candidates for the same asset, use --variant or --n; for a set of different assets (e.g. an icon set, multiple illustrations), use batch.

batch

jobs.jsonl One task per line; only prompt is required:

{"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"}

• Available fields:prompt、variants、n、images、mask、provider、model、aspect、size、quality、background、chroma_key、output_format、compression、out
• out is the filename under --out-dir ; generate parameters on the command line serve as defaults for each line
• If any line has a problem, the whole batch errors out before sending requests;message starts with line N: beginning
• Retryable errors (rate limiting, timeout, 5xx) are retried up to 3 times by default (--max-attempts); with --fail-fast , no new tasks are started once the first failure occurs

Transparent Background

--background transparent when,data.transparent explains which method was used:

• native: the model natively outputs transparent PNG
• chroma-key: the model does not support transparency, so imgen has it drawn on a solid background and then removes it locally. The prompt should only describe the subject, do not write background requirements yourself. When the subject is green, add --chroma-key '#ff00ff'

In the results, for each image the transparent_ratio is the proportion of transparent pixels. When it is close to 0, or when looking at the image you find color fringing at the edges or background residue:

1. Change the --chroma-key color, or adjust the prompt so the subject outline is cleaner, then regenerate; or
2. switch to --background opaque, write "perfectly flat solid #00FF00 background" yourself in the prompt, then use imgen cutout to tune parameters:--key '#RRGGBB' specifies the background color,--contract 1 removes color fringing,--feather 1 softens the edges,--hard --tolerance N handles pixel art with sharp edges

cutout and resize only accept PNG. If the input is JPEG, convert it first; on macOS use sips -s format png in.jpg --out in.png。

rules

• Always add --format json, and read the final path from data.images[].path : when the return format and extension do not match, imgen changes the extension.
• When top-level ok is false but there are data , it is a partial failure; the successful images have already been written, so only regenerate the few that failed.
• content_policy: do not retry as-is; tell the user it was rejected, and you may adjust the wording and try again without changing the user's intent.
• exists: change the path, or after confirming the user agrees to overwrite, add --force。
• Exit code 2 is a parameter error or the model does not support a certain capability; fix according to message and retry.
• Exit code 3 is missing or invalid credentials: stop retrying, relay error.message to the user, and let the user set the API key or run codex login。
• Do not read, print, or pass the API key in command-line arguments; credentials are provided only via environment variables, api_key_command in the config file, or Codex login.
• Each request costs money and takes time (typically 10–60 seconds per image). When unsure whether parameters take effect, first use --dry-run; do not arbitrarily increase --n。