home / skills / madappgang / claude-code / gemini-api

gemini-api skill

safe

This skill helps you generate and tailor Gemini Image API prompts and configurations for high-quality images, edits, and aspect-aware outputs.

npx playbooks add skill madappgang/claude-code --skill gemini-api

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.7 KB

---
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

```bash
# 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

1. Visit: https://makersuite.google.com/app/apikey
2. Create new API key
3. 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

1. **Prompts**: Be specific about style, lighting, composition
2. **Styles**: Use markdown templates for consistent results
3. **References**: Provide visual examples for style matching
4. **Batch**: Generate variations to pick the best
5. **Iteration**: Edit results to refine
6. **Retries**: Increase `--max-retries` for unreliable connections

Overview

This skill is a concise reference for using the Google Gemini image API via a TypeScript-based CLI and scripts. It documents supported models, aspect ratios, CLI flags, error codes, and retry behavior to help developers generate, edit, and iterate on images reliably. The content focuses on practical settings for image quality, composition, and operational recovery.

How this skill works

The skill inspects and explains the CLI options and API parameters used to call Gemini image models, including text-to-image generation, image editing with reference inputs, and style templates. It lists supported model IDs and recommended resolutions, maps common aspect ratios to use cases, and enumerates error codes with recovery steps. Retry behavior and exponential backoff details are provided to handle transient failures automatically.

When to use it

Generate high-quality images or quick prototypes using the appropriate Gemini model (e.g., gemini-3-pro-image-preview for up to 4K).
Edit or restyle photos by providing an existing image and a reference style file with the --edit and --ref flags.
Produce multiple variations or batches to select the best result and speed up iteration.
Integrate image generation into CI or scripts while handling transient network and server errors automatically.
Choose aspect ratios for platform-specific outputs (social, mobile stories, cinematic widescreen).

Best practices

Be specific in prompts: include style, lighting, composition, and focal details for predictable outputs.
Use markdown-style templates for repeatable style application across batches and projects.
Provide reference images for close stylistic matching instead of relying on text prompts alone.
Generate variations in batches to compare results and iterate by editing selected outputs.
Configure --max-retries and rely on exponential backoff for rate limits and transient network errors.

Example use cases

Create a 4K promotional image with gemini-3-pro-image-preview and --aspect 16:9 for desktop headers.
Edit a product photo using --edit product.jpg and --ref style.png to match a brand look.
Generate social media icons with --aspect 1:1 and a compact prompt for consistency across platforms.
Produce mobile story assets using --aspect 9:16 and batch generation for A/B testing creative variations.
Automate image generation in scripts with --max-retries set higher for unstable network environments.

FAQ

How do I set the API key?

Create an API key at makersuite.google.com/app/apikey and export it as GEMINI_API_KEY in your environment.

Which model should I pick for best quality?

Use gemini-3-pro-image-preview for highest quality up to 4K; use gemini-2.5-flash-image for faster, lower-resolution iterations.