How do I install the Gemini API skill?

Run npx skillmds@latest add madappgang/gemini-api in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Gemini API safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Gemini API?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Gemini API free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Gemini API?

MadAppGang (@madappgang) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Gemini API by madappgang — Agent Skill

Name: Gemini API
Rating: 4.2 (5 reviews)
Author: MadAppGang

File contents

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-retries for unreliable connections

---name: gemini-apidescription: Google Gemini 3 Pro Image API reference. Covers text-to-image, editing, reference images, aspect ratios, and error handling.---plugin: nanobananaupdated: 2026-01-20# Gemini Image API Reference## Quick Start```bash# Set API keyexport GEMINI_API_KEY="your-key"# Generate imageuv run python main.py output.png "A minimal 3D cube"```## API Key Setup1. Visit: https://makersuite.google.com/app/apikey2. Create new API key3. 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 BehaviorThe script automatically retries on transient errors:- Rate limits (429)- Server errors (502, 503)- Connection timeouts- Network errorsRetry uses exponential backoff: 1s, 2s, 4s, 8s, etc.Maximum retries configurable with `--max-retries` (default: 3)## Best Practices1. **Prompts**: Be specific about style, lighting, composition2. **Styles**: Use markdown templates for consistent results3. **References**: Provide visual examples for style matching4. **Batch**: Generate variations to pick the best5. **Iteration**: Edit results to refine6. **Retries**: Increase `--max-retries` for unreliable connections

Frequently asked questions

Gemini API