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:
- Process environment:
export GEMINI_API_KEY="your-key"
- Project root:
.env
.claude/.env.claude/skills/.env.claude/skills/ai-multimodal/.env
Get API key: https://aistudio.google.com/apikey
For Vertex AI:
export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1 # Optional
Install SDK:
pip install google-genai python-dotenv pillow
Common Patterns
Transcribe Audio:
python scripts/gemini_batch_process.py \
--files audio.mp3 \
--task transcribe \
--model gemini-2.5-flash
Analyze Image:
python scripts/gemini_batch_process.py \
--files image.jpg \
--task analyze \
--prompt "Describe this image" \
--output docs/assets/<output-name>.md \
--model gemini-2.5-flash
Process Video:
python scripts/gemini_batch_process.py \
--files video.mp4 \
--task analyze \
--prompt "Summarize key points with timestamps" \
--output docs/assets/<output-name>.md \
--model gemini-2.5-flash
Extract from PDF:
python scripts/gemini_batch_process.py \
--files document.pdf \
--task extract \
--prompt "Extract table data as JSON" \
--output docs/assets/<output-name>.md \
--format json
Generate Image:
python scripts/gemini_batch_process.py \
--task generate \
--prompt "A futuristic city at sunset" \
--output docs/assets/<output-file-name> \
--model gemini-2.5-flash-image \
--aspect-ratio 16:9
Optimize Media:
# Prepare large video for processing
python scripts/media_optimizer.py \
--input large-video.mp4 \
--output docs/assets/<output-file-name> \
--target-size 100MB
# Batch optimize multiple files
python scripts/media_optimizer.py \
--input-dir ./videos \
--output-dir docs/assets/optimized \
--quality 85
Convert Documents to Markdown:
# Convert to PDF
python scripts/document_converter.py \
--input document.docx \
--output docs/assets/document.md
# Extract pages
python scripts/document_converter.py \
--input large.pdf \
--output docs/assets/chapter1.md \
--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
- Use
gemini-2.5-flash for most tasks (best price/performance)
- Use File API for files >20MB or repeated queries
- Optimize media before upload (see
media_optimizer.py)
- Process specific segments instead of full videos
- Use lower FPS for static content
- Implement context caching for repeated queries
- 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
When to Use
Process and generate multimedia content using Google Gemini API.
Covers: AI Multimodal Processing Skill, Core Capabilities, Audio Processing, Image Understanding, Video Analysis.
1---2name: ai-multimodal3description: 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), pr...4license: MIT5---6# AI Multimodal Processing Skill78Process audio, images, videos, documents, and generate images using Google Gemini's multimodal API. Unified interface for all multimedia content understanding and generation.910## Core Capabilities1112### Audio Processing13- Transcription with timestamps (up to 9.5 hours)14- Audio summarization and analysis15- Speech understanding and speaker identification16- Music and environmental sound analysis17- Text-to-speech generation with controllable voice1819### Image Understanding20- Image captioning and description21- Object detection with bounding boxes (2.0+)22- Pixel-level segmentation (2.5+)23- Visual question answering24- Multi-image comparison (up to 3,600 images)25- OCR and text extraction2627### Video Analysis28- Scene detection and summarization29- Video Q&A with temporal understanding30- Transcription with visual descriptions31- YouTube URL support32- Long video processing (up to 6 hours)33- Frame-level analysis3435### Document Extraction36- Native PDF vision processing (up to 1,000 pages)37- Table and form extraction38- Chart and diagram analysis39- Multi-page document understanding40- Structured data output (JSON schema)41- Format conversion (PDF to HTML/JSON)4243### Image Generation44- Text-to-image generation45- Image editing and modification46- Multi-image composition (up to 3 images)47- Iterative refinement48- Multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)49- Controllable style and quality5051## Capability Matrix5253| Task | Audio | Image | Video | Document | Generation |54|------|:-----:|:-----:|:-----:|:--------:|:----------:|55| Transcription | ✓ | - | ✓ | - | - |56| Summarization | ✓ | ✓ | ✓ | ✓ | - |57| Q&A | ✓ | ✓ | ✓ | ✓ | - |58| Object Detection | - | ✓ | ✓ | - | - |59| Text Extraction | - | ✓ | - | ✓ | - |60| Structured Output | ✓ | ✓ | ✓ | ✓ | - |61| Creation | TTS | - | - | - | ✓ |62| Timestamps | ✓ | - | ✓ | - | - |63| Segmentation | - | ✓ | - | - | - |6465## Model Selection Guide6667### Gemini 2.5 Series (Recommended)68- **gemini-2.5-pro**: Highest quality, all features, 1M-2M context69- **gemini-2.5-flash**: Best balance, all features, 1M-2M context70- **gemini-2.5-flash-lite**: Lightweight, segmentation support71- **gemini-2.5-flash-image**: Image generation only7273### Gemini 2.0 Series74- **gemini-2.0-flash**: Fast processing, object detection75- **gemini-2.0-flash-lite**: Lightweight option7677### Feature Requirements78- **Segmentation**: Requires 2.5+ models79- **Object Detection**: Requires 2.0+ models80- **Multi-video**: Requires 2.5+ models81- **Image Generation**: Requires flash-image model8283### Context Windows84- **2M tokens**: ~6 hours video (low-res) or ~2 hours (default)85- **1M tokens**: ~3 hours video (low-res) or ~1 hour (default)86- **Audio**: 32 tokens/second (1 min = 1,920 tokens)87- **PDF**: 258 tokens/page (fixed)88- **Image**: 258-1,548 tokens based on size8990## Quick Start9192### Prerequisites9394**API Key Setup**: Supports both Google AI Studio and Vertex AI.9596The skill checks for `GEMINI_API_KEY` in this order:971. Process environment: `export GEMINI_API_KEY="your-key"`982. Project root: `.env`993. `.claude/.env`1004. `.claude/skills/.env`1015. `.claude/skills/ai-multimodal/.env`102103**Get API key**: https://aistudio.google.com/apikey104105**For Vertex AI**:106```bash107export GEMINI_USE_VERTEX=true108export VERTEX_PROJECT_ID=your-gcp-project-id109export VERTEX_LOCATION=us-central1 # Optional110```111112**Install SDK**:113```bash114pip install google-genai python-dotenv pillow115```116117### Common Patterns118119**Transcribe Audio**:120```bash121python scripts/gemini_batch_process.py \122 --files audio.mp3 \123 --task transcribe \124 --model gemini-2.5-flash125```126127**Analyze Image**:128```bash129python scripts/gemini_batch_process.py \130 --files image.jpg \131 --task analyze \132 --prompt "Describe this image" \133 --output docs/assets/<output-name>.md \134 --model gemini-2.5-flash135```136137**Process Video**:138```bash139python scripts/gemini_batch_process.py \140 --files video.mp4 \141 --task analyze \142 --prompt "Summarize key points with timestamps" \143 --output docs/assets/<output-name>.md \144 --model gemini-2.5-flash145```146147**Extract from PDF**:148```bash149python scripts/gemini_batch_process.py \150 --files document.pdf \151 --task extract \152 --prompt "Extract table data as JSON" \153 --output docs/assets/<output-name>.md \154 --format json155```156157**Generate Image**:158```bash159python scripts/gemini_batch_process.py \160 --task generate \161 --prompt "A futuristic city at sunset" \162 --output docs/assets/<output-file-name> \163 --model gemini-2.5-flash-image \164 --aspect-ratio 16:9165```166167**Optimize Media**:168```bash169# Prepare large video for processing170python scripts/media_optimizer.py \171 --input large-video.mp4 \172 --output docs/assets/<output-file-name> \173 --target-size 100MB174175# Batch optimize multiple files176python scripts/media_optimizer.py \177 --input-dir ./videos \178 --output-dir docs/assets/optimized \179 --quality 85180```181182**Convert Documents to Markdown**:183```bash184# Convert to PDF185python scripts/document_converter.py \186 --input document.docx \187 --output docs/assets/document.md188189# Extract pages190python scripts/document_converter.py \191 --input large.pdf \192 --output docs/assets/chapter1.md \193 --pages 1-20194```195196## Supported Formats197198### Audio199- WAV, MP3, AAC, FLAC, OGG Vorbis, AIFF200- Max 9.5 hours per request201- Auto-downsampled to 16 Kbps mono202203### Images204- PNG, JPEG, WEBP, HEIC, HEIF205- Max 3,600 images per request206- Resolution: ≤384px = 258 tokens, larger = tiled207208### Video209- MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP210- Max 6 hours (low-res) or 2 hours (default)211- YouTube URLs supported (public only)212213### Documents214- PDF only for vision processing215- Max 1,000 pages216- TXT, HTML, Markdown supported (text-only)217218### Size Limits219- **Inline**: <20MB total request220- **File API**: 2GB per file, 20GB project quota221- **Retention**: 48 hours auto-delete222223## Reference Navigation224225For detailed implementation guidance, see:226227### Audio Processing228- `references/audio-processing.md` - Transcription, analysis, TTS229 - Timestamp handling and segment analysis230 - Multi-speaker identification231 - Non-speech audio analysis232 - Text-to-speech generation233234### Image Understanding235- `references/vision-understanding.md` - Captioning, detection, OCR236 - Object detection and localization237 - Pixel-level segmentation238 - Visual question answering239 - Multi-image comparison240241### Video Analysis242- `references/video-analysis.md` - Scene detection, temporal understanding243 - YouTube URL processing244 - Timestamp-based queries245 - Video clipping and FPS control246 - Long video optimization247248### Document Extraction249- `references/document-extraction.md` - PDF processing, structured output250 - Table and form extraction251 - Chart and diagram analysis252 - JSON schema validation253 - Multi-page handling254255### Image Generation256- `references/image-generation.md` - Text-to-image, editing257 - Prompt engineering strategies258 - Image editing and composition259 - Aspect ratio selection260 - Safety settings261262## Cost Optimization263264### Token Costs265**Input Pricing**:266- Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output267- Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output268- Gemini 1.5 Flash: $0.70/1M input, $0.175/1M output269270**Token Rates**:271- Audio: 32 tokens/second (1 min = 1,920 tokens)272- Video: ~300 tokens/second (default) or ~100 (low-res)273- PDF: 258 tokens/page (fixed)274- Image: 258-1,548 tokens based on size275276**TTS Pricing**:277- Flash TTS: $10/1M tokens278- Pro TTS: $20/1M tokens279280### Best Practices2811. Use `gemini-2.5-flash` for most tasks (best price/performance)2822. Use File API for files >20MB or repeated queries2833. Optimize media before upload (see `media_optimizer.py`)2844. Process specific segments instead of full videos2855. Use lower FPS for static content2866. Implement context caching for repeated queries2877. Batch process multiple files in parallel288289## Rate Limits290291**Free Tier**:292- 10-15 RPM (requests per minute)293- 1M-4M TPM (tokens per minute)294- 1,500 RPD (requests per day)295296**YouTube Limits**:297- Free tier: 8 hours/day298- Paid tier: No length limits299- Public videos only300301**Storage Limits**:302- 20GB per project303- 2GB per file304- 48-hour retention305306## Error Handling307308Common errors and solutions:309- **400**: Invalid format/size - validate before upload310- **401**: Invalid API key - check configuration311- **403**: Permission denied - verify API key restrictions312- **404**: File not found - ensure file uploaded and active313- **429**: Rate limit exceeded - implement exponential backoff314- **500**: Server error - retry with backoff315316## Scripts Overview317318All scripts support unified API key detection and error handling:319320**gemini_batch_process.py**: Batch process multiple media files321- Supports all modalities (audio, image, video, PDF)322- Progress tracking and error recovery323- Output formats: JSON, Markdown, CSV324- Rate limiting and retry logic325- Dry-run mode326327**media_optimizer.py**: Prepare media for Gemini API328- Compress videos/audio for size limits329- Resize images appropriately330- Split long videos into chunks331- Format conversion332- Quality vs size optimization333334**document_converter.py**: Convert documents to PDF335- Convert DOCX, XLSX, PPTX to PDF336- Extract page ranges337- Optimize PDFs for Gemini338- Extract images from PDFs339- Batch conversion support340341Run any script with `--help` for detailed usage.342343## Resources344345- [Audio API Docs](https://ai.google.dev/gemini-api/docs/audio)346- [Image API Docs](https://ai.google.dev/gemini-api/docs/image-understanding)347- [Video API Docs](https://ai.google.dev/gemini-api/docs/video-understanding)348- [Document API Docs](https://ai.google.dev/gemini-api/docs/document-processing)349- [Image Gen Docs](https://ai.google.dev/gemini-api/docs/image-generation)350- [Get API Key](https://aistudio.google.com/apikey)351- [Pricing](https://ai.google.dev/pricing)352353## When to Use354355Process and generate multimedia content using Google Gemini API.356357Covers: AI Multimodal Processing Skill, Core Capabilities, Audio Processing, Image Understanding, Video Analysis.
JantonioFC