Gemini Agentic Video Understanding API 实战指南

两小时的课程录像和 20 秒的产品短片，显然不该用同一种方式分析。对于长视频，或需要定位特定片段的问题，Gemini 新推出的 agentic video understanding 更适合作为起点；但 Google 所称的“最高”节省幅度来自基准测试，并不意味着每一笔 API 账单都会固定降低 66%。

按任务选模式，而不是只看视频时长

如果问题需要在视频中查找、回看某个特定时刻，Gemini agentic video understanding 会更合适。对于要求短片尽快返回结果，或必须以一致方式覆盖每个采样区间的任务，静态处理仍是更简单的选择。

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 中指定处理方式

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，并在发送媒体 part 前等待文件就绪。你安装的客户端版本可能不同，SDK 细节请以最新的官方视频理解指南为准。

从 client.interactions.create 迁移到 generateContent 时，不要直接混用两套示例代码。

Agentic 视频理解到底如何工作

静态视频处理会按固定帧率对视频采样。Google 表示默认值为每秒 1 帧，开发者可通过 API 调整采样率，随后模型会分析这些采样帧。

Agentic 工作流让 Gemini 搜索和扫描时间线，自主选择合适的处理速度，并按需调用视觉帧、音频或字幕文本，而不是对整段录像进行均匀加载：

1. 请求与问题相关的片段或模态信息。
2. 检查返回的帧、音频或字幕文本。
3. 需要更精确的时间定位时，重新查看更窄的时间区间。

静态采样能为开发者提供清晰直接的覆盖规则；agentic 处理则赋予模型更多判断权，让它决定该看哪里。因此在生产环境中，应使用有代表性的视频来校验时间戳和计数结果。

“最高节省”不等于固定打六六折

Google 公布了其在标准视频分析基准测试上的结果，并特别强调长视频中的最大收益：

根据 Google 的发布公告，agentic video understanding 按标准 Gemini API Token 定价计费，不收取额外功能费用。实际成本仍取决于模型、检索到的内容、请求本身和输出。若想了解更完整的 Token 与模型定价背景，可参考 Gemini 3.7 Flash API pricing guide。

如果需要围绕同一段录像反复提问，可在 API 工作流支持的情况下缓存视频上下文。Google Cloud 的视频分析实战笔记将上下文缓存列为重复分析的重要成本优化手段。

可用范围与后续发布边界

Agentic video understanding 是覆盖三款 Flash 系列模型的一项处理能力，并非单独发布的视频模型。Google 表示，它于 2026 年 9 月 1 日面向以下模型和入口推出：

面向消费者和 YouTube 的计划发布，并不代表目前所有账号都已获得这些能力。

切换默认模式前，先做四轮生产测试

发布公告展示了能力层面的结论，却无法说明该模式在你的具体视频上会如何表现。在替换现有静态工作流前，先准备一小组评估样本。

1. 时间戳检索：样本中应包含场景切换、短暂出现的对象，以及一项起止时间必须精确的事件。将返回的时间戳与人工核验过的参考结果进行比较。
2. 快速动作计数：使用存在重复动作或对象穿越画面的素材。核查总计数，并确认答案是否解释了计数所对应的时间窗口。
3. 音频和字幕文本依据：针对语音内容与画面动作不一致的场景提问。确认答案不会在未说明的情况下用一种模态替代另一种。
4. 运行表现：将同一批文件分别以两种模式运行，记录输入/输出 Token、端到端延迟、重试次数、空答案、漏检事件和静态模式的回退结果。若选择性检索漏掉证据或带来不可接受的延迟，就保留回退方案。

不要根据发布文章制定“视频超过 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 处理保留为默认方案。