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 |
Y |
- |
Y |
- |
- |
| Summarization |
Y |
Y |
Y |
Y |
- |
| Q&A |
Y |
Y |
Y |
Y |
- |
| Object Detection |
- |
Y |
Y |
- |
- |
| Text Extraction |
- |
Y |
- |
Y |
- |
| Structured Output |
Y |
Y |
Y |
Y |
- |
| Creation |
TTS |
- |
- |
- |
Y |
| Timestamps |
Y |
- |
Y |
- |
- |
| Segmentation |
- |
Y |
- |
- |
- |
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:
Install SDK:
Common Patterns
Transcribe Audio:
Analyze Image:
Process Video:
Extract from PDF:
Generate Image:
Optimize Media:
Batch optimize multiple files
python scripts/media_optimizer.py
--input-dir ./videos
--output-dir docs/assets/optimized
--quality 85
Convert Documents to Markdown:
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)
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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: ai-multimodal-23description: 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. Use when this capability is needed.4---56# 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 | Y | - | Y | - | - |56| Summarization | Y | Y | Y | Y | - |57| Q&A | Y | Y | Y | Y | - |58| Object Detection | - | Y | Y | - | - |59| Text Extraction | - | Y | - | Y | - |60| Structured Output | Y | Y | Y | Y | - |61| Creation | TTS | - | - | - | Y |62| Timestamps | Y | - | Y | - | - |63| Segmentation | - | Y | - | - | - |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**:106107<example type="usage">108<code language="bash">109export GEMINI_USE_VERTEX=true110export VERTEX_PROJECT_ID=your-gcp-project-id111export VERTEX_LOCATION=us-central1 # Optional112</code>113</example>114115**Install SDK**:116117<example type="usage">118<code language="bash">119pip install google-genai python-dotenv pillow120</code>121</example>122123### Common Patterns124125**Transcribe Audio**:126127<example type="usage">128<code language="bash">129python scripts/gemini_batch_process.py \130 --files audio.mp3 \131 --task transcribe \132 --model gemini-2.5-flash133</code>134</example>135136**Analyze Image**:137138<example type="usage">139<code language="bash">140python scripts/gemini_batch_process.py \141 --files image.jpg \142 --task analyze \143 --prompt "Describe this image" \144 --output docs/assets/<output-name>.md \145 --model gemini-2.5-flash146</code>147</example>148149**Process Video**:150151<example type="usage">152<code language="bash">153python scripts/gemini_batch_process.py \154 --files video.mp4 \155 --task analyze \156 --prompt "Summarize key points with timestamps" \157 --output docs/assets/<output-name>.md \158 --model gemini-2.5-flash159</code>160</example>161162**Extract from PDF**:163164<example type="usage">165<code language="bash">166python scripts/gemini_batch_process.py \167 --files document.pdf \168 --task extract \169 --prompt "Extract table data as JSON" \170 --output docs/assets/<output-name>.md \171 --format json172</code>173</example>174175**Generate Image**:176177<example type="usage">178<code language="bash">179python scripts/gemini_batch_process.py \180 --task generate \181 --prompt "A futuristic city at sunset" \182 --output docs/assets/<output-file-name> \183 --model gemini-2.5-flash-image \184 --aspect-ratio 16:9185</code>186</example>187188**Optimize Media**:189190<example type="usage">191<code language="bash">192# Prepare large video for processing193python scripts/media_optimizer.py \194 --input large-video.mp4 \195 --output docs/assets/<output-file-name> \196 --target-size 100MB197198# Batch optimize multiple files199python scripts/media_optimizer.py \200 --input-dir ./videos \201 --output-dir docs/assets/optimized \202 --quality 85203</code>204</example>205206**Convert Documents to Markdown**:207208<example type="usage">209<code language="bash">210# Convert to PDF211python scripts/document_converter.py \212 --input document.docx \213 --output docs/assets/document.md214215# Extract pages216python scripts/document_converter.py \217 --input large.pdf \218 --output docs/assets/chapter1.md \219 --pages 1-20220</code>221</example>222223## Supported Formats224225### Audio226- WAV, MP3, AAC, FLAC, OGG Vorbis, AIFF227- Max 9.5 hours per request228- Auto-downsampled to 16 Kbps mono229230### Images231- PNG, JPEG, WEBP, HEIC, HEIF232- Max 3,600 images per request233- Resolution: <=384px = 258 tokens, larger = tiled234235### Video236- MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV, 3GPP237- Max 6 hours (low-res) or 2 hours (default)238- YouTube URLs supported (public only)239240### Documents241- PDF only for vision processing242- Max 1,000 pages243- TXT, HTML, Markdown supported (text-only)244245<constraints>246<constraint severity="critical">API key must be kept secure - never commit to version control</constraint>247<constraint severity="high">File size limit: 20MB inline, 2GB via File API</constraint>248<constraint severity="high">YouTube processing limited to public videos only</constraint>249<constraint severity="medium">Free tier rate limit: 10-15 requests per minute</constraint>250<constraint severity="medium">Files uploaded via File API are auto-deleted after 48 hours</constraint>251<constraint severity="low">Image generation requires specific flash-image model</constraint>252</constraints>253254## Reference Navigation255256For detailed implementation guidance, see:257258### Audio Processing259- `references/audio-processing.md` - Transcription, analysis, TTS260 - Timestamp handling and segment analysis261 - Multi-speaker identification262 - Non-speech audio analysis263 - Text-to-speech generation264265### Image Understanding266- `references/vision-understanding.md` - Captioning, detection, OCR267 - Object detection and localization268 - Pixel-level segmentation269 - Visual question answering270 - Multi-image comparison271272### Video Analysis273- `references/video-analysis.md` - Scene detection, temporal understanding274 - YouTube URL processing275 - Timestamp-based queries276 - Video clipping and FPS control277 - Long video optimization278279### Document Extraction280- `references/document-extraction.md` - PDF processing, structured output281 - Table and form extraction282 - Chart and diagram analysis283 - JSON schema validation284 - Multi-page handling285286### Image Generation287- `references/image-generation.md` - Text-to-image, editing288 - Prompt engineering strategies289 - Image editing and composition290 - Aspect ratio selection291 - Safety settings292293## Cost Optimization294295### Token Costs296**Input Pricing**:297- Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output298- Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output299- Gemini 1.5 Flash: $0.70/1M input, $0.175/1M output300301**Token Rates**:302- Audio: 32 tokens/second (1 min = 1,920 tokens)303- Video: ~300 tokens/second (default) or ~100 (low-res)304- PDF: 258 tokens/page (fixed)305- Image: 258-1,548 tokens based on size306307**TTS Pricing**:308- Flash TTS: $10/1M tokens309- Pro TTS: $20/1M tokens310311### Best Practices3121. Use `gemini-2.5-flash` for most tasks (best price/performance)3132. Use File API for files >20MB or repeated queries3143. Optimize media before upload (see `media_optimizer.py`)3154. Process specific segments instead of full videos3165. Use lower FPS for static content3176. Implement context caching for repeated queries3187. Batch process multiple files in parallel319320## Rate Limits321322**Free Tier**:323- 10-15 RPM (requests per minute)324- 1M-4M TPM (tokens per minute)325- 1,500 RPD (requests per day)326327**YouTube Limits**:328- Free tier: 8 hours/day329- Paid tier: No length limits330- Public videos only331332**Storage Limits**:333- 20GB per project334- 2GB per file335- 48-hour retention336337## Error Handling338339Common errors and solutions:340- **400**: Invalid format/size - validate before upload341- **401**: Invalid API key - check configuration342- **403**: Permission denied - verify API key restrictions343- **404**: File not found - ensure file uploaded and active344- **429**: Rate limit exceeded - implement exponential backoff345- **500**: Server error - retry with backoff346347## Scripts Overview348349All scripts support unified API key detection and error handling:350351**gemini_batch_process.py**: Batch process multiple media files352- Supports all modalities (audio, image, video, PDF)353- Progress tracking and error recovery354- Output formats: JSON, Markdown, CSV355- Rate limiting and retry logic356- Dry-run mode357358**media_optimizer.py**: Prepare media for Gemini API359- Compress videos/audio for size limits360- Resize images appropriately361- Split long videos into chunks362- Format conversion363- Quality vs size optimization364365**document_converter.py**: Convert documents to PDF366- Convert DOCX, XLSX, PPTX to PDF367- Extract page ranges368- Optimize PDFs for Gemini369- Extract images from PDFs370- Batch conversion support371372Run any script with `--help` for detailed usage.373374## Resources375376- [Audio API Docs](https://ai.google.dev/gemini-api/docs/audio)377- [Image API Docs](https://ai.google.dev/gemini-api/docs/image-understanding)378- [Video API Docs](https://ai.google.dev/gemini-api/docs/video-understanding)379- [Document API Docs](https://ai.google.dev/gemini-api/docs/document-processing)380- [Image Gen Docs](https://ai.google.dev/gemini-api/docs/image-generation)381- [Get API Key](https://aistudio.google.com/apikey)382- [Pricing](https://ai.google.dev/pricing)383384---385> Converted and distributed by [TomeVault](https://tomevault.io/claim/zircote) — claim your Tome and manage your conversions.386<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io