Geminiのマルチモーダル動画理解で長編映像を分析する：アナリスト・リサーチャー向けタイムスタンプ付きイベント抽出ガイド

コンテンツアナリスト、UXリサーチャー、市場調査の専門家は、日々の業務で数時間に及ぶ膨大な録画データを取り扱っています。ユーザーテストの記録、フォーカスグループインタビュー、大学の講義、決算説明会、業界ウェビナーなど、その形態は多岐にわたります。従来、これら長編映像から構造化されたイベントログを抽出するには、音声認識（ASR）による書き起こし、スライド切り替えを検知する画像解析スクリプト、手作業によるタイムコード照合作業など、分断された複数のツールを組み合わせる必要がありました。

Google Geminiのネイティブマルチモーダル動画理解機能は、この分析フローを根本から刷新します。100万トークンを超える広大なコンテキストウィンドウと高度な音映像同期処理を備えたGeminiモデル（Gemini 3.8 Flash、Gemini 3.7 Flash、Gemini 2.5 Proなど）は、長時間の未加工動画ファイルを直接取り込むことが可能です。リサーチャーは自然言語によるプロンプトを通じて、発言内容と画面上の操作ログを突き合わせ、特定事象を迅速に特定し、高精度な MM:SS タイムスタンプを付与した構造化イベント要約を取得できます。

本記事では、GeminiのFiles APIを用いた大容量動画のアップロード方法、静的モードとエージェンティック（Agentic）モードの使い分け、JSONスキーマによる構造化出力の強制、そしてコンテキストキャッシュ（Context Caching）による反復分析コストとレイテンシの削減方法を網羅して解説します。

1. 処理モードの選定：静的処理 vs エージェンティック動画理解

Geminiには2つの動画処理モードが用意されています。トークン消費量、処理速度、分析精度のトレードオフを最適化するには、この選択が極めて重要です。

エージェンティックモードを選択すべき場面

15分を超える長編動画では、エージェンティックモード（"processing": "agentic"）の利用を強く推奨します。数万枚の静止画フレームを一括してコンテキストに投入すると、莫大なトークン費用が発生するだけでなく、不要な情報によってモデルの注意力（Attention）が希釈されがちです。エージェンティックモードでは、モデルがまず音声テキストを精査して関連時間帯を特定し、画面のクリック操作やホワイトボードの図解を確認する必要がある瞬間のみ高解像度フレームを取得します。これにより、トークンコストを最大66%削減しつつ、回答品質を約7%向上させることができます。

静的モードが必要となる場面

発話を伴わない純粋な視覚的挙動（被験者の視線移動、微細な表情の変化、無言でのUI試行錯誤など）を漏れなく追跡したい場合は、静的モードが適しています。静的モードではサンプリングレートをカスタマイズでき（例：fps: 0.5 で2秒に1フレーム取得）、100万トークンの枠内で最長3時間の観察記録全体を漏れなくカバーすることが可能です。

2. Files APIを用いた長編動画のアップロード

リクエスト内に直接動画データをインライン（base64）で埋め込む方式は、20MB（またはエンドポイントにより100MB）未満の小型ファイルに限定されます。本格的な調査録画を処理する際は、必ず Files API を使用します。Files APIは有料プランで最大20GB（無料プランで最大2GB）のファイルサイズをサポートし、MP4、MOV、MPEG、WEBM、AVIなど主要なコンテナ形式に対応しています。

取り込みは以下の2ステップで進行します：

1. レジューム対応アップロード： SDK経由で大容量動画を専用ストレージへ転送。
2. 状態のポーリング： サーバー側でのトランスコードとインデックス作成が完了し、ファイルステータスが PROCESSING から ACTIVE へ遷移するのを待機。

アップロードされたファイルは48時間保持され、その間の追加ストレージ料金は発生しません。同日中に複数の切り口から反復検証を行うリサーチ業務に最適です。

3. プロンプト設計とJSONスキーマによる構造化出力

モデルの出力をそのままデータベースやリサーチレポートに連携させるには、厳格なタイムスタンプ規約とスキーマ定義が不可欠です：

1. タイムコード形式の明示： Geminiは MM:SS 形式（長編映像では HH:MM:SS）を標準認識します。プロンプト内で「開始時刻と終了時刻を両方明記すること」を明確に指示します。
2. 音映像の相互検証： 音声と画面の突き合わせを指示します（例：「被験者が14分20秒時点で迷いを口にした際、画面上にエラーダイアログが表示されていたかを検証せよ」）。
3. JSONスキーマの強制： response_mime_type: "application/json" とPydanticスキーマを構成し、timestamp_start、timestamp_end、event_type、summary、visual_evidence、verbal_quote などの項目を過不足なく出力させます。無駄な挨拶文や前置きは完全に排除されます。
4. プロンプトの配置順： 入力コンテンツ配列を構築する際、テキストプロンプトは必ず動画オブジェクトの後方に配置してください。

4. Pythonによる実装コード

以下は、リサーチャーが60分のインタビュー動画をアップロードし、エージェンティックモードとサーバー側バックグラウンド非同期実行（Background Execution）を有効化して、構造化イベント要約を抽出する完全なスクリプトです：

import time
from google import genai
from google.genai import types
from pydantic import BaseModel, Field

# 1. クライアントの初期化
client = genai.Client()

# 2. Files APIによる大容量動画のアップロード
print("動画ファイルをアップロード中...")
video_file = client.files.upload(
    file="user_research_session_04.mp4",
    config={"mime_type": "video/mp4"}
)

# 3. サーバー側処理の完了を待機
while video_file.state.name == "PROCESSING":
    print("サーバーでトランスコードおよびインデックス処理中... 5秒後に再確認します")
    time.sleep(5)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
    raise RuntimeError("動画のサーバー処理に失敗しました。ファイル形式を確認してください。")

print(f"動画が利用可能になりました。URI: {video_file.uri}")

# 4. 構造化出力データモデルの定義
class VideoEvent(BaseModel):
    timestamp_start: str = Field(description="イベント開始時刻（MM:SS形式）")
    timestamp_end: str = Field(description="イベント終了時刻（MM:SS形式）")
    event_type: str = Field(description="分類：ペインポイント、機能要望、操作ミス、議論")
    summary: str = Field(description="発生事象の簡潔な要約")
    visual_evidence: str = Field(description="画面上で確認された視覚的根拠や操作ログ")
    verbal_quote: str = Field(description="発話された重要引用フレーズ")

class ResearchSummary(BaseModel):
    video_overview: str = Field(description="セッション全体のエグゼクティブサマリー")
    events: list[VideoEvent] = Field(description="時系列順に並んだ構造化イベント一覧")

# 5. エージェンティックモードとバックグラウンド実行による分析リクエスト
# background=True を指定することで長時間の推論に伴うネットワーク切断を防止
prompt_text = """
このユーザーインタビュー録画を分析してください。
被験者が直面したUIの摩擦、機能要望、意思決定の瞬間を漏れなく特定してください。
口頭でのコメントと画面上の操作を照合し、正確なMM:SS形式のタイムスタンプ付きで時系列順に出力してください。
"""

print("エージェンティック動画分析リクエストを送信中...")
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"  # エージェンティック探索を有効化
        },
        {
            "type": "text",
            "text": prompt_text
        }
    ],
    response_mime_type="application/json",
    response_schema=ResearchSummary,
    background=True  # サーバー側非同期実行
)

# 6. バックグラウンドタスクのポーリング
while interaction.status == "in_progress":
    print("モデルがタイムラインを探索し、証拠を統合中...")
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print("\n--- 抽出結果 ---")
print(interaction.output_text)

5. コンテキストキャッシュ（Context Caching）による反復調査の最適化

定性調査において、同じ動画に対して1回しか質問しないケースは極めて稀です。まず全体のアジェンダを把握し、続いて競合製品への言及、感情の変化、特定機能の操作導線などを繰り返し深掘りするのが一般的なリサーチ手順です。

毎回90分の動画全体を再送信すると、コストと待ち時間は跳ね上がります。Geminiのコンテキストキャッシュはこの課題を直接解決します：

• コスト大幅削減： キャッシュにヒットした入力トークン単価は、通常の10%〜20%程度に抑えられます。
• レイテンシ短縮： 音映像データがメモリ上で事前にトークン展開されているため、初回トークン生成時間が劇的に短縮されます。
• 実装手順： generateContent APIを使用して有効期限（TTL、例：2時間）付きのキャッシュオブジェクトを作成します。以降の分析クエリでは cachedContents/<cache-id> を指定するだけで、チーム全体で低コストかつ高速な質疑応答が可能になります。

6. 実務上の注意点とトラブルシューティング

• 通信タイムアウトの防止： 15分を超える長編動画に対する複雑な多段推論は完了まで数分を要することがあり、同期HTTP接続ではタイムアウトや認証失効（401 Unauthorized など）が発生するリスクがあります。Interactions APIでは必ず background=True を設定するか、generateContent APIでストリーミング（stream=True）を活用してください。
• エージェンティック探索の検証： レスポンスの interaction.steps を確認してください。processing_call や processing_result のログが存在していれば、モデルが静的全体像から推測したのではなく、動画内の特定区間をアクティブに読み込んだことが証明されます。
• 解像度パラメータの調整： スライド内の小さな文字やUIの数値、コード行を精緻に読み取る必要がある場合は media_resolution: "high" を設定します。全体の会議進行や大まかなデモの把握であれば、デフォルトの低解像度（1フレームあたり66トークン）で十分な精度と最高水準のコストパフォーマンスが得られます。
• タイムスタンプのズレ対策： 人間の発話タイミングと画面のUIレンダリングにはわずかなラグが生じます。プロンプトで単一の時点ではなく時間枠（timestamp_start と timestamp_end）を要求することで、後から動画編集ソフトで特定シーンへジャンプする際の精度が大幅に向上します。

参考文献

• Video understanding | Gemini API | Google AI for Developers
• Files API | Gemini API | Google AI for Developers
• Understand and count tokens | Gemini API | Google AI for Developers
• Context caching | Gemini API | Google AI for Developers
• Background execution | Gemini API | Google AI for Developers