Gemini Agentic Video Understanding APIガイド

2時間の講義動画と20秒の商品クリップを、同じ手順で調べる必要はありません。長尺動画から特定の場面を探す質問には、Geminiの新しいagentic video understandingモードが有力な出発点になります。一方で、Googleが掲げる「最大」の削減率はベンチマーク上の結果であり、すべてのAPI利用料金が必ず66%下がるという意味ではありません。

動画の長さではなく、やりたいことから処理モードを選ぶ

Gemini agentic video understandingは、特定の瞬間を見つけたり、該当場面をあらためて確認したりする質問に向いています。短い動画を素早く返したい場合や、サンプリングした全区間を均一にカバーしたい場合は、static処理のほうがシンプルです。

Googleがローンチ時に挙げたユースケースは4つです。サブ秒単位の場面検索、長尺動画における「干し草の山から針を探す」検索、異常検知、そして動作や物体のカウントです。公式発表では、10分のハウツー動画から90分の講義、数時間に及ぶ録画までを例として紹介しています。

公表されている動画時間の明確な境界はありません。たとえば5分の動画でも、見つけにくいイベントが1つ含まれていればagentic処理を選ぶ理由になります。反対に、より長い録画でも内容が均一なら、必ずしもそうとは限りません。

同じ機能でもAPIリクエストの形は2種類ある

「Agentic」は、どのAPIでも共通のJSONフィールド1つで有効化するものではありません。Googleのローンチ例ではInteractions APIを使い、動画入力内にprocessing: "agentic"を指定しています。一方、GenerateContentではメディアパート側で処理方法を設定します。

Interactions APIでは動画入力にprocessingを指定する

Googleのローンチ記事では、YouTube動画に対して次のPythonパターンを示しています。

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

この設定は、無関係なトップレベルのフィールドではなく、動画オブジェクトに置きます。

GenerateContentではメディアパートに処理設定を置く

Geminiの動画理解ドキュメントでは、GenerateContentの形式を別途説明しています。このリクエスト形式では、メディア入力にmedia_processing: "AGENTIC"を指定します。JavaScriptでは、対応するキャメルケースのプロパティmediaProcessingを使用します。

最小限のPython例は次のとおりです。

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

ローカル動画を使う場合は、YOUR_VIDEO_FILE_URIをGeminiのファイルアップロードフローで返されるURIに置き換え、メディアパートを送信する前にファイルの準備完了を待ちます。導入済みクライアントのバージョンに対応したSDKの詳細は、最新の公式動画理解ガイドで確認してください。

client.interactions.createからgenerateContentへ移行する際、コード断片をそのまま入れ替えてはいけません。

agentic video understandingは実際に何をするのか

static動画処理では、一定のフレームレートで動画をサンプリングします。Googleによると、デフォルトは毎秒1フレームで、APIを通じてレートを調整できます。取得されたフレームをモデルが解析する仕組みです。

agenticワークフローでは、録画全体を均一に読み込むのではなく、Geminiがタイムラインを検索・走査し、適切な速度を選び、映像フレーム、音声、文字起こしを利用します。

1. 質問に関係するセグメントまたはモダリティをリクエストする。
2. 返されたフレーム、音声、文字起こしを確認する。
3. より高い時間精度が必要なら、さらに狭い区間を再確認する。

staticサンプリングでは、開発者が明快なカバレッジのルールを持てます。agentic処理では、どこを見るかの判断をモデルにより多く委ねます。本番システムでは、代表的な映像を使ってタイムスタンプやカウントを検証すべきです。

「最大66%削減」は66%割引ではない

Googleは標準的な動画分析ベンチマークにおいて、以下の結果を報告しています。特に長尺動画での効果を強調しています。

Googleのローンチ発表によれば、agentic video understandingには通常のGemini APIトークン料金が適用され、この機能に追加料金はかかりません。ただし、実際のコストはモデル、取得されるコンテンツ、リクエスト、出力に左右されます。トークンとモデルの料金をより広く確認したい場合は、Gemini 3.7 Flash API pricing guideを参照してください。

同じ録画に対して繰り返し質問するなら、APIワークフローで対応している場合は動画コンテキストをキャッシュしてください。Google Cloudの実践的な動画分析ノートでも、繰り返し分析における重要なコスト削減手段としてコンテキストキャッシュが挙げられています。

提供状況とロールアウトの範囲

agentic video understandingは、個別に発表された動画モデルではなく、3つのFlash系モデルにまたがる処理機能です。Googleは、2026年9月1日に以下のモデルと提供先でローンチしたとしています。

一般向けGeminiとYouTube向けの展開予定は、すべてのアカウントで現在利用できることを意味するものではありません。

デフォルト切り替え前に行う4項目の本番テスト

ローンチ発表は機能の主張を示していますが、手元の動画でこのモードがどう振る舞うかまでは教えてくれません。既存のstaticワークフローを置き換える前に、小規模な評価セットを用意しましょう。

1. タイムスタンプの取得: シーン切り替え、短時間だけ映る対象、開始・終了時刻の正確さが重要なイベントを含むクリップを使います。返されたタイムスタンプを、人手で確認した正解データと比較してください。
2. 高速な動作のカウント: 繰り返し動く対象や、フレームを横切る物体を含む映像を使います。合計数だけでなく、回答がカウント対象の時間範囲を説明しているかも確認します。
3. 音声と文字起こしへのグラウンディング: 発話内容と画面上の動作が異なる質問をします。回答が一方のモダリティをもう一方に黙って置き換えていないことを検証してください。
4. 運用上の挙動: 同じファイルを両モードで実行し、入力・出力トークン、実時間のレイテンシ、リトライ、空の回答、見逃したイベント、staticフォールバックの結果を記録します。選択的取得で根拠を見逃す場合や、許容できない遅延が加わる場合は、フォールバックを残してください。

ローンチ記事を根拠に、「X分を超えたらagenticを使う」という固定ルールを作るべきではありません。公表されている内容が支持しているのはタスクベースの選択であり、普遍的な動画時間のしきい値ではありません。

Gemini agentic video understanding APIのFAQ

agentic video understandingは新しいGeminiモデルですか？

いいえ。Googleはこれを、Gemini 3.7 Flash、Gemini 3.6 Flash、Gemini 3.5 Flash-Liteで利用できる動画理解機能として位置付けています。

YouTube URLではなく、アップロードした動画も使えますか？

はい。Googleは、アップロードした動画ファイルとYouTube動画を対応API入力として挙げています。ローカルファイルの場合は、まずアップロードし、処理の準備が完了してから返されたファイルURIをメディアパートに渡します。

agentic動画処理には追加料金がかかりますか？

Googleによると、追加の機能料金はありません。通常のGemini APIトークン料金が適用され、最終的な請求額は取得されるコンテンツとリクエストの残りの部分によって決まります。

代表的な動画セットを両モードで実行し、測定した根拠の品質とトークンコストがアプリケーションの目標に合う場合に限り、agentic処理をデフォルトとして採用してください。