Ai Multimodal

# Google Gemini API Configuration

# ============================================================================
# OPTION 1: Google AI Studio (Default - Recommended for most users)
# ============================================================================
# Get your API key: https://aistudio.google.com/apikey
GEMINI_API_KEY=your_api_key_here

# ============================================================================
# OPTION 2: Vertex AI (Google Cloud Platform)
# ============================================================================
# Uncomment these lines to use Vertex AI instead of Google AI Studio
# GEMINI_USE_VERTEX=true
# VERTEX_PROJECT_ID=your-gcp-project-id
# VERTEX_LOCATION=us-central1

# ============================================================================
# Model Selection (Optional)
# ============================================================================
# Override default model for specific tasks
# Default: gemini-2.5-flash for most tasks
# GEMINI_MODEL=gemini-2.5-flash
# GEMINI_IMAGE_GEN_MODEL=gemini-2.5-flash-image

# ============================================================================
# Rate Limiting Configuration (Optional)
# ============================================================================
# Requests per minute limit (adjust based on your tier)
# GEMINI_RPM_LIMIT=15

# Tokens per minute limit
# GEMINI_TPM_LIMIT=4000000

# Requests per day limit
# GEMINI_RPD_LIMIT=1500

# ============================================================================
# Processing Options (Optional)
# ============================================================================
# Video resolution mode: default or low-res
# low-res uses ~100 tokens/second vs ~300 for default
# GEMINI_VIDEO_RESOLUTION=default

# Audio quality: default (16 Kbps mono, auto-downsampled)
# GEMINI_AUDIO_QUALITY=default

# PDF processing mode: inline (<20MB) or file-api (>20MB, automatic)
# GEMINI_PDF_MODE=auto

# ============================================================================
# Retry Configuration (Optional)
# ============================================================================
# Maximum retry attempts for failed requests
# GEMINI_MAX_RETRIES=3

# Initial retry delay in seconds (uses exponential backoff)
# GEMINI_RETRY_DELAY=1

# ============================================================================
# Output Configuration (Optional)
# ============================================================================
# Default output directory for generated images
# OUTPUT_DIR=./output

# Image output format (png or jpeg)
# IMAGE_FORMAT=png

# Image quality for JPEG (1-100)
# IMAGE_QUALITY=95

# ============================================================================
# Context Caching (Optional)
# ============================================================================
# Enable context caching for repeated queries on same file
# GEMINI_ENABLE_CACHING=true

# Cache TTL in seconds (default: 1800 = 30 minutes)
# GEMINI_CACHE_TTL=1800

# ============================================================================
# Logging (Optional)
# ============================================================================
# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
# LOG_LEVEL=INFO

# Log file path
# LOG_FILE=./logs/gemini.log

# ============================================================================
# Notes
# ============================================================================
# 1. Never commit API keys to version control
# 2. Add .env to .gitignore
# 3. API keys can be restricted in Google Cloud Console
# 4. Monitor usage at: https://aistudio.google.com/apikey
# 5. Free tier limits: 15 RPM, 1M-4M TPM, 1,500 RPD
# 6. Vertex AI requires GCP authentication via gcloud CLI

{
  "description": "Process and generate multimedia content using Google Gemini API. Capabilities include analyze audio files (transcription with timestamps, summarization, speech understanding, music/sound analysis up to 9.5 hours), understand images (captioning, object detection, OCR, visual Q&A, segmentation), process videos (scene detection, Q&A, temporal analysis, YouTube URLs, up to 6 hours), extract from documents (PDF tables, forms, charts, diagrams, multi-page), generate images (text-to-image, editing, composition, refinement). Use when working with audio/video files, analyzing images or screenshots, processing PDF documents, extracting structured data from media, creating images from text prompts, or implementing multimodal AI features. Supports multiple models (Gemini 2.5/2.0) with context windows up to 2M tokens.",
  "metadata": {
    "license": "MIT"
  },
  "references": {
    "files": [
      "references/audio-processing.md",
      "references/document-extraction.md",
      "references/image-generation.md",
      "references/video-analysis.md",
      "references/vision-understanding.md"
    ]
  },
  "content": "Process audio, images, videos, documents, and generate images using Google Gemini's multimodal API. Unified interface for all multimedia content understanding and generation.\r\n\r\n\r\n### Prerequisites\r\n\r\n**API Key Setup**: Supports both Google AI Studio and Vertex AI.\r\n\r\nThe skill checks for `GEMINI_API_KEY` in this order:\r\n1. Process environment: `export GEMINI_API_KEY=\"your-key\"`\r\n2. Project root: `.env`\r\n3. `.claude/.env`\r\n4. `.claude/skills/.env`\r\n5. `.claude/skills/ai-multimodal/.env`\r\n\r\n**Get API key**: https://aistudio.google.com/apikey\r\n\r\n**For Vertex AI**:\r\n```bash\r\nexport GEMINI_USE_VERTEX=true\r\nexport VERTEX_PROJECT_ID=your-gcp-project-id\r\nexport VERTEX_LOCATION=us-central1  # Optional\r\n```\r\n\r\n**Install SDK**:\r\n```bash\r\npip install google-genai python-dotenv pillow\r\n```\r\n\r\n### Common Patterns\r\n\r\n**Transcribe Audio**:\r\n```bash\r\npython scripts/gemini_batch_process.py \\\r\n  --files audio.mp3 \\\r\n  --task transcribe \\\r\n  --model gemini-2.5-flash\r\n```\r\n\r\n**Analyze Image**:\r\n```bash\r\npython scripts/gemini_batch_process.py \\\r\n  --files image.jpg \\\r\n  --task analyze \\\r\n  --prompt \"Describe this image\" \\\r\n  --model gemini-2.5-flash\r\n```\r\n\r\n**Process Video**:\r\n```bash\r\npython scripts/gemini_batch_process.py \\\r\n  --files video.mp4 \\\r\n  --task analyze \\\r\n  --prompt \"Summarize key points with timestamps\" \\\r\n  --model gemini-2.5-flash\r\n```\r\n\r\n**Extract from PDF**:\r\n```bash\r\npython scripts/gemini_batch_process.py \\\r\n  --files document.pdf \\\r\n  --task extract \\\r\n  --prompt \"Extract table data as JSON\" \\\r\n  --format json\r\n```\r\n\r\n**Generate Image**:\r\n```bash\r\npython scripts/gemini_batch_process.py \\\r\n  --task generate \\\r\n  --prompt \"A futuristic city at sunset\" \\\r\n  --model gemini-2.5-flash-image \\\r\n  --aspect-ratio 16:9\r\n```\r\n\r\n**Optimize Media**:\r\n```bash\r\npython scripts/media_optimizer.py \\\r\n  --input large-video.mp4 \\\r\n  --output optimized-video.mp4 \\\r\n  --target-size 100MB\r\n\r\npython scripts/media_optimizer.py \\\r\n  --input-dir ./videos \\\r\n  --output-dir ./optimized \\\r\n  --quality 85\r\n```\r\n\r\n**Convert Documents**:\r\n```bash\r\npython scripts/document_converter.py \\\r\n  --input document.docx \\\r\n  --output document.pdf",
  "name": "ai-multimodal",
  "id": "ai-multimodal_mrgoonie",
  "sections": {
    "Quick Start": "python scripts/document_converter.py \\\r\n  --input large.pdf \\\r\n  --output chapter1.pdf \\\r\n  --pages 1-20\r\n```",
    "Reference Navigation": "For detailed implementation guidance, see:\r\n\r\n### Audio Processing\r\n- `references/audio-processing.md` - Transcription, analysis, TTS\r\n  - Timestamp handling and segment analysis\r\n  - Multi-speaker identification\r\n  - Non-speech audio analysis\r\n  - Text-to-speech generation\r\n\r\n### Image Understanding\r\n- `references/vision-understanding.md` - Captioning, detection, OCR\r\n  - Object detection and localization\r\n  - Pixel-level segmentation\r\n  - Visual question answering\r\n  - Multi-image comparison\r\n\r\n### Video Analysis\r\n- `references/video-analysis.md` - Scene detection, temporal understanding\r\n  - YouTube URL processing\r\n  - Timestamp-based queries\r\n  - Video clipping and FPS control\r\n  - Long video optimization\r\n\r\n### Document Extraction\r\n- `references/document-extraction.md` - PDF processing, structured output\r\n  - Table and form extraction\r\n  - Chart and diagram analysis\r\n  - JSON schema validation\r\n  - Multi-page handling\r\n\r\n### Image Generation\r\n- `references/image-generation.md` - Text-to-image, editing\r\n  - Prompt engineering strategies\r\n  - Image editing and composition\r\n  - Aspect ratio selection\r\n  - Safety settings",
    "Error Handling": "Common errors and solutions:\r\n- **400**: Invalid format/size - validate before upload\r\n- **401**: Invalid API key - check configuration\r\n- **403**: Permission denied - verify API key restrictions\r\n- **404**: File not found - ensure file uploaded and active\r\n- **429**: Rate limit exceeded - implement exponential backoff\r\n- **500**: Server error - retry with backoff",
    "Rate Limits": "**Free Tier**:\r\n- 10-15 RPM (requests per minute)\r\n- 1M-4M TPM (tokens per minute)\r\n- 1,500 RPD (requests per day)\r\n\r\n**YouTube Limits**:\r\n- Free tier: 8 hours/day\r\n- Paid tier: No length limits\r\n- Public videos only\r\n\r\n**Storage Limits**:\r\n- 20GB per project\r\n- 2GB per file\r\n- 48-hour retention",
    "Scripts Overview": "All scripts support unified API key detection and error handling:\r\n\r\n**gemini_batch_process.py**: Batch process multiple media files\r\n- Supports all modalities (audio, image, video, PDF)\r\n- Progress tracking and error recovery\r\n- Output formats: JSON, Markdown, CSV\r\n- Rate limiting and retry logic\r\n- Dry-run mode\r\n\r\n**media_optimizer.py**: Prepare media for Gemini API\r\n- Compress videos/audio for size limits\r\n- Resize images appropriately\r\n- Split long videos into chunks\r\n- Format conversion\r\n- Quality vs size optimization\r\n\r\n**document_converter.py**: Convert documents to PDF\r\n- Convert DOCX, XLSX, PPTX to PDF\r\n- Extract page ranges\r\n- Optimize PDFs for Gemini\r\n- Extract images from PDFs\r\n- Batch conversion support\r\n\r\nRun any script with `--help` for detailed usage.",
    "Model Selection Guide": "### Gemini 2.5 Series (Recommended)\r\n- **gemini-2.5-pro**: Highest quality, all features, 1M-2M context\r\n- **gemini-2.5-flash**: Best balance, all features, 1M-2M context\r\n- **gemini-2.5-flash-lite**: Lightweight, segmentation support\r\n- **gemini-2.5-flash-image**: Image generation only\r\n\r\n### Gemini 2.0 Series\r\n- **gemini-2.0-flash**: Fast processing, object detection\r\n- **gemini-2.0-flash-lite**: Lightweight option\r\n\r\n### Feature Requirements\r\n- **Segmentation**: Requires 2.5+ models\r\n- **Object Detection**: Requires 2.0+ models\r\n- **Multi-video**: Requires 2.5+ models\r\n- **Image Generation**: Requires flash-image model\r\n\r\n### Context Windows\r\n- **2M tokens**: ~6 hours video (low-res) or ~2 hours (default)\r\n- **1M tokens**: ~3 hours video (low-res) or ~1 hour (default)\r\n- **Audio**: 32 tokens/second (1 min = 1,920 tokens)\r\n- **PDF**: 258 tokens/page (fixed)\r\n- **Image**: 258-1,548 tokens based on size",
    "Capability Matrix": "| Task | Audio | Image | Video | Document | Generation |\r\n|------|:-----:|:-----:|:-----:|:--------:|:----------:|\r\n| Transcription | ✓ | - | ✓ | - | - |\r\n| Summarization | ✓ | ✓ | ✓ | ✓ | - |\r\n| Q&A | ✓ | ✓ | ✓ | ✓ | - |\r\n| Object Detection | - | ✓ | ✓ | - | - |\r\n| Text Extraction | - | ✓ | - | ✓ | - |\r\n| Structured Output | ✓ | ✓ | ✓ | ✓ | - |\r\n| Creation | TTS | - | - | - | ✓ |\r\n| Timestamps | ✓ | - | ✓ | - | - |\r\n| Segmentation | - | ✓ | - | - | - |",
    "Core Capabilities": "### Audio Processing\r\n- Transcription with timestamps (up to 9.5 hours)\r\n- Audio summarization and analysis\r\n- Speech understanding and speaker identification\r\n- Music and environmental sound analysis\r\n- Text-to-speech generation with controllable voice\r\n\r\n### Image Understanding\r\n- Image captioning and description\r\n- Object detection with bounding boxes (2.0+)\r\n- Pixel-level segmentation (2.5+)\r\n- Visual question answering\r\n- Multi-image comparison (up to 3,600 images)\r\n- OCR and text extraction\r\n\r\n### Video Analysis\r\n- Scene detection and summarization\r\n- Video Q&A with temporal understanding\r\n- Transcription with visual descriptions\r\n- YouTube URL support\r\n- Long video processing (up to 6 hours)\r\n- Frame-level analysis\r\n\r\n### Document Extraction\r\n- Native PDF vision processing (up to 1,000 pages)\r\n- Table and form extraction\r\n- Chart and diagram analysis\r\n- Multi-page document understanding\r\n- Structured data output (JSON schema)\r\n- Format conversion (PDF to HTML/JSON)\r\n\r\n### Image Generation\r\n- Text-to-image generation\r\n- Image editing and modification\r\n- Multi-image composition (up to 3 images)\r\n- Iterative refinement\r\n- Multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)\r\n- Controllable style and quality",
    "Supported Formats": "### Audio\r\n- WAV, MP3, AAC, FLAC, OGG Vorbis, AIFF\r\n- Max 9.5 hours per request\r\n- Auto-downsampled to 16 Kbps mono\r\n\r\n### Images\r\n- PNG, JPEG, WEBP, HEIC, HEIF\r\n- Max 3,600 images per request\r\n- Resolution: ≤384px = 258 tokens, larger = tiled\r\n\r\n### Video\r\n- MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP\r\n- Max 6 hours (low-res) or 2 hours (default)\r\n- YouTube URLs supported (public only)\r\n\r\n### Documents\r\n- PDF only for vision processing\r\n- Max 1,000 pages\r\n- TXT, HTML, Markdown supported (text-only)\r\n\r\n### Size Limits\r\n- **Inline**: <20MB total request\r\n- **File API**: 2GB per file, 20GB project quota\r\n- **Retention**: 48 hours auto-delete",
    "Resources": "- [Audio API Docs](https://ai.google.dev/gemini-api/docs/audio)\r\n- [Image API Docs](https://ai.google.dev/gemini-api/docs/image-understanding)\r\n- [Video API Docs](https://ai.google.dev/gemini-api/docs/video-understanding)\r\n- [Document API Docs](https://ai.google.dev/gemini-api/docs/document-processing)\r\n- [Image Gen Docs](https://ai.google.dev/gemini-api/docs/image-generation)\r\n- [Get API Key](https://aistudio.google.com/apikey)\r\n- [Pricing](https://ai.google.dev/pricing)",
    "Cost Optimization": "### Token Costs\r\n**Input Pricing**:\r\n- Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output\r\n- Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output\r\n- Gemini 1.5 Flash: $0.70/1M input, $0.175/1M output\r\n\r\n**Token Rates**:\r\n- Audio: 32 tokens/second (1 min = 1,920 tokens)\r\n- Video: ~300 tokens/second (default) or ~100 (low-res)\r\n- PDF: 258 tokens/page (fixed)\r\n- Image: 258-1,548 tokens based on size\r\n\r\n**TTS Pricing**:\r\n- Flash TTS: $10/1M tokens\r\n- Pro TTS: $20/1M tokens\r\n\r\n### Best Practices\r\n1. Use `gemini-2.5-flash` for most tasks (best price/performance)\r\n2. Use File API for files >20MB or repeated queries\r\n3. Optimize media before upload (see `media_optimizer.py`)\r\n4. Process specific segments instead of full videos\r\n5. Use lower FPS for static content\r\n6. Implement context caching for repeated queries\r\n7. Batch process multiple files in parallel"
  }
}

---
name: ai-multimodal
description: Process and generate multimedia content using Google Gemini API. Capabilities include analyze audio files (transcription with timestamps, summarization, speech understanding, music/sound analysis up to 9.5 hours), understand images (captioning, object detection, OCR, visual Q&A, segmentation), process videos (scene detection, Q&A, temporal analysis, YouTube URLs, up to 6 hours), extract from documents (PDF tables, forms, charts, diagrams, multi-page), generate images (text-to-image, editing, composition, refinement). Use when working with audio/video files, analyzing images or screenshots, processing PDF documents, extracting structured data from media, creating images from text prompts, or implementing multimodal AI features. Supports multiple models (Gemini 2.5/2.0) with context windows up to 2M tokens.
license: MIT
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
---

# AI Multimodal Processing Skill

Process audio, images, videos, documents, and generate images using Google Gemini's multimodal API. Unified interface for all multimedia content understanding and generation.

## Core Capabilities

### Audio Processing
- Transcription with timestamps (up to 9.5 hours)
- Audio summarization and analysis
- Speech understanding and speaker identification
- Music and environmental sound analysis
- Text-to-speech generation with controllable voice

### Image Understanding
- Image captioning and description
- Object detection with bounding boxes (2.0+)
- Pixel-level segmentation (2.5+)
- Visual question answering
- Multi-image comparison (up to 3,600 images)
- OCR and text extraction

### Video Analysis
- Scene detection and summarization
- Video Q&A with temporal understanding
- Transcription with visual descriptions
- YouTube URL support
- Long video processing (up to 6 hours)
- Frame-level analysis

### Document Extraction
- Native PDF vision processing (up to 1,000 pages)
- Table and form extraction
- Chart and diagram analysis
- Multi-page document understanding
- Structured data output (JSON schema)
- Format conversion (PDF to HTML/JSON)

### Image Generation
- Text-to-image generation
- Image editing and modification
- Multi-image composition (up to 3 images)
- Iterative refinement
- Multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)
- Controllable style and quality

## Capability Matrix

| Task | Audio | Image | Video | Document | Generation |
|------|:-----:|:-----:|:-----:|:--------:|:----------:|
| Transcription | ✓ | - | ✓ | - | - |
| Summarization | ✓ | ✓ | ✓ | ✓ | - |
| Q&A | ✓ | ✓ | ✓ | ✓ | - |
| Object Detection | - | ✓ | ✓ | - | - |
| Text Extraction | - | ✓ | - | ✓ | - |
| Structured Output | ✓ | ✓ | ✓ | ✓ | - |
| Creation | TTS | - | - | - | ✓ |
| Timestamps | ✓ | - | ✓ | - | - |
| Segmentation | - | ✓ | - | - | - |

## Model Selection Guide

### Gemini 2.5 Series (Recommended)
- **gemini-2.5-pro**: Highest quality, all features, 1M-2M context
- **gemini-2.5-flash**: Best balance, all features, 1M-2M context
- **gemini-2.5-flash-lite**: Lightweight, segmentation support
- **gemini-2.5-flash-image**: Image generation only

### Gemini 2.0 Series
- **gemini-2.0-flash**: Fast processing, object detection
- **gemini-2.0-flash-lite**: Lightweight option

### Feature Requirements
- **Segmentation**: Requires 2.5+ models
- **Object Detection**: Requires 2.0+ models
- **Multi-video**: Requires 2.5+ models
- **Image Generation**: Requires flash-image model

### Context Windows
- **2M tokens**: ~6 hours video (low-res) or ~2 hours (default)
- **1M tokens**: ~3 hours video (low-res) or ~1 hour (default)
- **Audio**: 32 tokens/second (1 min = 1,920 tokens)
- **PDF**: 258 tokens/page (fixed)
- **Image**: 258-1,548 tokens based on size

## Quick Start

### Prerequisites

**API Key Setup**: Supports both Google AI Studio and Vertex AI.

The skill checks for `GEMINI_API_KEY` in this order:
1. Process environment: `export GEMINI_API_KEY="your-key"`
2. Project root: `.env`
3. `.claude/.env`
4. `.claude/skills/.env`
5. `.claude/skills/ai-multimodal/.env`

**Get API key**: https://aistudio.google.com/apikey

**For Vertex AI**:
```bash
export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1  # Optional
```

**Install SDK**:
```bash
pip install google-genai python-dotenv pillow
```

### Common Patterns

**Transcribe Audio**:
```bash
python scripts/gemini_batch_process.py \
  --files audio.mp3 \
  --task transcribe \
  --model gemini-2.5-flash
```

**Analyze Image**:
```bash
python scripts/gemini_batch_process.py \
  --files image.jpg \
  --task analyze \
  --prompt "Describe this image" \
  --model gemini-2.5-flash
```

**Process Video**:
```bash
python scripts/gemini_batch_process.py \
  --files video.mp4 \
  --task analyze \
  --prompt "Summarize key points with timestamps" \
  --model gemini-2.5-flash
```

**Extract from PDF**:
```bash
python scripts/gemini_batch_process.py \
  --files document.pdf \
  --task extract \
  --prompt "Extract table data as JSON" \
  --format json
```

**Generate Image**:
```bash
python scripts/gemini_batch_process.py \
  --task generate \
  --prompt "A futuristic city at sunset" \
  --model gemini-2.5-flash-image \
  --aspect-ratio 16:9
```

**Optimize Media**:
```bash
# Prepare large video for processing
python scripts/media_optimizer.py \
  --input large-video.mp4 \
  --output optimized-video.mp4 \
  --target-size 100MB

# Batch optimize multiple files
python scripts/media_optimizer.py \
  --input-dir ./videos \
  --output-dir ./optimized \
  --quality 85
```

**Convert Documents**:
```bash
# Convert to PDF
python scripts/document_converter.py \
  --input document.docx \
  --output document.pdf

# Extract pages
python scripts/document_converter.py \
  --input large.pdf \
  --output chapter1.pdf \
  --pages 1-20
```

## Supported Formats

### Audio
- WAV, MP3, AAC, FLAC, OGG Vorbis, AIFF
- Max 9.5 hours per request
- Auto-downsampled to 16 Kbps mono

### Images
- PNG, JPEG, WEBP, HEIC, HEIF
- Max 3,600 images per request
- Resolution: ≤384px = 258 tokens, larger = tiled

### Video
- MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP
- Max 6 hours (low-res) or 2 hours (default)
- YouTube URLs supported (public only)

### Documents
- PDF only for vision processing
- Max 1,000 pages
- TXT, HTML, Markdown supported (text-only)

### Size Limits
- **Inline**: <20MB total request
- **File API**: 2GB per file, 20GB project quota
- **Retention**: 48 hours auto-delete

## Reference Navigation

For detailed implementation guidance, see:

### Audio Processing
- `references/audio-processing.md` - Transcription, analysis, TTS
  - Timestamp handling and segment analysis
  - Multi-speaker identification
  - Non-speech audio analysis
  - Text-to-speech generation

### Image Understanding
- `references/vision-understanding.md` - Captioning, detection, OCR
  - Object detection and localization
  - Pixel-level segmentation
  - Visual question answering
  - Multi-image comparison

### Video Analysis
- `references/video-analysis.md` - Scene detection, temporal understanding
  - YouTube URL processing
  - Timestamp-based queries
  - Video clipping and FPS control
  - Long video optimization

### Document Extraction
- `references/document-extraction.md` - PDF processing, structured output
  - Table and form extraction
  - Chart and diagram analysis
  - JSON schema validation
  - Multi-page handling

### Image Generation
- `references/image-generation.md` - Text-to-image, editing
  - Prompt engineering strategies
  - Image editing and composition
  - Aspect ratio selection
  - Safety settings

## Cost Optimization

### Token Costs
**Input Pricing**:
- Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output
- Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output
- Gemini 1.5 Flash: $0.70/1M input, $0.175/1M output

**Token Rates**:
- Audio: 32 tokens/second (1 min = 1,920 tokens)
- Video: ~300 tokens/second (default) or ~100 (low-res)
- PDF: 258 tokens/page (fixed)
- Image: 258-1,548 tokens based on size

**TTS Pricing**:
- Flash TTS: $10/1M tokens
- Pro TTS: $20/1M tokens

### Best Practices
1. Use `gemini-2.5-flash` for most tasks (best price/performance)
2. Use File API for files >20MB or repeated queries
3. Optimize media before upload (see `media_optimizer.py`)
4. Process specific segments instead of full videos
5. Use lower FPS for static content
6. Implement context caching for repeated queries
7. Batch process multiple files in parallel

## Rate Limits

**Free Tier**:
- 10-15 RPM (requests per minute)
- 1M-4M TPM (tokens per minute)
- 1,500 RPD (requests per day)

**YouTube Limits**:
- Free tier: 8 hours/day
- Paid tier: No length limits
- Public videos only

**Storage Limits**:
- 20GB per project
- 2GB per file
- 48-hour retention

## Error Handling

Common errors and solutions:
- **400**: Invalid format/size - validate before upload
- **401**: Invalid API key - check configuration
- **403**: Permission denied - verify API key restrictions
- **404**: File not found - ensure file uploaded and active
- **429**: Rate limit exceeded - implement exponential backoff
- **500**: Server error - retry with backoff

## Scripts Overview

All scripts support unified API key detection and error handling:

**gemini_batch_process.py**: Batch process multiple media files
- Supports all modalities (audio, image, video, PDF)
- Progress tracking and error recovery
- Output formats: JSON, Markdown, CSV
- Rate limiting and retry logic
- Dry-run mode

**media_optimizer.py**: Prepare media for Gemini API
- Compress videos/audio for size limits
- Resize images appropriately
- Split long videos into chunks
- Format conversion
- Quality vs size optimization

**document_converter.py**: Convert documents to PDF
- Convert DOCX, XLSX, PPTX to PDF
- Extract page ranges
- Optimize PDFs for Gemini
- Extract images from PDFs
- Batch conversion support

Run any script with `--help` for detailed usage.

## Resources

- [Audio API Docs](https://ai.google.dev/gemini-api/docs/audio)
- [Image API Docs](https://ai.google.dev/gemini-api/docs/image-understanding)
- [Video API Docs](https://ai.google.dev/gemini-api/docs/video-understanding)
- [Document API Docs](https://ai.google.dev/gemini-api/docs/document-processing)
- [Image Gen Docs](https://ai.google.dev/gemini-api/docs/image-generation)
- [Get API Key](https://aistudio.google.com/apikey)
- [Pricing](https://ai.google.dev/pricing)