Vertex AI Image CLI Skill

Vertex AI Image CLI

A Python CLI for image generation, editing, and understanding via Google Gemini.

Prerequisites

Set one of these API keys:

export GEMINI_API_KEY=your-key-here        # Recommended (Gemini API)
export GOOGLE_CLOUD_API_KEY=your-key-here  # Also supported

Models

| Task | Model ID | Description | | -------------------- | -------------------------------- | ----------------------------------------------------------- | | Generation (default) | gemini-3.1-flash-image-preview | Nano Banana 2 — fast, balanced cost/quality | | Generation (pro) | gemini-3-pro-image-preview | Nano Banana Pro — professional assets, complex instructions | | Generation (fast) | gemini-2.5-flash-image | Nano Banana — high-volume, low-latency | | Image reading | gemini-2.5-flash | Text understanding model |

Commands

Generate an image from text

# Output defaults to $XDG_CACHE_HOME/vertex-ai-images/generate-{ts}-a-cat-astronaut-floating-in-space.png
uv run --script scripts/vertex_ai_image.py generate \
  --prompt "A cat astronaut floating in space"

# Or specify a custom output path
uv run --script scripts/vertex_ai_image.py generate \
  --prompt "A cat astronaut floating in space" \
  --output output/cat-astronaut.png

With aspect ratio and resolution:

uv run --script scripts/vertex_ai_image.py generate \
  --prompt "A panoramic mountain landscape at sunset" \
  --output output/landscape.png \
  --aspect-ratio 16:9 \
  --size 2K

Image-only output (no accompanying text):

uv run --script scripts/vertex_ai_image.py generate \
  --prompt "A minimalist logo for a coffee shop" \
  --output output/logo.png \
  --image-only

With high thinking level for complex prompts:

uv run --script scripts/vertex_ai_image.py generate \
  --prompt "An infographic explaining photosynthesis as a recipe" \
  --output output/infographic.png \
  --thinking-level high \
  --size 4K

Using a different model:

uv run --script scripts/vertex_ai_image.py generate \
  --prompt "A product photo of a perfume bottle" \
  --model gemini-3-pro-image-preview \
  --output output/perfume.png \
  --size 4K

Options:

--prompt, -p — Text prompt (required)
--output, -o — Output file path (default: $XDG_CACHE_HOME/vertex-ai-images/generate-{ts}-{slug}.png)
--model, -m — Model ID (default: gemini-3.1-flash-image-preview)
--aspect-ratio, -a — Aspect ratio: 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
--size, -s — Resolution: 512 (0.5K), 1K, 2K, 4K
--image-only — Return only image, suppress text output
--thinking-level, -t — Thinking level: minimal (default) or high
--dry-run — Preview without API call

Edit an image

Provide one or more input images with a text instruction to modify them:

uv run --script scripts/vertex_ai_image.py edit \
  --prompt "Make the cat wear a top hat and monocle" \
  --image photo.jpg \
  --output output/fancy-cat.png

With multiple reference images (up to 14):

uv run --script scripts/vertex_ai_image.py edit \
  --prompt "Create a group photo of these people at a beach" \
  --image person1.png \
  --image person2.png \
  --image person3.png \
  --output output/group.png \
  --aspect-ratio 16:9 \
  --size 2K

Style transfer with a reference:

uv run --script scripts/vertex_ai_image.py edit \
  --prompt "Redraw this photo in watercolor style" \
  --image original.jpg \
  --output output/watercolor.png

Options:

--prompt, -p — Edit instruction (required)
--image, -i — Input image path or gs:// URI (required, repeatable up to 14 times)
--output, -o — Output file path (default: $XDG_CACHE_HOME/vertex-ai-images/edit-{ts}-{slug}.png)
--model, -m — Model ID (default: gemini-3.1-flash-image-preview)
--aspect-ratio, -a — Output aspect ratio
--size, -s — Output resolution: 512, 1K, 2K, 4K
--image-only — Return only image, suppress text output
--thinking-level, -t — Thinking level: minimal or high
--dry-run — Preview without API call

Read/describe an image

# Local file
uv run --script scripts/vertex_ai_image.py read \
  --image photo.jpg \
  --prompt "What objects are in this image?"

# GCS URI
uv run --script scripts/vertex_ai_image.py read \
  --image gs://bucket/image.jpg

Options:

--image, -i — Local path or gs:// URI (required)
--prompt, -p — Question about the image (default: "Describe this image in detail.")
--model, -m — Model ID (default: gemini-2.5-flash)
--dry-run — Preview without API call

Aspect Ratios & Resolutions

| Aspect Ratio | 512 | 1K | 2K | 4K | | ------------ | ------- | --------- | --------- | --------- | | 1:1 | 512×512 | 1024×1024 | 2048×2048 | 4096×4096 | | 16:9 | 688×384 | 1376×768 | 2752×1536 | 5504×3072 | | 9:16 | 384×688 | 768×1376 | 1536×2752 | 3072×5504 | | 3:2 | 632×424 | 1264×848 | 2528×1696 | 5056×3392 | | 4:3 | 600×448 | 1200×896 | 2400×1792 | 4800×3584 |

512 resolution is only available on gemini-3.1-flash-image-preview. gemini-2.5-flash-image outputs 1024px only and does not support --size.

Tips

For text-heavy images (infographics, menus), generate the text first, then ask for an image containing it.
Use --thinking-level high for complex compositions that need layout reasoning.
Use gemini-3-pro-image-preview with --size 4K for professional-grade assets.
Use gemini-2.5-flash-image for high-volume, low-latency batch workloads.
Describe scenes narratively rather than listing keywords for best results.

Agent Skills: Vertex AI Image CLI

Install this agent skill to your local

Skill Files