Gemini Agentic Video Understanding API 實戰指南

兩小時的課程影片，和只有 20 秒的產品短片，本來就不該用同一套方式分析。若問題是要從長片中找特定片段，或反覆追查某個時間點，Gemini 新推出的 agentic video understanding 是較合適的起點；但 Google 所說的「最高」節省幅度來自基準測試，並不代表每一筆 API 帳單都一定能少 66%。

該看任務需求，不是影片長度來選模式

Gemini agentic video understanding 適合用來尋找或回看特定時刻。若影片很短、回應速度優先，或你必須以一致方式覆蓋每個取樣區間，static 處理仍是更單純的選項。

Google 在推出時列出四種使用情境：次秒級瞬間檢索、長片中的「大海撈針」搜尋、異常偵測，以及動作或物件計數。官方公告舉出的範例，涵蓋 10 分鐘教學影片、90 分鐘講座與長達數小時的錄影。

目前沒有公開的影片長度分界。一支 5 分鐘影片只要藏著一個關鍵事件，就可能值得使用 agentic 處理；反過來說，內容均一的長影片未必需要。

同一項功能，API 請求格式有兩種

「Agentic」不是通用的單一 JSON 欄位。Google 的發布範例採用 Interactions API，將 processing: "agentic" 放在影片輸入內；GenerateContent 則是在媒體 part 上設定媒體處理方式。

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：在媒體 part 設定 media processing

Gemini video-understanding 文件另外說明了 GenerateContent 的格式。在這種請求結構中，媒體輸入使用 media_processing: "AGENTIC"；JavaScript 則使用對應的 camelCase 屬性 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，並在傳送媒體 part 前確認檔案已準備完成。你安裝的 client 版本可能有所不同，SDK 細節請以最新的官方 video-understanding 指南為準。

從 client.interactions.create 遷移到 generateContent 時，不要直接互換兩種範例程式碼。

Agentic video understanding 實際怎麼分析影片

Static 影片處理會以固定幀率取樣。Google 表示預設值是每秒 1 幀，並可透過 API 調整取樣速率，再將取樣畫面交給模型分析。

Agentic 工作流程讓 Gemini 能搜尋與掃描時間軸，自行選擇合適速度，並根據視覺影格、音訊或逐字稿取得資訊，而不是平均載入整段影片：

1. 要求取得與問題相關的片段或模態資料。
2. 檢視回傳的畫面、音訊或逐字稿。
3. 當需要更精確的時間判斷時，再回看更窄的時間區間。

Static 取樣讓開發者能採用明確的覆蓋規則；agentic 處理則把更多「該看哪裡」的判斷交給模型。因此在正式環境中，應以具代表性的影片驗證時間戳與計數結果。

所謂節省，不等於固定打 66 折

Google 根據標準影片分析基準測試公布以下結果，且特別強調長影片的提升幅度：

依 Google 的發布公告，agentic video understanding 採用標準 Gemini API token 定價，沒有額外功能費用。實際成本仍取決於模型、擷取內容、請求本身與輸出內容。如需了解更完整的 token 與模型定價背景，可參考 Gemini 3.7 Flash API pricing guide。

如果需要對同一份錄影反覆提問，請在 API 工作流程支援的情況下快取影片 context。Google Cloud 的實務影片分析筆記指出，context caching 是重複分析時重要的成本槓桿。

可用範圍與推出界線

Agentic video understanding 是支援三款 Flash 系列模型的處理能力，並非另一款單獨發布的影片模型。Google 表示，這項功能在 2026 年 9 月 1 日於以下模型與平台推出：

規劃中的消費者版與 YouTube 推出時程，並不能證明所有帳號現在都能使用。

切換預設模式前，先做四輪正式環境測試

發布公告說明了功能主張，但無法告訴你這個模式在自家影片上會如何運作。取代既有 static 工作流程前，先準備一組小型評測集。

1. 時間戳檢索：納入有場景切換、短暫出現物件，以及一個必須精準判斷開始與結束時間的事件的影片。將回傳時間戳與人工核對過的參考結果比較。
2. 快速動作計數：使用包含重複動作或物件穿越畫面的素材。檢查總數是否正確，以及回答是否交代計數時間窗。
3. 音訊與逐字稿依據：提出畫面動作與口語內容不同的問題，確認回答不會悄悄以其中一種模態替代另一種。
4. 營運表現：以兩種模式執行同一批檔案，記錄輸入／輸出 token、實際經過時間延遲、重試次數、空白回答、漏失事件，以及 static fallback 的結果。當選擇性擷取漏掉證據或帶來無法接受的延遲時，應保留 fallback。

不要根據發布文章訂出「超過 X 分鐘一律用 agentic」的硬性規則。已公開的資料支持依任務選擇，而非通用的片長門檻。

Gemini agentic video understanding API 常見問題

Agentic video understanding 是新的 Gemini 模型嗎？

不是。Google 將它定位為影片理解能力，可用於 Gemini 3.7 Flash、Gemini 3.6 Flash 與 Gemini 3.5 Flash-Lite。

我可以使用上傳影片，而不是 YouTube URL 嗎？

可以。Google 列出上傳影片檔案與 YouTube 影片兩種支援的 API 輸入來源；若是本機檔案，請先上傳，待處理完成後在媒體 part 傳入回傳的檔案 URI。

Agentic 影片處理需要額外付費嗎？

Google 表示沒有額外功能費用。一般 Gemini API token 定價仍然適用，最終帳單則取決於擷取內容與請求中的其他部分。

請讓具代表性的素材在兩種模式下都跑過一輪；只有在實測證據品質與 token 成本都符合應用目標時，才將 agentic 處理保留為預設模式。