AgentSkillsCN

gemini-api

Google Gemini 3 Pro 图像 API 参考。涵盖文本转图像、图像编辑、参考图像、宽高比，以及错误处理机制。

SKILL.md
--- frontmatter
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

ModelResolutionBest For
gemini-3-pro-image-previewUp to 4KHigh quality
gemini-2.5-flash-imageUp to 1KQuick iterations

Aspect Ratios

RatioUse Case
1:1Social media, icons
3:4Portrait photos
4:3Traditional photos
4:5Instagram portrait
5:4Landscape photos
9:16Mobile, stories
16:9YouTube, desktop
21:9Cinematic, ultrawide

CLI Flags

FlagDescriptionExample
--styleApply style template--style styles/glass.md
--editEdit existing image--edit photo.jpg
--refReference image--ref style.png
--aspectAspect ratio--aspect 16:9
--modelModel ID--model gemini-2.5-flash-image
--max-retriesRetry attempts--max-retries 5

Error Codes

CodeMeaningRecovery
SUCCESSOperation completedN/A
API_KEY_MISSINGGEMINI_API_KEY not setExport the variable
FILE_NOT_FOUNDReferenced file missingCheck path
INVALID_INPUTBad prompt or argumentFix input
RATE_LIMITEDToo many requestsWait, uses auto-retry
NETWORK_ERRORConnection failedCheck network, auto-retry
API_ERRORGemini API errorCheck logs
CONTENT_POLICYBlocked promptAdjust content
TIMEOUTRequest timed outRetry
PARTIAL_FAILURESome batch items failedCheck 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