做视频理解类应用时最直接的体感是模型能力在进步但 token 账单也在同步“进步”。尤其是会议录像、教学回放、安防素材这类几个小时的视频只要希望模型总结结果或回答某个细节问题平台成本和响应延迟都会明显上升。最近 Gemini API 在长视频方向提出了Agentic Video这种新的处理思路公开资料显示长视频处理 token 消耗最多能降低 88%。这篇文章会围绕这个功能展开先拆解为什么传统视频理解会“烧 token”再梳理 Agentic Video 的核心机制最后给出可直接参考的视频理解接入思路和工程化建议。本文适合三类读者一是刚接触多模态模型还没搞清楚视频 token 怎么计算的开发者二是已经在用 Gemini API 做视频总结、视频问答但觉得成本偏高的同学三是在做会议分析、媒体检索、内容理解平台的产品或算法工程师。1. Agentic Video 是什么先给视频处理一个“查找与精读”的过程1.1 从“AI 看视频”说起传统使用多模态模型理解视频时最自然的做法是把视频文件或连续帧交给模型然后输入一个提示词“帮我总结这段视频的内容”。模型会尽可能从画面帧、音频轨道、字幕信息中提取内容最终生成一篇摘要或回答。问题在于这种方式会一次性消耗大量 token。视频进入模型前往往需要先抽帧画面经过视觉编码器后会变成大量 visual token音频则变成 audio token文本字幕也有对应 token。视频越长token 总量就越惊人。对于几分钟的短视频还好但面对 1 小时起步的长视频输入 token 很容易进入超高量级。更麻烦的是很多业务问题并不需要“完整看完每一秒”。比如在 1 小时培训录像里问“讲师在哪个时间段演示了登录流程”或者在一场发布会里找“产品价格公布的那一段”传统做法是让模型从头到尾处理完整视频这自然会带来大量与目标任务无关的 token 消耗。1.2 Agentic Video 的核心思路从全量处理变成按需检索所谓 Agentic Video从公开信息传达的方向来看是指把视频理解从“一次性喂完整视频”改成“智能体式检索 按需精读”。大意是系统不再默认要求模型处理整个视频的全部帧而是先对视频做结构化分析和拆分再根据用户要解决的具体任务定位候选片段最后只把相关片段交给模型进行深层次理解和推理。这个思路有点像人类处理视频资料的方式拿到一份 3 小时录像后我们不会从第 1 秒开始逐帧记录而是会先看时间轴、看章节信息、拖进度条定位到关键段落再集中注意力精读重点部分。“先索引、再检索、后精读”取代了“打开就从头到尾全部看完”这正是它能明显降低 token 消耗的核心逻辑。可以把它理解为“带工具的模型”模型不再是一个被动的视频阅读器而是像一个会做规划的代理Agent它会先判断“当前任务需要看哪些片段”然后针对性地取得那些片段的分析结果。1.3 什么样的场景适合 Agentic Video不是所有视频任务都应该采用 Agentic 思路。它的优势场景主要是长视频且信息密度不均比如会议录像、课程回放、监控录像、直播存档。用户目标非常明确例如只想知道某个事件发生的时间、某个人说了什么结论。同一个长视频需要在多个问题上反复提问传统方式下每个问题都要全量分析一次Agentic 方式可以先建立索引后续每个问题只从索引中挑选相关片段省下重复计算成本。可以直观理解成如果任务要求“把每一分钟发生什么都详细列成报告”那么 Agentic 方式也可能需要覆盖大量片段优化空间有限但如果任务是“找出某几个关键事件”token 优化空间就非常明显。因此“最多降低 88%”这个数字取决于任务类型、视频结构和查询目标不能盲目理解成所有任务都能省同样多。2. 长视频处理为什么会“吃”掉大量 token2.1 视频 token 是怎么产生的很多刚开始接触视频理解的开发者会困惑文字 API 按 token 计费很好理解但视频到底怎么算这里需要先明确一个概念视频不是直接被模型以文件形式读取的输入前通常需要经过采样、切分和编码。模型层面的典型处理链路如下视频文件被解析成图像帧序列、音频时间片段和字幕文本。图像帧经视觉编码器转换成 visual token。音频经过编码后转换成 audio token。字幕、标题或语音识别结果转换成文本 token。所有这些 token 共同组成模型上下文随后续推理一起计算。所以输入的视频越长、采样帧数越多、画面内容越丰富token 量就越大。一个几十分钟视频换算成视觉 token数量级会非常夸张。而 API 的费用和上下文窗口占用都和 token 量直接相关。2.2 长视频场景里的三种典型浪费传统长视频处理里token 浪费主要体现在三个环节。第一全量输入浪费。视频有大量无关帧。一个时长 2 小时的活动录像真正有用的内容可能只有 20 分钟但全量模式下模型必须处理所有帧哪怕那些画面只是有人在签名入场。第二重复输入浪费。同一个视频如果先要总结又要提取特定片段还要做关键人物识别传统模式很可能每个任务都重新处理一次完整视频导致同一份长视频被反复计费。第三检索延迟进入上下文。当你希望模型“在长视频里查找某个细节”时它往往需要浏览足够多的上下文才能找到答案。如果没有一个可检索的中间索引模型就只能在长上下文中大海捞针输入 token 不会低输出准确性也容易受到影响。2.3 为什么说 Agentic 能改变这个结构Agentic Video 的设计目标是把“全量视频理解”变成“可计划、可检索的局部理解”。理想状态下视频只需要被解析一次随后系统形成时间点级别或事件级别的描述索引当用户提出任务时先从索引中定位最相关的候选时间片段再基于这些片段完成推理。假设一段 2 小时视频按传统方式需要消耗 1000 个单位的 token如果某个任务只需要定位其中 3 个片段做深度分析那么这部分检索与精读所需的 token 就远远小于 1000。多任务、多轮对话场景中这种收益会被进一步放大因为索引只需要创建一次后续查询不需要再重复读取整个视频。这也是“Agentic”中“代理”一词的意义模型会像有分工的项目负责人一样判断当下该看哪些内容、调用哪种能力、如何把多步查询结果汇聚成最终答案而不是简单地把输入一口气吞入。3. Agentic Video 的可能处理链路索引、定位与局部精读3.1 一条更省 token 的视频分析流水线虽然目前很多技术细节仍需以 Gemini API 官方文档为准但从长视频智能处理的设计思路上看一个 Agentic Video 类型的处理流程通常包含下面几个阶段。阶段一视频预处理与索引构建。系统先对视频进行解析把连续的视频流拆成不同的镜头或事件单元并给每个单元标注开始时间、结束时间、画面描述、语音文字、可能的事件类型。这个阶段输出的是一份结构化的视频索引。阶段二任务理解与检索定位。收到用户问题后模型先理解任务目标确认需要找什么。比如问题是“讲师演示 API 调用的部分是几分钟”那么模型会把关键词锁定为 API 调用、演示、讲师操作等然后到索引中检索候选片段。阶段三候选片段精读。系统把命中的片段作为重点输入只针对这些时间范围做深度视觉理解、语音理解和上下文推理。阶段四结果汇总与答案生成。模型把片段级结论聚合成用户可以理解的回答必要时给出对应的时间点。这里的关键不是某个 API 参数而是处理机制的变化从“读全片”变成“先看检索结果再有选择地精读”。正是这种机制让“长视频中找答案”能明显减少进入模型上下文的视频 token。3.2 可以把 Agentic Video 理解成“视频版 RAG”很多后端开发者对 RAGRetrieval-Augmented Generation检索增强生成已经比较熟悉。传统 RAG 的做法是先把文档切块、向量化、存储到向量数据库中用户提问后先做相似度检索召回相关文档块再把这些片段喂给大模型让模型基于片段生成回答。Agentic Video 的设计思路和 RAG 有异曲同工之处。只是这里的检索对象不是文本块而是有时间边界、有事件描述的视频片段索引内容可能包含场景描述、语音转写、画面 OCR、事件标签等。最终生成的也不是固定答案而是可以回溯到视频原片的检索结论。用熟悉的思路做类比会更容易接受这个能力的意义它不是让模型在超长上下文里硬找答案而是给模型配备了一个擅长管理长视频的检索辅助器。开发者如果以前做过 PDF 文档问答再切换到这个工作流时会比较顺畅。3.3 token 收益的示意估算为了更直观地理解 token 下降空间可以做一组非常粗略的示意计算。假设一段在线课程视频时长 60 分钟传统全量输入模式下每处理一次累计需要消耗约 100 万 token。Agentic 流程可以拆成两部分开销建立索引阶段模型做一次全片内容结构化识别可能消耗 30 万到 40 万 token。后续每个任务阶段只有命中片段进入上下文假设命中总时长 10 分钟相关视频 token 消耗约 15 万到 20 万。也就是说如果是一次性问答任务总 token 比以前降低一半以上如果是同一个视频做 5 个不同任务索引只建一次后面每个任务都只花片段级别的 token整体平均成本下降会非常可观。88% 这个数字应该是基于某些典型多任务或检索类场景测得的最佳结果。实际项目中如果你的任务要求覆盖整段视频的完整细节那么优化幅度不会那么高。因此在做技术选型时正确的态度是把 Agentic Video 看作一个适合长视频、多任务、检索类问题的机制并结合自己的评测数据集测试成本与效果。4. 在 Gemini API 中接入视频理解环境与示例思路4.1 环境准备要调用 Gemini API 处理视频首先要准备开发环境。本文以 Python 环境为例版本建议使用 Python 3.10 或更新版本。你需要准备Google AI Studio 或 Vertex AI 项目中的 API Key或者服务账号凭证。在项目中启用对应的 API 服务。安装官方提供的 Python SDK。安装 SDK 的基础命令如下pip install google-genai不同 SDK 版本之间接口可能存在差异下面的代码是理解原理的示例思路正式使用时请以你所安装 SDK 的文档或当前官方文档为准。如果你使用的是 Vertex AI则还需要处理项目 ID、区域等相关环境变量。4.2 传统方式直接上传视频并询问在还没有启用 Agentic 机制的简化示例中视频理解通常会经过“上传文件 → 引用文件 → 发送提示词”三个步骤。示例思路如下# 示例思路需要根据你使用的实际 SDK 版本调整 from google import genai client genai.Client(api_keyYOUR_API_KEY) # 步骤 1上传视频文件 video_file client.files.upload(pathmeeting_recording.mp4) # 步骤 2构造请求这里 model 名称需要按官方可用模型列表填写 response client.models.generate_content( modelgemini-2.x-pro, contents[ video_file, 请总结这段视频的重要内容并指出关键时间点。, ], ) print(response.text)这段代码不一定会直接调用到 Agentic Video 模式但它展示了基础接入入口。需要特别说明的是不同模型版本对视频格式、时长上限的要求不同开发时应在上传前对视频做转码或抽帧预处理。如果你在调用过程中遇到403、permission denied、或者类似token exchange failed的报错先检查 API Key 是否有效、项目权限是否被正确授予、当前账号所在区域是否为官方支持区域。认证失败类问题多数是权限配置导致而不是代码逻辑问题。4.3 手动实现“先检索后精读”的 Agentic 工作流在相关能力完全开放前如果你想在自己的工程里复刻 Agentic Video 的低 token 思路可以参考下面这套手动工作流先让模型生成事件索引再用 FFmpeg 截取候选片段最后只将候选片段发回模型精读。第一步建立视频事件索引。index_prompt 请对上传的视频进行一次快速分析。你的目标是生成视频事件索引而不是详细转写。 输出要求 1. 将视频划分成若干个语义完整的事件片段。 2. 每个片段输出开始时间、结束时间和一句话事件描述。 3. 不要输出冗长细节不要让描述超过 30 个字。 4. 使用 JSON 数组返回。 这一步的输出质量直接决定后续检索准确率。为了让索引更适合程序解析建议要求模型使用 JSON 结构并把开始时间和结束时间统一成秒数。例如[ {start: 0, end: 340, desc: 开场介绍与议程说明}, {start: 340, end: 920, desc: 演示用户登录流程}, {start: 920, end: 1800, desc: 答疑与讨论} ]拿到结果后可以将这份索引存入数据库。后续每个新问题不需要重新分析视频只需要对照索引检索即可这正是 Agentic 工作流中“索引只建一次、后续按需精读”的工程价值。第二步根据用户查询筛选候选片段并裁剪视频。假设用户问题是“演示登录流程的片段是从哪里开始的”我们可以从索引中筛选出开始于第 340 秒的片段。为了让精读阶段获取更准确的上下文可以适当扩展候选片段边界。ffmpeg -i meeting_recording.mp4 -ss 300 -to 360 -c copy candidate_segment.mp4命令解释如下-i meeting_recording.mp4指定输入视频。-ss 300从第 300 秒开始裁剪提前 40 秒有利于保留上下文。-to 360裁剪到第 360 秒。-c copy直接复制编码避免重新编码导致速度过慢。第三步只对候选片段发送精读请求。# 示例思路只将裁剪后的候选视频传给模型 response client.models.generate_content( modelgemini-2.x-pro, contents[ candidate_video_file, 这是一个视频片段。请仔细分析用户登录流程的每一步并说明画面中出现的关键字段。, ], )相比把整段 1 小时视频传给模型这种方式输入的 token 消耗会大幅下降。你也可以在候选片段分析中加入最终校验 prompt让模型判断“这一段是否确实包含用户要的信息如果证据不足返回 insufficient”。4.4 工程化时如何记录 token 用量在 Gemini API 的返回结果中通常带有usage_metadata信息可以帮助你统计输入 token、输出 token 和总 token。工程化时务必保留这些日志数据。{ prompt_token_count: 123456, candidates_token_count: 890, total_token_count: 124346 }有了这个数据你就可以做对比测试把同一个问题分别用“全量视频输入”和“先检索后精读”的方式跑一次对比调用成本、返回准确率和端到端耗时。不要轻信任何人给出的永远省 88% 的结论因为任务和视频差异很大要以自己的评测数据为准。5. Agentic Video 适合落地在哪些业务场景5.1 会议记录与客服质检会议录像和客服通话录音往往有几个特点时长长、说话人多、有效业务内容密度低。传统全量分析会花费大量 token尤其当业务人员只想复盘某几个关键决策、确认某个客户投诉承诺时全量处理会产生大量无用开销。用 Agentic 工作流后系统可以先为整个会议建立内容索引之后当运营人员提问“客户最后是否同意续费”或“技术负责人给出的排期是什么”时只需把候选语音段落或事件片段交给模型精读既节省 token也能让答案附带回看时间点。客服质检场景也是类似。对成百上千通客服录音做全量多轮分析成本很高但按事件片段建立检索库后可以先快速筛出涉及“投诉、退款、辱骂、承诺”等事件的片段再针对命中片段做深度判断这样才能在可控预算内支撑大规模质检。5.2 媒体资料库与影视素材检索影视、广告、媒体行业经常积累大量历史素材。传统做法是让剪辑师手动翻素材或者用人工打标效率低且成本高。引入长视频理解能力后可以实现自然语言驱动的素材召回。例如导演需要找一段“黄昏时主角在楼顶说话”的镜头。系统可以先依靠镜头切分识别出场景边界再结合字幕/旁白构建事件描述用户提问时直接从索引里命中楼顶、黄昏等语义标签抽出候选片段做精细确认。这里 Agentic 的价值不只是减少 token更重要的是让机器在真正理解前先建立可检索的视频结构从而服务好非结构化素材库的搜索需求。5.3 在线教育与直播回放在线教育平台经常需要从几个小时的直播录像中切出知识点短视频。每个录像会被不同用户反复利用如果每一道练习题、每一个新问答都全量处理一次视频成本会成倍增长。更合理的方式是开课或直播结束后先对完整视频做一次事件级别索引再基于索引把课程切分成“概念讲解”“代码演示”“学员提问”等片段。后面所有学生问答、课程章节生成、讲义整理都只需要从索引中定位片段后处理不用重复处理完整视频。这可以看作是 Agentic 模式的直接工程落地。5.4 安防与长时监控资料分析安防场景中长时监控视频包含大量无有效事件的时间段。要快速找到“某日凌晨有人进入仓库”的片段传统人工看录像并不现实全量多模态分析又会把大量无关画面送入模型。使用类似 Agentic 的思路时系统可以先用低成本算法完成运动检测、人脸框识别或区域入侵判断生成事件时间索引。只有当事件片段被触发时才调用多模态大模型对窗口期视频做深度理解。这既可以用在存证检索也可以作为高优先级告警复核。需要提醒的是任何涉及人员监控和隐私处理的场景都必须严格遵守当地法律法规确保采集、存储、分析行为有合法授权并对人脸、车牌等敏感信息进行必要的脱敏保护。6. 常见问题与排查思路6.1 为什么官方说“最多降低 88%”我自测的效果却不同88% 是强检索条件、多种相似任务复用索引时的优化结果。你的业务如果要求把视频中每一分钟都详细总结出来使用 Agentic 机制也需要覆盖足够多的事件片段天然很难压缩到同等幅度。建议在方案设计阶段把任务分成两类全量覆盖型任务和重点检索型任务并分别评估是否采用“先索引后精读”策略。6.2 视频上传后调用很慢怎么办长视频处理涉及上传、预解析、索引等阶段本身会比普通文本对话更慢。如果慢在“上传”可以检查网络和文件体积如果慢在“模型响应”则应当缩小候选片段时长避免每次请求都携带超大上下文。工程上也可以把视频文件存放为对象存储 URL而不是每次都上传局域网大文件。6.3 遇到 token 相关报错或认证报错怎么排查很多开发者在接入 Gemini API 时遇到过这类报错常见表现包括403 forbidden权限不足、配额用尽、API Key 无效或当前区域不支持。token exchange failedOAuth 流程或 API Key 交换出问题服务侧拒绝完成认证交换。提示输出 token 达到上限复杂长视频任务要求模型一次性生成过长结果超出了单次输出的最大 token 限制。建议的排查顺序是先检查 API Key 和项目权限再确认所在区域是否被官方支持然后查看官方调用配额最后把单次输出拆小。代码层可以在每个调用点补 full 的错误日志记录 status code、报错 body 和调用时间方便和官方文档比对。6.4 模型回答中的时间点不准确怎么办视频事件边界切分可能受镜头切换、字幕对齐误差影响模型给出的时间点只是估计值。面向生产时可以加入二次确认机制对模型定位到的时间点前后扩展几秒形成候选片段再把候选片段抽样帧发送给模型做验证。如果业务对时间精度要求很高例如必须精确到秒仍建议结合人工抽检或音频波形对齐技术来做兜底。6.5 长视频文件格式不支持怎么办常见处理途径是先使用 FFmpeg 做转码。示例命令如下ffmpeg -i input.mov -c:v libx264 -c:a aac -movflags faststart output.mp4转码后再上传可以降低文件解码兼容风险。文件过大的话还可以切分成多个水平片段分别分析但要注意切分不应破坏语义完整性。按下述规则切分更容易保持片段语义完整性切分点优先选在无对白段、章节标题出现前、镜头有明显变化的位置。7. 工程实践建议把低 token 思路沉淀成架构能力7.1 建立“视频索引层”而不仅是“模型调用层”Agentic Video 虽然可能以 API 的形式开放但工程落地不能只是把视频直接丢过去而是在系统设计上增加“视频索引层”。一次完整接入应当至少包含三个模块视频预处理模块负责上传、转码、解析基础信息。事件索引模块负责调用模型或传统算法生成可检索结构。查询精读模块负责将文本检索命中映射到视频片段并执行局部深度理解。把索引层作为独立模块后同一个视频可以被会议纪要、客服复核、知识库检索等多个上游业务复用。这样做不仅省 token也让整个系统逻辑更清晰。7.2 控制输出 token结构化输出更省心很多开发者在统计成本时只关注输入 token实际上输出 token 也会对成本产生较大影响。Agentic 流程尤其需要控制输出索引构建阶段要求模型输出格式固定的 JSON精读阶段要求模型只输出结论、证据片段和置信度不要长篇大论复述画面。建议每次都给出明确的输出约束如下面这段提示词请基于视频片段回答下列问题。 要求 1. 如果片段中能找到证据用一到两句话作答。 2. 给出对应的起始时间点。 3. 如果找不到证据不允许编造请输出 insufficient。结构化的输出更容易接入业务逻辑也方便在后续做统计、评测和缓存。7.3 对视频和索引做缓存处理同一段视频如果被多个不同人员提问视频索引完全可以复用。可以引入多级缓存第一级原始视频元数据缓存例如分辨率、时长、格式。第二级事件索引缓存重复生成会浪费较多 token。第三级高频问答结果缓存完全相同的用户问题直接返回结果。缓存设计对成本的帮助甚至比压缩 token 更大因为它让 API 调用从“每次实时计算”变成“一次计算多次读取”。7.4 注意数据安全与合规视频往往比文本包含更多敏感信息处理时必须强调几个边界只处理有明确授权的视频数据不要因为技术方便就越权分析监控素材或私人录像。视频内涉及人脸、声音、身份证、车牌等敏感信息时建议先做脱敏处理。不要把完整视频内容写入日志系统日志里只记录文件 ID、片段时间点和处理状态。使用第三方 API 前不要忽略服务条款中的数据处理政策。7.5 建立成本与质量评估指标在把 Agentic Video 接入生产前建议先建立一套可量化的评估方式成本指标单视频平均 token 消耗、单次查询平均费用、缓存命中率。质量指标事实一致性、时间点准确率、无答案查全率。性能指标建立索引耗时、单次问答时延、批量任务吞吐量。可以挑选 20 到 50 条覆盖不同时长的目标视频设计 30 个有代表性的问题先用传统全量输入跑一遍获取基线数据再用手动 Agentic 工作流跑一遍最后对比成本与准确率。只有用数据验证过才适合决定是否要大规模替换现有链路。8. 下一步可以继续关注什么Gemini API 推出 Agentic Video 背后的趋势其实是视频理解从“输入全量信息”向“自动规划信息获取路径”演变。对于开发者而言与其只等待某一个新接口公布不如先把这套“索引、检索、局部精读”的工程方法论用在现有业务里这往往能更快见效。下一步可以做的三件事在 Gemini API 官方文档和自己项目环境中验证最新视频处理能力确认 SDK 参数和配额细节。把手头的长视频业务任务清单整理一遍区分出哪些适合全量分析、哪些适合检索式分析。搭建一个最小评测集跑通“先建索引、再精读片段”的流程记录成本和效果变化。如果你正在做会议纪要、素材检索、视频告警复核或内容理解平台可以先从一次小范围对比实验开始把同一段视频分别用全量输入和先索引后精读的方式跑一遍观察 token 消耗和答案质量再决定是否把你的业务迁移到 Agentic Video 这套处理方法上来。等到官方接入细节更新稳定后替换核心 API 调用层就不会是难事了。