gemini-api
API reference and CLI guide for Google Gemini 3 Pro Image generation.
Install
mkdir -p .claude/skills/gemini-api && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5115" && unzip -o skill.zip -d .claude/skills/gemini-api && rm skill.zipInstalls to .claude/skills/gemini-api
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Google Gemini 3 Pro Image API reference. Covers text-to-image, editing, reference images, aspect ratios, and error handling.Key capabilities
- →Configures Gemini Image API requests
- →Sets aspect ratios for specific platforms
- →Handles API retries and error codes
- →Applies image style templates
How it works
It acts as a configuration interface for the Gemini Image API, translating CLI flags into valid API parameters and managing network retries.
Inputs & outputs
When to use gemini-api
- →Generate image from text
- →Edit existing images via API
- →Configure image aspect ratios
- →Handle API error codes
About this skill
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
When not to use it
- →Video generation tasks
- →Real-time interactive image processing
- →Non-Gemini image editing models
Prerequisites
Limitations
- →Strict reliance on Gemini 3 Pro model availability
- →Limited by current Gemini API output resolution caps
- →Does not provide local image processing
How it compares
It provides a centralized reference for platform-specific aspect ratios and standardizes error recovery behavior.
Compared to similar skills
gemini-api side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| gemini-api (this skill) | 1 | 6mo | Review | Beginner |
| ideogram-hello-world | 1 | 25d | Caution | Beginner |
| fastapi-templates | 520 | 2mo | No flags | Intermediate |
| mcp-builder | 136 | 3mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by MadAppGang
View all by MadAppGang →You might also like
ideogram-hello-world
jeremylongshore
Create a minimal working Ideogram example. Use when starting a new Ideogram integration, testing your setup, or learning basic Ideogram API patterns. Trigger with phrases like "ideogram hello world", "ideogram example", "ideogram quick start", "simple ideogram code".
fastapi-templates
wshobson
Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects.
mcp-builder
anthropics
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
fastapi-pro
sickn33
Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and Pydantic V2. Master microservices, WebSockets, and modern Python async patterns. Use PROACTIVELY for FastAPI development, async optimization, or API architecture.
telegram-bot-builder
davila7
Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot.
stripe-integration
wshobson
Implement Stripe payment processing for robust, PCI-compliant payment flows including checkout, subscriptions, and webhooks. Use when integrating Stripe payments, building subscription systems, or implementing secure checkout flows.