做多模态应用的开发者这两年应该都有一种感觉：文本 token 好算，视频 token 难控。尤其当视频时长从几十秒变成几十分钟甚至几小时，直接把视频“一次性打包”交给大模型处理，token 消耗和延迟会迅速超出预期。
最近 Gemini API 推出的 Agentic Video 之所以引起关注，正是因为它在长视频处理场景里给出了一条新的技术路径：官方数据显示，长视频处理场景下的 token 消耗最多可以降低 88%。这个数字并不只是简单的模型压缩或缓存优化，而是把视频理解过程从“全量识别”改成“按需理解”。
这篇文章会围绕几个问题展开：视频任务中的 token 到底是怎么消耗的？Agentic Video 背后是什么样的处理思路？如果我们自己在项目中做视频问答、视频检索、视频摘要，能不能借鉴这套方法设计一套低成本的工程方案？文章会给出可落地的伪代码、评估思路和常见踩坑点，适合正在做多模态应用、视频内容理解或希望控制大模型成本的后端开发者阅读。
1. Agentic Video 是什么，为什么值得关注
1.1 对 Agentic Video 的初步理解
Gemini API 推出 Agentic Video，不是简单地给模型增加一个视频上传入口，而是把 Agent 的“规划—执行—验证”思路引入了视频理解流程。
传统视频理解做法是：用户上传一段视频，模型把视频转成一张张图像帧，再做整体分析。这个做法对短视频、单场景视频没有问题，但视频一长，计算量会线性增长。
Agentic Video 的差异点在于：模型不再试图一次性理解视频中所有细节，而是先通过一套 Agent 机制对视频做内容索引，记录“第几秒到第几秒大概发生了什么”，当用户提问时，Agent 再决定应该细看哪一段画面。整个过程类似于我们处理长文档时先建目录，再翻到对应章节精读。
这种设计在长视频场景下非常有价值。视频理解任务通常是“在一个较长的时间轴上找到特定事件”，而不是“把每一秒画面都记住”。只要定位准确，模型不必看完全部帧就能回答问题。
1.2 官方数据传达的信号
官方提到的“token 消耗最多降低 88%”是一个很吸引人的数字，但需要正确理解。
从工程角度看，这个数字并不是说所有视频处理任务都能直接打一折。它更可能来自特定基准场景：一段长视频、一个需要定位特定事件的问题、多轮对话过程中不再重复读取全视频。这样的任务非常适合 Agentic Video 的两阶段结构，节省效果就很明显。
反过来，如果用户要求“把视频里每一秒都详细描述一遍”，Agentic Video 不可能跳过那么多内容，节省幅度就会低很多。
我们真正应该关注的是这个方向背后的框架：先粗粒度理解，再细粒度问答。这是一种可以在自有 pipeline 中复现的思路，不依赖某一个具体模型或 API。
2. 视频任务中 token 为什么“伤不起”
2.1 从文本 token 到视频 token
如果你使用过大模型 API，对 token 这个词应该不陌生。文本场景里，token 可以近似理解为模型读取文本的最小单位，一个汉字可能对应一到多个 token，一个英文单词通常拆成一到两个 token。
到了视频场景，token 的概念变得复杂。视频本质上是一个三维数据流：包含宽度、高度、时间三个维度。模型无法像人一样直接“看视频”，常见做法是把视频按照一定的间隔抽取成图像帧，再让视觉编码器把单帧画面转换成视觉 token，加上音频轨道的音频 token，最终得到一个巨大的 token 序列。
整个过程可以近似写成：
视频总 token ≈ 每帧画面产生的 token × 抽帧数量 + 音频 token + 字幕 token举一个直觉上的例子。假设一个视频理解模型每秒从视频中抽取 1 帧，每帧会被压缩成 1000 个左右的 token，那么 1 分钟视频大约产生 60000 个输入 token。这个量级对上下文窗口来说可能还能接受，但如果视频是 1 小时，输入 token 就可能膨胀到数百万。
这就是为什么长视频 API 调用在 token 和费用上都容易失控。
2.2 长视频处理的三个核心痛点
这里把长视频处理中的工程痛点梳理为三点，理解了这三件事，也就理解了 Agentic Video 优化的目标。
痛点一：全量视频 token 太大。无论任务是问答、摘要还是搜索，只要模型需要把握整体内容，就绕不开抽取大量帧。视频越长，输入 token 越大，API 单次请求的延迟也会明显增加。
痛点二：多轮交互时重复计费。视频问答通常不是一问一答就结束。用户会连续问多个问题，比如“画面里出现了哪些人”“他们最后去了哪里”。如果每次都把完整视频重新传给模型，每一轮都会产生一份完整的视频 token 费用。回答 5 个问题，视频内容相当于被完整计算了 5 次。
痛点三：定位精度要求高。视频不同于纯文本，事件往往分布在某几秒或某几十秒内。模型需要从时间轴上找到对应的片段，这个定位能力依赖强视觉推理。如果抽帧稀疏，可能错过关键事件；如果抽帧密集，token 成本又压不住。
传统方案只能在“抽帧稀疏省 token”和“抽帧密集保效果”之间做取舍，而 Agentic Video 试图用两层结构解决这个矛盾。
2.3 一个直观的数字估算
为了便于理解，我们可以做一组理想化估算。
| 策略 | 假设输入 token | 一次问答成本 | 连续 10 次问答成本 |
|---|---|---|---|
| 全量视频直接送模型 | N | N | 10 × N |
| 先索引后按需细看 | 索引阶段 20% N，每次提问只消费相关片段 10% N | 20% N + 10% N = 30% N | 30% N + 9 × 10% N = 120% N |
这组数字本身不严谨，只是一个方向性示意。但它说明了一件事：长视频问答场景下，成本优势不是来自单次请求，而是来自多轮复用的“索引”。
第一次索引占用的 token 不会消失，但它是一次性成本。后续提问只检索相关片段，成本就降下来了。当问题数量越多、视频越长，这个模式的优势越明显。
3. Agentic Video 的核心思路：从“全量灌入”到“按需理解”
3.1 “Agentic” 一词在这里代表什么
最近一年，Agentic 这个词在大模型领域出现频率很高。简单理解，Agentic 指的是模型不是只做“输入—输出”的一次性响应，而是可以多步规划、调用工具、观察中间结果后继续推进目标。
在 Agentic Video 里，这个思想体现为：模型面对的不再是静态的视频文件，而是一个可以被检索、被定位、被局部读取的视频库。
换句话说，视频不再是一段必须整体读入上下文的“大文本”，而是变成了一个带有时间索引的“知识库”。Agent 通过规划决定哪些步骤必须在低分辨率、大跨度帧条件下执行，哪些步骤需要调用高分辨率局部片段。
这里有一个容易混淆的概念：Agentic Video 并不是指“视频里的人或物体可以自主行动”，而是指“视频理解的过程本身是 Agent 化的”。
3.2 处理流程拆解
一个典型的 Agentic Video 处理流程可以分解为三个步骤。
第一步：粗粒度建立索引。
系统先对视频做一个低成本扫描。这一阶段的帧间隔可以设置得比较大，分辨率要求也不需要很高，只要能识别出场景切换、主要人物、关键事件即可。扫描结果会生成一个带时间戳的内容列表，比如：
| 时间区间 | 事件摘要 | 置信度 |
|---|---|---|
| 00:00:00 - 00:02:15 | 主持人开场 | 高 |
| 00:02:16 - 00:05:40 | 研发负责人介绍模型架构 | 高 |
| 00:05:41 - 00:08:20 | 现场 demo 演示 | 中 |
| 00:08:21 - 00:12:00 | 评论区观众提问 | 中 |
这个阶段是成本可控的关键。即使完整索引需要一定 token，它也是全局范围内唯一一次高消耗操作。
第二步：根据用户问题做时间定位。
用户提出“这段视频里模型讲解架构时，提到了哪几个模块？”Agent 不直接去大模型中翻整段视频，而是在索引中搜索与“模型架构”“技术模块”相关的片段，得到候选时间范围。
这一步仍然是低成本检索，不涉及大量视觉细节。
第三步：只对相关片段做高精度推理。
确定相关时间区间后，Agent 将目标片段以较高帧率取出，再送入多模态模型做细粒度视觉理解。模型只需观察几十秒的内容，就能组织出准确答案。
如果用户继续追问“架构图里数据库那一层用的是什么方案”，Agent 可以回到索引查找对应更细的时间点，只检索那一段，而不需要重新读取整场视频。
3.3 为什么最多可以降低 88% 的 token 消耗
在理想的长视频多轮问答场景中，88% 的节省是可以通过计算结构解释的。
假设一段 1 小时视频全量送入模型需要消耗 600 万 token。传统方案中，用户每提一个问题，系统都消耗 600 万 token。如果用户连续问 20 个问题，总消耗是 1.2 亿 token。
Agentic Video 模式下，索引阶段消耗一次，可能占总量的 15% 到 20%。每个问题定位相关片段后，平均只需要细看视频总时长的 5% 到 10%，即每问消耗 30 万到 60 万 token。
20 个问题下来，总消耗可能只有全量模式的不到 20%。当问题数量更多、相关片段更分散时，节省比例可以进一步提高。
当然，如果视频只有十几秒，本身就不需要建立复杂索引，Agentic 的额外步骤反而可能带来更多开销。这就是为什么官方在描述中特别强调“长视频处理”。
3.4 不是银弹：什么情况下收益有限
作为开发者，我们应该清楚这项技术的适用边界，避免盲目套用。
当任务是全局理解时，Agentic Video 的优势会被削弱。比如“请描述整段视频中出现的所有转场方式”，模型本来就默认对所有内容负责，Agent 跳过某些部分可能导致信息丢失。
当视频场景切换频繁、没有明确时间语义时，索引阶段的定位精度可能下降。比如一段长时间固定机位的监控视频，画面内容几乎不变，Agent 很难通过粗粒度扫描找到“事件发生点”，此时需要配合音频事件检测、运动检测等外部手段。
当问题本身需要跨多个不连续片段进行综合推理时，检索结果的合并和去重逻辑会变复杂，系统需要额外设计，不能简单认为所有视频任务都可以直接降低 88% 成本。
4. 类 Agentic Video 方案落地：工程示例
4.1 基线设计：传统视频全量问答伪代码
在理解 Agentic Video 之前，先看一下传统全量视频问答的问题出在哪里。下面伪代码演示了“每一轮都重新传入完整视频”的交互模式。
# 伪代码：传统全量视频问答，仅供理解成本结构 def upload_video_file(video_path): # 上传视频到模型服务端，获得可访问的视频资源 return service.upload(video_path) def generate_content(video_ref, question): # 伪代码：将完整视频和问题一起发送给模型 response = model.generate_content( contents=[video_ref, question] ) return response.text, response.usage_metadata video_ref = upload_video_file("./long_video.mp4") questions = [ "视频里专家是从什么时候开始介绍架构设计的？", "架构设计中提到了哪几个核心组件？", "演示环节有没有出现报错？", ] for q in questions: answer, usage = generate_content(video_ref, q) # 每一轮都会重新读取全量视频 token print("问答结果：", answer) print("本轮 token 消耗：", usage)这种写法实现简单，代码容易理解，但如果视频很长，每一轮问答都会产生高昂的输入成本。
真正的 Agentic Video 思路会尝试让系统在第一次“看”视频时就留下索引信息，后续问题尽可能只访问索引和局部片段。
4.2 搭建两阶段视频问答 Pipeline
下面演示一个简化版的两阶段处理流程。这个流程不是官方 SDK 的完整复制品，而是为了表达核心工程结构。
# 伪代码：两阶段视频理解 Pipeline 示意图 class VideoIndex: def __init__(self): self.segments = [] # 存储 [start_time, end_time, summary, keywords] def build(self, video_path): # 阶段：低间隔取帧，建立场景索引 frames = sample_frames(video_path, interval_sec=5, resolution="low") # 伪代码：批量对低清帧生成视觉描述 descriptions = [describe_video(frame_group) for frame_group in frames] # 伪代码：按时间连续性合并语义接近的片段 self.segments = merge_by_semantics(descriptions, max_gap_sec=15) def search(self, question): # 伪代码：在索引摘要中检索候选片段 hits = [] for seg in self.segments: relevance = text_similarity(question, seg.summary) if relevance > threshold: hits.append(seg) return hits def agentic_video_qa(video, index, question): # 第一步：在低成本索引中定位 candidate_segments = index.search(question) if not candidate_segments: return "未在视频中找到相关片段" # 第二步：只把候选片段内容送到高精度模型 local_high_fps = [] for seg in candidate_segments: local_high_fps.append( extract_video_segment(video, seg.start, seg.end, resolution="high") ) answer = model.generate_content( contents=[*local_high_fps, question] ) return answer, candidate_segments这段伪代码中，sample_frames、describe_video、merge_by_semantics等函数都是抽象函数，落在真实项目中可以是不同的实现方式：
sample_frames可以使用 FFmpeg 按固定间隔抽帧，也可以调用视频场景切分模型。describe_video可以调用多模态模型对每组帧生成描述。merge_by_semantics可以基于文本相似度或时间间隔做合并。text_similarity可以是大模型的零样本判断，也可以是向量检索。
这里最关键的设计变化是：视频只在VideoIndex.build阶段被整体消费一次；用户发起问答后，系统从文本索引开始检索，再拉取局部片段。
4.3 添加一个可运行的成本对比工具
在做这类改造时，建议把“成本”纳入验收条件，而不是只关注答案效果。可以在每次请求后读取模型的 usage_metadata 字段，把 token 消耗累计下来。
# 伪代码：统计两阶段方案与全量方案的 token 差距 def estimate_baseline_tokens(video_duration_sec, tokens_per_sec): return video_duration_sec * tokens_per_sec def estimate_agentic_tokens(index_cost, questions, avg_retrieve_duration_sec, tokens_per_sec): # 索引阶段一次性成本 total = index_cost # 每个问题只消费目标片段时长 token for _ in questions: total += avg_retrieve_duration_sec * tokens_per_sec return total video_duration = 3600 # 1 小时视频 tokens_per_sec = 1200 # 假设每秒视频约产生这么多输入 token questions = 20 avg_retrieve_duration = 40 baseline = estimate_baseline_tokens(video_duration, tokens_per_sec) * len(questions) agentic = estimate_agentic_tokens( index_cost=int(video_duration * tokens_per_sec * 0.15), questions=questions, avg_retrieve_duration_sec=avg_retrieve_duration, tokens_per_sec=tokens_per_sec, ) print("全量方案预计 token：", baseline) print("两阶段方案预计 token：", agentic) print("节省比例：", round(1 - agentic / baseline, 2))这段代码的价值不在于精确计算，而在于提醒我们：视频长、问得多，Agentic 结构越划算；如果视频短、只问一次，则没必要引入额外索引流程。
4.4 验证这类方案时要注意什么
完成 Pipeline 改造后，不能只看 token 减少了。索引可能漏掉关键片段，检索阶段也可能返回错误时间，所以建议在测试集中做三类验证。
第一类是片段定位准确性验证。给定一个事件描述，检查 Agent 返回的时间区间是否覆盖真实发生时间。如果覆盖率低，说明索引摘要的信息密度不够。
第二类是端到端答案质量验证。记录 Agentic Video 方案和全量视频方案的输出，可以由人工或另一个评测模型打分，判断有多少答案在信息完整性上出现下降。
第三类是成本收益验证。需要同时统计索引构建耗时、首轮问答时延、后续问答平均时延，以及总的 token 消耗。因为 Agentic Video 增加了一步索引，工程上可能有额外基础设施成本，CPU、内存、存储开销也要一起计入。
5. Gemini API 相关实践注意事项
5.1 视频上传与请求方式
使用 Gemini API 处理视频时，通常需要先把视频上传到可访问的服务端，再在模型请求中引用该视频资源，而不是直接传本地路径。
短视频可以直接通过 API 请求发送文件内容，但长视频文件较大，一般更适合使用异步上传或 File API。具体限制需要查阅当前官方文档，因为不同版本和不同区域可能有差异。
重点要关注的信息包括：单个视频文件的大小上限、可分析的最长时长、支持的视频格式清单、存储有效期。这些限制会直接影响我们设计 Agentic Video 索引任务时的切片策略。如果长视频超过单次 API 限制，先做场景切分可能是必要前置步骤。
5.2 多轮对话下的 token 使用技巧
在长视频对话场景中，一个常见的误操作是：把历史多轮问答也一起重新传给视频模型。视频内容已经在之前对话中出现过，如果每轮都在 messages 里追加历史视频 token，费用会越滚越大。
建议把视频处理拆分为“视频理解对话”和“一般文本对话”两个阶段。第一阶段只负责从视频中提取事实并生成结构化结果，第二阶段基于结构化结果继续问答。这样可以让视频 token 尽量集中在校验和答案生成阶段，避免重复消耗。
另一个实用技巧是，在不需要视觉细节时，优先让模型基于文本摘要回答问题。比如用户问“这个视频大概讲了几个部分”，文本摘要已经足够，不需要再把高清片段塞入上下文。
5.3 异步任务、缓存与降级方案
长视频处理往往不是一次同步请求就能完成的。真实业务中建议设计一个任务队列，把视频上传、索引构建、问题回答拆成异步任务。
索引结果应该落库缓存。假如多名用户针对同一段视频提问，完全不需要重复构建索引。缓存 key 可以是视频文件的 hash 值，value 是分段索引结果和过期时间。这样一来，第二次以后的所有问答都只消耗检索和局部阅读 token。
降级方案同样重要。当检索系统返回空结果或置信度过低时，应该触发“全量回调”逻辑，即放弃节省 token，重新把完整视频送入模型做一次兜底回答。这样虽然成本可能偏高，但可以保证用户体验不会因为检索失误而完全失败。
6. 常见问题与排查思路
6.1 常见报错与处理方式
在长视频 API 调用的实践中，下面几类问题非常典型，整理为表格便于对照排查。
| 问题现象 | 可能原因 | 解决思路 |
|---|---|---|
| 视频文件上传后无法访问 | 文件超过长度限制，或格式不受支持 | 查看官方文档限制，使用 ffmpeg 转码或切片后重传 |
| 单次请求耗时过高 | 视频较长且抽帧策略密集 | 降低抽帧频率，先使用低清帧索引，需要细看时再拉局部高帧率 |
| 多轮问答 token 消耗增长异常 | 历史消息中保留了大量视频内容 | 将视频历史转换为文本摘要，或增加缓存机制 |
| 返回内容截断 | 输出 token 达到限制 | 调整 max_output_tokens，或要求模型先给结论再展开细节 |
| 鉴权报错或返回地区限制类错误 | API Key 权限、配额或账户地区受限 | 检查账户权限、项目配额和官方支持地区，不要在无权限环境重度调用 |
针对每一个问题，建议先看响应体中的 error 类型和 usage_metadata，这比盲目改代码更高效。如果出现鉴权相关报错，不要反复重试，先核对 API Key 是否具有视频模型的访问权限、项目是否开通了对应模型服务。
6.2 为什么视频 token 统计和预期不一致
很多开发者在刚接触视频 API 时，会发现 token 统计比自己手动计算多一点或少一点。这通常是正常现象。
不同模型对视频的解码策略不相同。有的模型按固定间隔抽帧，比如每秒识别一帧；有的模型使用场景自适应采样，画面静止时可以少抽帧，画面变化剧烈时增加抽帧。音频轨道也会产生 token，因此仅用“时长 × 固定系数”不能做到完全精确。
如果希望得到准确数据，不要靠估算，直接在调用后打印 usage_metadata，观察输入 token 和输出 token 的实际变化。任何成本优化最终都要以线上实际统计为准。
6.3 检索命中不准时应如何调整
Agentic Video 类方案中，检索环节决定了最终效果上限。如果返回的相关片段并不是用户真正想问的部分，要从下面几个角度排查。
一是检查索引阶段抽帧间隔是否过大。事件只持续 5 秒，索引却每 30 秒才抽一帧，很可能完全没有记录到该事件。
二是检查索引中的视频描述是否过于笼统。“一位演讲者在台上讲解技术”这类描述无法支撑后续检索，需要提示模型在索引阶段输出更具体的实体、动作和时间点。
三是检查用户问题与索引摘要之间的语义匹配方式。如果只做文本相似度匹配，很容易漏掉“模型架构”“数据库选型”等抽象概念和画面内容之间的间接关系。此时可以先把用户问题改写成多个检索子问题，再对每个子问题分别检索。
6.4 如何避免生产环境出现成本失控
生产环境不是功能演示，费用上限一定要提前设计好。可以在 API 调用层封装一层计数器，每轮请求结束后记录累计 token，当同一用户超过预算阈值时，自动切换到纯文本摘要问答模式，不再调用视频理解模型。
另一个建议是建立不同层级的视频缓存策略。视频索引缓存保留多久、局部高帧片段是否需要存储、字幕文件的复用周期，都要和业务场景结合考虑。
7. 总结
说实话，Agentic Video 这次最值得关注的地方不是某一个 API 接口，而是它背后的工程范式变化：视频 API 不再鼓励开发者把整段视频一次性塞进上下文，而是引导开发者用 Agent 的规划能力，让模型在“理解全局”和“只读局部”之间找到平衡点。
对于做视频问答、视频知识库、自动化视频摘要的开发者来说，这是一个明确的信号。我们可以把这些思想迁移到自己项目中：先对视频做一次低成本的语义索引，然后在每次提问时只检索并细看相关片段，避免重复消耗全量 token。88% 这个数字不会适用于所有场景，但“先索引后精读”的思路，在长视频领域基本是长期正确的方向。
实际动手时，建议先用一小段带有明确事件的视频做对比实验，统计完整送入方案和两阶段方案各自的 token 差异和回答质量。不要一开始就追求复杂架构，先把索引构建、片段定位、局部推理这三步跑通，再逐步加入缓存、异步队列和降级策略。
如果你正在做视频类大模型应用，可以把这套方案作为自己降低成本的第一版参考。如果文章中有任何 API 细节与你使用的版本不一致，以你当前的官方文档为准，毕竟这类产品的迭代速度确实很快。
