gemini-api
Google Gemini 3 Pro Image API reference. Covers text-to-image, editing, reference images, aspect ratios, and error handling.
When & Why to Use This Skill
This Claude skill provides a comprehensive technical reference and integration guide for the Google Gemini 3 Pro Image API. It empowers developers and creators to master text-to-image generation, sophisticated image editing, and style consistency through detailed documentation on CLI commands, model capabilities, and optimized aspect ratios, ensuring a robust and efficient visual content workflow.
Use Cases
- High-Quality Visual Prototyping: Rapidly generate 4K images for UI/UX mockups and creative concepts using specific prompts and style templates.
- Automated Social Media Content: Streamline the creation of platform-specific visuals by utilizing predefined aspect ratios such as 9:16 for stories and 1:1 for profile icons.
- Consistent Brand Asset Generation: Use reference images and the style flag to maintain visual consistency across multiple marketing assets and campaigns.
- Production-Ready API Integration: Implement reliable image generation services with built-in error handling, rate-limit management, and exponential backoff strategies.
| name | gemini-api |
|---|---|
| description | Google Gemini 3 Pro Image API reference. Covers text-to-image, editing, reference images, aspect ratios, and error handling. |
plugin: nanobanana updated: 2026-01-20
Gemini Image API Reference
Quick Start
# Set API key
export GEMINI_API_KEY="your-key"
# Generate image
uv run python main.py output.png "A minimal 3D cube"
API Key Setup
- Visit: https://makersuite.google.com/app/apikey
- Create new API key
- Set environment variable:
export GEMINI_API_KEY="your-api-key"
Supported Models
| Model | Resolution | Best For |
|---|---|---|
| gemini-3-pro-image-preview | Up to 4K | High quality |
| gemini-2.5-flash-image | Up to 1K | Quick iterations |
Aspect Ratios
| Ratio | Use Case |
|---|---|
| 1:1 | Social media, icons |
| 3:4 | Portrait photos |
| 4:3 | Traditional photos |
| 4:5 | Instagram portrait |
| 5:4 | Landscape photos |
| 9:16 | Mobile, stories |
| 16:9 | YouTube, desktop |
| 21:9 | Cinematic, ultrawide |
CLI Flags
| Flag | Description | Example |
|---|---|---|
--style |
Apply style template | --style styles/glass.md |
--edit |
Edit existing image | --edit photo.jpg |
--ref |
Reference image | --ref style.png |
--aspect |
Aspect ratio | --aspect 16:9 |
--model |
Model ID | --model gemini-2.5-flash-image |
--max-retries |
Retry attempts | --max-retries 5 |
Error Codes
| Code | Meaning | Recovery |
|---|---|---|
SUCCESS |
Operation completed | N/A |
API_KEY_MISSING |
GEMINI_API_KEY not set | Export the variable |
FILE_NOT_FOUND |
Referenced file missing | Check path |
INVALID_INPUT |
Bad prompt or argument | Fix input |
RATE_LIMITED |
Too many requests | Wait, uses auto-retry |
NETWORK_ERROR |
Connection failed | Check network, auto-retry |
API_ERROR |
Gemini API error | Check logs |
CONTENT_POLICY |
Blocked prompt | Adjust content |
TIMEOUT |
Request timed out | Retry |
PARTIAL_FAILURE |
Some batch items failed | Check individual results |
Retry Behavior
The script automatically retries on transient errors:
- Rate limits (429)
- Server errors (502, 503)
- Connection timeouts
- Network errors
Retry uses exponential backoff: 1s, 2s, 4s, 8s, etc.
Maximum retries configurable with --max-retries (default: 3)
Best Practices
- Prompts: Be specific about style, lighting, composition
- Styles: Use markdown templates for consistent results
- References: Provide visual examples for style matching
- Batch: Generate variations to pick the best
- Iteration: Edit results to refine
- Retries: Increase
--max-retriesfor unreliable connections