ai-multimodal

AI マルチモーダル処理スキル

Google Gemini のマルチモーダル API を使用して、音声、画像、動画、ドキュメントを処理し、画像を生成します。あらゆるマルチメディアコンテンツの理解と生成に対応する統一インターフェースです。

主な機能

音声処理

• タイムスタンプ付き文字起こし（最大 9.5 時間）
• 音声の要約と分析
• 音声の理解と話者の識別
• 音楽と環境音の分析
• 音声を制御できる音声合成

画像理解

• 画像のキャプション生成と説明
• バウンディングボックス付き物体検出（2.0 以降）
• ピクセルレベルのセグメンテーション（2.5 以降）
• 視覚的な質問応答
• 複数画像の比較（最大 3,600 枚）
• OCR とテキスト抽出

動画分析

• シーン検出と要約
• 時間的な理解に基づく動画 Q&A
• 視覚的な説明付き文字起こし
• YouTube URL に対応
• 長時間動画の処理（最大 6 時間）
• フレーム単位の分析

ドキュメント抽出

• PDF のネイティブな視覚処理（最大 1,000 ページ）
• 表とフォームの抽出
• グラフと図の分析
• 複数ページのドキュメント理解
• 構造化データの出力（JSON スキーマ）
• 形式変換（PDF から HTML/JSON）

画像生成

• テキストからの画像生成
• 画像の編集と変更
• 複数画像の合成（最大 3 枚）
• 反復的な調整
• 複数のアスペクト比（1:1、16:9、9:16、4:3、3:4）
• スタイルと品質の制御

機能マトリックス

タスク	音声	画像	動画	ドキュメント	生成
文字起こし	✓	-	✓	-	-
要約	✓	✓	✓	✓	-
Q&A	✓	✓	✓	✓	-
物体検出	-	✓	✓	-	-
テキスト抽出	-	✓	-	✓	-
構造化出力	✓	✓	✓	✓	-
作成	TTS	-	-	-	✓
タイムスタンプ	✓	-	✓	-	-
セグメンテーション	-	✓	-	-	-

モデル選択ガイド

Gemini 2.5 シリーズ（推奨）

• gemini-2.5-pro：最高品質、すべての機能に対応、コンテキスト長 1M～2M
• gemini-2.5-flash：最適なバランス、すべての機能に対応、コンテキスト長 1M～2M
• gemini-2.5-flash-lite：軽量、セグメンテーションに対応
• gemini-2.5-flash-image：画像生成専用

Gemini 2.0 シリーズ

• gemini-2.0-flash：高速処理、物体検出
• gemini-2.0-flash-lite：軽量版

機能要件

• セグメンテーション：2.5 以降のモデルが必要です
• 物体検出：2.0 以降のモデルが必要です
• 複数動画：2.5 以降のモデルが必要です
• 画像生成：flash-image モデルが必要です

コンテキストウィンドウ

• 2M トークン：動画約 6 時間（低解像度）または約 2 時間（標準）
• 1M トークン：動画約 3 時間（低解像度）または約 1 時間（標準）
• 音声：32 トークン/秒（1 分 = 1,920 トークン）
• PDF：258 トークン/ページ（固定）
• 画像：サイズに応じて 258～1,548 トークン

クイックスタート

前提条件

API キーの設定：Google AI Studio と Vertex AI の両方に対応しています。

このスキルは、次の順序で GEMINI_API_KEY を確認します。

1. プロセス環境変数：export GEMINI_API_KEY="your-key"
2. プロジェクトのルート：.env
3. .claude/.env
4. .claude/skills/.env
5. .claude/skills/ai-multimodal/.env

API キーの取得：https://aistudio.google.com/apikey

Vertex AI の場合：

export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1  # Optional

SDK のインストール：

pip install google-genai python-dotenv pillow

よく使われるパターン

音声の文字起こし：

python scripts/gemini_batch_process.py \
  --files audio.mp3 \
  --task transcribe \
  --model gemini-2.5-flash

画像の分析：

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

動画の処理：

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

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

画像の生成：

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

メディアの最適化：

# 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

ドキュメントから 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

対応形式

音声

• WAV、MP3、AAC、FLAC、OGG Vorbis、AIFF
• リクエストごとに最大 9.5 時間
• 自動的に 16 Kbps のモノラルにダウンサンプリング

画像

• PNG、JPEG、WEBP、HEIC、HEIF
• リクエストごとに最大 3,600 枚
• 解像度：≤384px は 258 トークン、それより大きい場合はタイル分割

動画

• MP4、MPEG、MOV、AVI、FLV、MPG、WebM、WMV、3GPP
• 最大 6 時間（低解像度）または 2 時間（標準）
• YouTube URL に対応（一般公開されているもののみ）

ドキュメント

• ビジョン処理はPDFのみ
• 最大1,000ページ
• TXT、HTML、Markdownに対応（テキストのみ）

サイズ制限

• インライン：リクエスト全体で20MB未満
• File API：ファイルあたり2GB、プロジェクトのクォータは20GB
• 保持期間：48時間後に自動削除

リファレンスナビゲーション

詳しい実装ガイダンスについては、以下を参照してください。

音声処理

• references/audio-processing.md - 文字起こし、分析、TTS
  • タイムスタンプの処理とセグメント分析
  • 複数話者の識別
  • 非音声オーディオの分析
  • テキスト読み上げの生成

画像理解

• references/vision-understanding.md - キャプション生成、検出、OCR
  • オブジェクトの検出と位置特定
  • ピクセルレベルのセグメンテーション
  • 画像に関する質問応答
  • 複数画像の比較

動画分析

• references/video-analysis.md - シーン検出、時間的な理解
  • YouTube URLの処理
  • タイムスタンプに基づくクエリ
  • 動画のクリッピングとFPS制御
  • 長時間動画の最適化

ドキュメント抽出

• references/document-extraction.md - PDF処理、構造化出力
  • 表とフォームの抽出
  • グラフと図の分析
  • JSONスキーマの検証
  • 複数ページの処理

画像生成

• references/image-generation.md - テキストから画像生成、編集
  • プロンプトエンジニアリングの戦略
  • 画像の編集と構図
  • アスペクト比の選択
  • 安全設定

コストの最適化

トークン料金

入力料金：

• Gemini 2.5 Flash：入力100万トークンあたり$1.00、出力100万トークンあたり$0.10
• Gemini 2.5 Pro：入力100万トークンあたり$3.00、出力100万トークンあたり$12.00
• Gemini 1.5 Flash：入力100万トークンあたり$0.70、出力100万トークンあたり$0.175

トークンレート：

• 音声：毎秒32トークン（1分 = 1,920トークン）
• 動画：毎秒約300トークン（デフォルト）、または約100トークン（低解像度）
• PDF：1ページあたり258トークン（固定）
• 画像：サイズに応じて258～1,548トークン

TTS料金：

• Flash TTS：100万トークンあたり$10
• Pro TTS：100万トークンあたり$20

ベストプラクティス

1. ほとんどのタスクではgemini-2.5-flashを使用します（価格と性能のバランスが最良です）
2. 20MBを超えるファイルや、繰り返しクエリを行う場合はFile APIを使用します
3. アップロード前にメディアを最適化します（media_optimizer.pyを参照）
4. 動画全体ではなく、特定のセグメントを処理します
5. 動きの少ないコンテンツには低いFPSを使用します
6. 繰り返しクエリにはコンテキストキャッシュを実装します
7. 複数のファイルを並列でバッチ処理します

レート制限

無料枠：

• 10～15 RPM（1分あたりのリクエスト数）
• 100万～400万 TPM（1分あたりのトークン数）
• 1,500 RPD（1日あたりのリクエスト数）

YouTubeの制限：

• 無料枠：1日8時間
• 有料枠：長さの制限なし
• 公開動画のみ

ストレージ制限：

• プロジェクトあたり20GB
• ファイルあたり2GB
• 保持期間は48時間

エラー処理

よくあるエラーと解決方法：

• 400：無効な形式またはサイズ — アップロード前に検証します
• 401：無効なAPIキー — 設定を確認します
• 403：アクセス拒否 — APIキーの制限を確認します
• 404：ファイルが見つからない — ファイルがアップロード済みで、有効であることを確認します
• 429：レート制限超過 — 指数バックオフを実装します
• 500：サーバーエラー — バックオフを使って再試行します

スクリプトの概要

すべてのスクリプトは、統一されたAPIキーの検出とエラー処理に対応しています。

gemini_batch_process.py：複数のメディアファイルをバッチ処理します

• すべてのモダリティ（音声、画像、動画、PDF）に対応
• 進行状況の追跡とエラー復旧
• 出力形式：JSON、Markdown、CSV
• レート制限と再試行ロジック
• ドライランモード

media_optimizer.py：Gemini API用にメディアを準備します

• サイズ制限に合わせて動画や音声を圧縮
• 画像を適切なサイズに変更
• 長い動画をチャンクに分割
• 形式の変換
• 品質とサイズの最適化

document_converter.py：ドキュメントをPDFに変換します

• DOCX、XLSX、PPTXをPDFに変換
• ページ範囲を抽出
• Gemini向けにPDFを最適化
• PDFから画像を抽出
• バッチ変換に対応

詳しい使い方を確認するには、各スクリプトを--help付きで実行してください。

Resources

• Audio API Docs
• Image API Docs
• Video API Docs
• Document API Docs
• Image Gen Docs
• Get API Key
• Pricing