imagegen
Text-to-image and image-editing CLI backed by Google Gemini's Nano Banana 2 family. JSON output.
CLI
- Path:
./imagegen-cli/imagegen (relative to this SKILL.md).
- Requires
uv (install). First call provisions the Python environment automatically.
- Subcommands:
generate (alias gen). Pass --image <path> (repeatable) to edit, restyle, or compose existing images instead of generating from scratch.
- Always run
imagegen generate --help to discover current flags and defaults. Do not memorize flag values — they evolve with the API.
API key
The CLI looks for the key in this order:
GEMINI_API_KEY environment variable..gemini-key file (raw key, no quotes) found by walking up from the current working directory — project-local override. Add .gemini-key to .gitignore.~/.gemini-key in the user's home directory — machine-wide default.
If none is found, the CLI returns code: "API_KEY_MISSING" with a recovery hint. Get a key at https://aistudio.google.com/apikey.
Models
The --model choice gates which other flags work. Pick the cheapest that meets the need.
| Model |
Sizes (--size) |
Aspect ratios (--aspect-ratio) |
--thinking |
Max --image inputs |
gemini-3.1-flash-image-preview (default) |
512, 1K, 2K, 4K |
1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 |
minimal (def.) / high |
14 |
gemini-3-pro-image-preview |
1K, 2K, 4K |
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
always on, not user-set |
14 |
gemini-2.5-flash-image |
not configurable |
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
n/a |
3 |
Use the default for almost everything. Switch to gemini-3-pro-image-preview for high-stakes assets (legible long text, complex multi-element compositions). Switch to gemini-2.5-flash-image only for cost reasons on simple prompts.
Prompting (these are thinking, creative models)
These models reason about composition and fill creative gaps on their own. Provide intent and context — not exhaustive specs.
- Give what only the user knows: brand, audience, where the asset goes, mood, must-include elements, must-avoid elements.
- Let the model choose lens, lighting, palette, and layout unless the user specified them.
- One narrative sentence beats a tag list. Describe the scene, not keywords.
- For exclusions, prefer rewriting the prompt positively (e.g. "an empty street" instead of
--negative-prompt "people, cars"). Use --negative-prompt only as a last resort.
- Iterate by saving the output and re-invoking with
--image <previous-output> plus a small directive (e.g. "warmer lighting, keep everything else").
Output rules
- Always pass
--output <path> and place the file in a project-appropriate assets directory (e.g. src/assets/, public/images/). Use a descriptive filename matching the content.
- After the call returns
ok:true, use the Read tool on the produced file path to confirm the image landed and looks right.
- Never generate copyrighted characters, real people's likenesses, or harmful content.
Editing / composition
Pass --image <path> one or more times in addition to the prompt. Same generate command. Examples of when to use it:
- Add or remove elements from an existing image.
- Apply a style transfer.
- Compose a scene from multiple references (e.g. a model + a garment).
- Maintain character consistency across renders.
- Refine a previous generation.
1---2name: imagegen3description: This skill should be used when the user asks to "generate an image", "create a cover image", "make an illustration", "generate artwork", "create a hero image", "generate a logo", "make a banner", "create an image for", "generate a thumbnail", "make an icon", "create visual content", "edit this image", "restyle this image", "compose these images", or needs AI-generated or AI-edited images for their project. Provides a CLI with JSON output optimized for LLM consumption.4---56# imagegen78Text-to-image and image-editing CLI backed by Google Gemini's Nano Banana 2 family. JSON output.910## CLI1112- Path: `./imagegen-cli/imagegen` (relative to this SKILL.md).13- Requires `uv` ([install](https://docs.astral.sh/uv/)). First call provisions the Python environment automatically.14- Subcommands: `generate` (alias `gen`). Pass `--image <path>` (repeatable) to edit, restyle, or compose existing images instead of generating from scratch.15- Always run `imagegen generate --help` to discover current flags and defaults. Do not memorize flag values — they evolve with the API.1617## API key1819The CLI looks for the key in this order:20211. `GEMINI_API_KEY` environment variable.222. `.gemini-key` file (raw key, no quotes) found by walking up from the current working directory — project-local override. Add `.gemini-key` to `.gitignore`.233. `~/.gemini-key` in the user's home directory — machine-wide default.2425If none is found, the CLI returns `code: "API_KEY_MISSING"` with a recovery hint. Get a key at <https://aistudio.google.com/apikey>.2627## Models2829The `--model` choice gates which other flags work. Pick the cheapest that meets the need.3031| Model | Sizes (`--size`) | Aspect ratios (`--aspect-ratio`) | `--thinking` | Max `--image` inputs |32| ---------------------------------- | ----------------------- | --------------------------------------------------------------------------- | ------------------------ | -------------------- |33| `gemini-3.1-flash-image-preview` (default) | `512`, `1K`, `2K`, `4K` | `1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9` | `minimal` (def.) / `high` | 14 |34| `gemini-3-pro-image-preview` | `1K`, `2K`, `4K` | `1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9` | always on, not user-set | 14 |35| `gemini-2.5-flash-image` | not configurable | `1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9` | n/a | 3 |3637Use the default for almost everything. Switch to `gemini-3-pro-image-preview` for high-stakes assets (legible long text, complex multi-element compositions). Switch to `gemini-2.5-flash-image` only for cost reasons on simple prompts.3839## Prompting (these are thinking, creative models)4041These models reason about composition and fill creative gaps on their own. Provide intent and context — not exhaustive specs.4243- Give what only the user knows: brand, audience, where the asset goes, mood, must-include elements, must-avoid elements.44- Let the model choose lens, lighting, palette, and layout unless the user specified them.45- One narrative sentence beats a tag list. Describe the scene, not keywords.46- For exclusions, prefer rewriting the prompt positively (e.g. "an empty street" instead of `--negative-prompt "people, cars"`). Use `--negative-prompt` only as a last resort.47- Iterate by saving the output and re-invoking with `--image <previous-output>` plus a small directive (e.g. "warmer lighting, keep everything else").4849## Output rules5051- Always pass `--output <path>` and place the file in a project-appropriate assets directory (e.g. `src/assets/`, `public/images/`). Use a descriptive filename matching the content.52- After the call returns `ok:true`, use the Read tool on the produced `file` path to confirm the image landed and looks right.53- Never generate copyrighted characters, real people's likenesses, or harmful content.5455## Editing / composition5657Pass `--image <path>` one or more times in addition to the prompt. Same `generate` command. Examples of when to use it:5859- Add or remove elements from an existing image.60- Apply a style transfer.61- Compose a scene from multiple references (e.g. a model + a garment).62- Maintain character consistency across renders.63- Refine a previous generation.
ThilinaTLM