ai-multimodal

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

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

主な機能

音声処理

• タイムスタンプ付きの文字起こし（最大 9.5 時間）
• 音声の要約と分析
• 音声理解と話者識別
• 音楽と環境音の分析
• 音声を調整可能なボイスで生成

画像理解

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

動画分析

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

ドキュメント抽出

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

画像生成

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

機能マトリックス

タスク	音声	画像	動画	ドキュメント	生成
文字起こし	✓	-	✓	-	-
要約	✓	✓	✓	✓	-
質問応答	✓	✓	✓	✓	-
物体検出	-	✓	✓	-	-
テキスト抽出	-	✓	-	✓	-
構造化出力	✓	✓	✓	✓	-
作成	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：1 ページあたり 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" \
  --model gemini-2.5-flash

動画の処理：

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

PDF からの抽出：

python scripts/gemini_batch_process.py \
  --files document.pdf \
  --task extract \
  --prompt "Extract table data as JSON" \
  --format json

画像の生成：

python scripts/gemini_batch_process.py \
  --task generate \
  --prompt "A futuristic city at sunset" \
  --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 optimized-video.mp4 \
  --target-size 100MB

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

ドキュメントの変換：

# 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

対応形式

音声

• 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：1ファイルあたり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

トークンレート：

• 音声：1 秒あたり 32 トークン（1 分 = 1,920 トークン）
• 動画：1 秒あたり約 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
• 1 ファイルあたり 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