ReddRadar
Agent skill
gemini-api
Google Gemini 3 Pro Image API reference. Covers text-to-image, editing, reference images, aspect ratios, and error handling.
Install this agent skill to your Project
npx add-skill https://github.com/MadAppGang/claude-code/tree/main/plugins/nanobanana/skills/gemini-api
SKILL.md
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:
bash
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
MadAppGang/claude-code
test-skill
A test skill for validation testing. Use when testing skill parsing and validation logic.
MadAppGang/claude-code
bad-skill
MadAppGang/claude-code
claudish-usage
CRITICAL - Guide for using Claudish CLI ONLY through sub-agents to run Claude Code with OpenRouter models (Grok, GPT-5, Gemini, MiniMax). NEVER run Claudish directly in main context unless user explicitly requests it. Use when user mentions external AI models, Claudish, OpenRouter, or alternative models. Includes mandatory sub-agent delegation patterns, agent selection guide, file-based instructions, and strict rules to prevent context window pollution.
MadAppGang/claude-code
release
Plugin release process for MAG Claude Plugins marketplace. Covers version bumping, marketplace.json updates, git tagging, and common mistakes. Use when releasing new plugin versions or troubleshooting update issues.
MadAppGang/claude-code
claudish-integration
MadAppGang/claude-code
openrouter-trending-models
Fetch trending programming models from OpenRouter rankings. Use when selecting models for multi-model review, updating model recommendations, or researching current AI coding trends. Provides model IDs, context windows, pricing, and usage statistics from the most recent week.
Didn't find tool you were looking for?