generate-image CLI
Generate images using Gemini's Nano Banana model series. The CLI handles API calls, reference image loading, multi-variant generation, and JSON output.
When to Use This Skill
- User asks to generate, create, or edit an image
- User needs product photos, starting frames, or visual assets
- User mentions Gemini image generation, Nano Banana, or specific model IDs
- User wants to generate multiple image variants from a single prompt
CLI Usage
generate-image \
--provider google \
--model <model-id> \
--prompt "your prompt" \
--output path/to/output.png \
[--aspect-ratio 9:16] \
[--references path/to/ref1.png --references path/to/ref2.png] \
[--variants 4] \
[--image-size 2K]
Flags
| Flag | Required | Default | Description |
|---|---|---|---|
--provider |
Yes | — | Provider name: google |
--model |
Yes | — | Model ID (see Model Comparison below) |
--prompt |
Yes | — | Generation prompt |
--output |
Yes | — | Output file path (e.g. images/photo.png) |
--aspect-ratio |
No | 9:16 |
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
--references |
No | — | Reference image paths. Repeat flag for each file. |
--variants |
No | 1 |
Number of variants to generate (outputs _1.png, _2.png, etc.) |
--image-size |
No | — | Resolution: 1K, 2K, 4K (Pro model only, uppercase K) |
Model Comparison
| Model | ID | Best For | Resolution | Speed | Max References |
|---|---|---|---|---|---|
| Nano Banana | gemini-2.5-flash-image |
High-volume, low-latency, rapid iteration | 1024px | Fast | 3 |
| Nano Banana Pro | gemini-3-pro-image-preview |
Professional assets, complex instructions, text-in-image | Up to 4K | Slower | 14 (5 high-fidelity) |
See models/gemini-flash.md and models/gemini-pro.md for details.
JSON Output
All output goes to stdout as JSON. Progress messages go to stderr.
Success
{
"status": "success",
"provider": "google",
"model": "gemini-2.5-flash-image",
"output_files": ["images/photo_1.png", "images/photo_2.png"],
"elapsed_seconds": 12.5,
"metadata": {}
}
Error
{
"status": "error",
"provider": "google",
"model": "gemini-2.5-flash-image",
"error_code": "generation_failed",
"error_message": "Content policy violation",
"elapsed_seconds": 2.1
}
Exit Codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Generation failed (content_policy, timeout, quota_exceeded, etc.) |
2 |
Invalid provider or model |
3 |
Proxy unreachable |
Error Handling
error_code |
Meaning | Recovery |
|---|---|---|
generation_failed |
General generation failure | Check prompt, retry |
content_policy |
Prompt violates content policy | Adjust prompt, remove banned content |
timeout |
Generation took too long | Retry |
quota_exceeded |
Rate limit hit | Wait 30s, retry |
invalid_image |
Bad reference image | Check image format/path |
proxy_unreachable |
GenAI proxy is down | Cannot proceed, skip generation |
Examples
Text-to-image (Flash, fast)
generate-image \
--provider google \
--model gemini-2.5-flash-image \
--prompt "A photorealistic close-up of a ceramic coffee mug on a concrete surface, soft studio lighting" \
--output images/mug.png \
--aspect-ratio 1:1
With product references (Pro, high quality)
generate-image \
--provider google \
--model gemini-3-pro-image-preview \
--prompt "A creator holds the product naturally, casual selfie style, warm indoor lighting" \
--output images/creator_shot.png \
--aspect-ratio 9:16 \
--references product_images/product_1.png \
--references product_images/product_2.png \
--image-size 2K
Multi-variant generation
generate-image \
--provider google \
--model gemini-3-pro-image-preview \
--prompt "UGC-style starting frame with product" \
--output images/starting_frame.png \
--aspect-ratio 9:16 \
--references product_images/product_1.png \
--variants 4
Outputs: starting_frame_1.png, starting_frame_2.png, starting_frame_3.png, starting_frame_4.png
Prompting
Good prompts are descriptive narratives, not keyword lists. See:
- Best practices — Prompting strategies, camera control, model-specific tips
- Generation templates — 7 templates: photorealistic, stylized, text-in-image, product mockups, minimalist, sequential art, search-grounded
- Editing templates — 6 techniques: add/remove elements, inpainting, style transfer, multi-image composition, detail preservation, sketch-to-photo
- Character consistency — Multi-angle 360-degree character generation
Limitations
- All generated images include a SynthID watermark
- Best performance in: EN, ar-EG, de-DE, es-MX, fr-FR, hi-IN, id-ID, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, ua-UA, vi-VN, zh-CN
- For text-in-image accuracy, generate text first then ask for image with text
- Flash: best with up to 3 input images; Pro: 5 high-fidelity + up to 14 total
What's next? Use these images in a full UGC pipeline
You've generated product photos. On the Genieus platform, these become starting frames for UGC videos — the agent writes the script, picks the best frame, and renders a 15-second video.
On genieus.io:
- Product photos → UGC video starting frames
- AI script generation matched to your visuals
- Full campaign from images to published video ads