Ultimate Gemini

Ultimate Gemini

Self-contained image generation. Derived from anand-92/ultimate-image-gen-mcp — tool surface, defaults, validation, and output shape mirror the original.

Prerequisites

• GEMINI_API_KEY (or GOOGLE_API_KEY) in the environment. If missing, tell the user to set it — do not try to fix it yourself. Get one: https://aistudio.google.com/app/apikey.
• Python deps: google-genai, pillow. Install on first run if missing:

``bash pip install google-genai pillow ``

The CLI

python3 /scripts/gemini_image.py generate-image --prompt "..." [flags]
python3 /scripts/gemini_image.py batch-generate --prompts "p1" "p2" ... [flags]

| Subcommand | Purpose | |-------------------|-----------------------------------------| | generate-image | Single image | | batch-generate | Up to 8 prompts, run in parallel |

Flag names are kebab-case (e.g. --enable-google-search, --reference-image-paths, --thinking-level). Defaults: aspect_ratio=1:1, image_size=2K, output_format=png, thinking_level=minimal, batch_size=8, model=gemini-3.1-flash-image-preview.

Images save to $PWD/gemini_images/ by default (a subfolder of the directory the script runs from — keeps output with the project you're working on). Override with $GEMINI_OUTPUT_DIR. The script prints a JSON result on stdout — parse it to report paths back to the user.

User preference overrides

The user's global preferences override the defaults when invoking this skill (unless they explicitly ask for something else):

• --image-size 1K (the user prefers 1K)
• --aspect-ratio 21:9 when generating banners / hero images

Apply these before falling back to script defaults.

Decision tree

1. One image → generate-image --prompt "...".
2. Multiple related images (storyboard, variations, product angles) → batch-generate --prompts "..." "...". Runs in parallel — always faster than serial generate-image calls.
3. Real product / person / current event → add --enable-google-search so the model grounds on live data (e.g. "Tony Hawk", "Way of Wade 12 shoes", "2025 iPhone").
4. Want visual style references from the web → add --enable-image-search.
5. Quality matters more than speed → --thinking-level high. Default minimal is fast and fine for most asks.

(If either search flag is on, the script forces minimal to avoid thought_signature errors from the API — expected.)

1. User provided reference image paths → --reference-image-paths path1 path2 ... (absolute paths, up to 14).

Prompting principles

• Less is more. "Tony Hawk kickflip" beats a paragraph; the model + search fills the rest.
• Don't pre-load style verbiage the user didn't ask for. A "logo for Acme" is not automatically "cinematic, 8K, hyperdetailed".
• For polished results in a specific style, pick a template from references/templates.md — each gives a crafted prompt body plus recommended params.

Common invocations

Banner / hero (user default)

python3 /scripts/gemini_image.py generate-image \
  --prompt "..." \
  --aspect-ratio 21:9 \
  --image-size 1K

Logo

python3 /scripts/gemini_image.py generate-image \
  --prompt " logo for , flat vector, strong silhouette, transparent background" \
  --aspect-ratio 1:1 \
  --image-size 1K \
  --response-modalities IMAGE

Product shot grounded in reality

python3 /scripts/gemini_image.py generate-image \
  --prompt "Way of Wade 12 shoes on studio white" \
  --aspect-ratio 1:1 \
  --image-size 1K \
  --enable-google-search --enable-image-search

Storyboard / variations (parallel)

python3 /scripts/gemini_image.py batch-generate \
  --prompts "scene 1 ..." "scene 2 ..." "scene 3 ..." "scene 4 ..." \
  --aspect-ratio 16:9 \
  --image-size 1K

With reference images

python3 /scripts/gemini_image.py generate-image \
  --prompt "same character in a new pose" \
  --reference-image-paths /abs/path/char1.png /abs/path/char2.png

Output shape

generate-image output (JSON):

{
  "success": true,
  "model": "gemini-3.1-flash-image-preview",
  "prompt": "...",
  "images_generated": 1,
  "images": [{"index": 0, "path": "...", "filename": "...", "size": 12345, "timestamp": "..."}],
  "text": null,
  "metadata": {"aspect_ratio": "1:1", "image_size": "2K", "output_format": "png", "thinking_level": "minimal"}
}

batch-generate output (JSON):

{
  "success": true,
  "total_prompts": 4, "batch_size": 8, "image_size": "1K", "output_format": "png",
  "completed": 4, "failed": 0,
  "results": [{"prompt_index": 0, "prompt": "...", "success": true, "images": [...], ...}]
}

Parameter reference

Full schema (14 aspect ratios, sizes, formats, modalities, batch semantics, env vars) is in references/parameters.md. Load it when the user pushes the edges or asks about options.

Prompt templates

26 domain-specific prompt recipes (photography, cinematic, product mockup, logo, storyboard, macro, fashion, technical cutaway, flat lay, action freeze, night street, drone aerial, stylized 3D, SEM microscopy, double exposure, architectural viz, isometric, food, motion blur, typography, retro-futurism, surreal dreamscape, character sheet, PBR texture, historical, bioluminescent, silhouette) live in references/templates.md. Load only when the user's request clearly maps to one.

After generation

• Parse stdout JSON and report the file path(s) to the user.
• If the user asked to "see" the image, open it:
• Linux / WSL (Linux path): xdg-open
• WSL (Windows-reachable path like /mnt/c/...): explorer.exe
• macOS: open
• If the script exits nonzero with an auth error, GEMINI_API_KEY is missing or expired — tell the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bradAGI
• Source: bradAGI/ultimate-gemini-skill
• License: MIT

Install and usage instructions live in the source repository linked above.