Gen Image

Generate or edit images via AI image models. Generic — no style or domain knowledge. Higher-order skills build prompts and call the CLI scripts bundled here.

Prerequisites

• python3 must be available in PATH (no pip packages needed — stdlib only)
• GEMINI_API_KEY must be set. Add to one of:
  • Project .env (for project-level installs): echo 'GEMINI_API_KEY=your-key' >> .env
  • Global ~/.claude/.env (for global installs): echo 'GEMINI_API_KEY=your-key' >> ~/.claude/.env
  • Or export directly: export GEMINI_API_KEY=your-key

API calls consume Google AI credits. Imagen 4 requires billing. Gemini Flash has a free tier but is rate-limited. See Google AI pricing.

Variables

GI_CLI: python3 ./gemini-image.py # Path to the Gemini image CLI DEFAULT_CREATE_MODEL: gemini-3-pro-image-preview # Nano Banana Pro. Best quality + character/text fidelity. Override with --model (e.g. imagen-4.0-generate-001 for cheaper batches) DEFAULT_EDIT_MODEL: gemini-2.5-flash-image # Nano Banana. Default for edits DEFAULT_SIZE: 1280x960 # 4:3 landscape. Override with --size

Workflow

1. Check Prerequisites

   • IF: which python3 fails → report "python3 not found" and stop
   • IF: ./gemini-image.py not found → report "gemini-image CLI missing" and stop
   • IF: API key not available → run <GI_CLI> models as a lightweight auth check. If it fails with "GEMINI_API_KEY not set", stop and tell the user:

     GEMINI_API_KEY is not configured. Set it in one of:

     • Project-level: add GEMINI_API_KEY=your-key to ./.env
     • Global (recommended for personal use): add GEMINI_API_KEY=your-key to ~/.claude/.env
     • Shell: export GEMINI_API_KEY=your-key

     Get your API key at: https://aistudio.google.com/apikey

   • Example: python3 found, gemini-image.py exists, API key valid → proceed
   • Tool: Bash

2. Route Request

   • IF: user asks to create an image → go to step 3
   • IF: user asks to edit an existing image → go to step 4
   • IF: user asks about available models → run <GI_CLI> models and report results
   • IF: user asks to check remote API models → run <GI_CLI> models --remote
   • Example: "generate a sunset painting" → step 3 (create)
   • Example: "make the sky orange in photo.png" → step 4 (edit)
   • Example: "what models can I use?" → <GI_CLI> models
   • Tool: Bash <GI_CLI> models [--remote] [--json]

3. Create Image (Text to Image)

   • Generate a new image from a text prompt
   • IF: no --model → uses DEFAULT_CREATE_MODEL
   • IF: no --size → uses DEFAULT_SIZE
   • IF: no --output → saves as output.png in current directory
   • IF: safety filter triggers (empty response) → rephrase prompt to be more specific, less ambiguous
   • IF: rate limit (429) → wait and retry. Imagen 4 has generous limits; Gemini Flash free tier is stricter
   • Enrich vague prompts with specific details (style, lighting, composition, colors) before calling the API
   • Example: <GI_CLI> create "a watercolor painting of a mountain lake at sunset" --output lake.png
   • Example: <GI_CLI> create "pixel art treasure chest, 32x32 sprite" --size 1024x1024 --output chest.png
   • Example: <GI_CLI> create "photo of a red sports car" --model gemini-2.0-flash-exp --output car.png
   • Tool: Bash <GI_CLI> create <prompt> [--output <path>] [--size <WxH>] [--model <id>]

4. Edit Image (Image + Instruction)

   • Modify an existing image based on a text instruction
   • IF: no --model → uses DEFAULT_EDIT_MODEL
   • IF: no --output → saves as edited.png
   • IF: user wants to overwrite → set --output same as --input
   • Describe what to CHANGE, not what to keep. Good: "Make the sky orange." Bad: "Keep everything but change the sky."
   • Example: <GI_CLI> edit "change the background to a beach" --input photo.png --output beach.png
   • Example: <GI_CLI> edit "remove the text overlay" --input screenshot.png --output clean.png
   • Tool: Bash <GI_CLI> edit <instruction> --input <source> [--output <path>] [--model <id>]

5. Inspect and Iterate

   • Read the generated image to visually verify the result
   • Check for common AI artifacts: extra limbs, baked-in text, wrong colors, white borders, blur
   • IF: result needs small fixes → use edit command on the output
   • IF: result is fundamentally wrong → adjust prompt and create again
   • Example: Read output.png → spots extra finger → <GI_CLI> edit "remove the extra finger on the left hand" --input output.png --output fixed.png
   • Tool: Read (to view image), then Bash (to edit/recreate)

Reference

• IF: need full CLI flags, supported sizes, or model details → read reference/commands.md
• IF: need to add a new provider → see gemini-image.py as the reference implementation contract