结论先说
- 三种传视频方式按体积和来源选:小于
20 MB的极短片段可内联字节直传;本地长视频走 Files API 上传(单文件最大2 GB,必须等状态变成ACTIVE才能提问);已在 YouTube 公开发布的视频直接传file_uri链接,免下载免上传。 - 提问和输出时间戳统一用
MM:SS格式:比如问「02:15到03:40展示了什么」,或要求模型按MM:SS列出关键画面切换点。 - 只看局部片段就配
video_metadata裁剪:通过start_offset、end_offset和抽帧率fps,只为实际截取的那几分钟付 token 费。 - 默认每秒视频约合
258–300 token:折合一分钟约1.8 万 token;长视频把media_resolution调成低档(low)后可降到每秒约100 token。 - 谷歌账号准备与多工具订阅入口:使用 Gemini、Google AI Studio 与 Antigravity 需具备符合地区与年龄要求的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 的 谷歌邮箱成品号),跨平台付费订阅总览见 AI 会员充值中心。

图:本站根据 Gemini API 官方文档:Video understanding 整理的示意图
本文根据 Google AI for Developers 官方文档《Video understanding》《Files API》《Gemini Developer API pricing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想用 Gemini API 自动给会议录像、网课或演示视频生成带
MM:SS时间戳的章节摘要与字幕的开发者; - 搜「gemini api 视频理解 youtube」,想知道怎么不下载视频直接把公开 YouTube 网址喂给模型分析的人;
- 传大视频报
FAILED_PRECONDITION,或想提前算清一小时视频到底消耗多少 token 的人。
一、本地长视频上传(Files API)与必等的 ACTIVE 状态
先确认已装好 google-genai SDK 并配置密钥(准备步骤见 Gemini API Python 调用入门 与 Gemini API Key 获取教程)。总请求超过 20 MB 时,官方要求先调 client.files.upload。
新手最常踩的坑是刚上传完立刻发生成请求报 400 FAILED_PRECONDITION:视频上传后后台要做抽帧预处理,状态先处于 PROCESSING,必须轮询到 ACTIVE 才能喂给模型:
python
import time
from google import genai
client = genai.Client()
video_file = client.files.upload(file="demo_meeting.mp4")
while video_file.state.name == "PROCESSING":
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name != "ACTIVE":
raise RuntimeError(f"视频处理失败,状态:{video_file.state.name}")
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=[
video_file,
"按 MM:SS 时间戳列出核心议题切换点,并总结 01:20 处的结论。",
],
)
print(response.text)
官方提示:请把视频对象放在 contents 列表最前面,文字提问放在后面;Files API 托管文件默认保留 48 小时 后自动清理,不需要继续复用的敏感录像也可以主动调 client.files.delete(name=video_file.name) 立即删除。如果你的视频只有几秒钟、连同提示词整包体积小于 20 MB,也可以跳过上传步骤,直接用 types.Part.from_bytes(data=video_bytes, mime_type="video/mp4") 内联传入,省去轮询等待时间。
二、免下载直传 YouTube 链接与片段裁剪(video_metadata)
目标视频在 YouTube 上且权限为公开(Public)时,直接用 FileData 传网址即可。若只看局部几分钟,或视频是翻页很慢的网课,可用 VideoMetadata 指定起止秒数与每秒抽帧数(fps):
python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=types.Content(
parts=[
types.Part(
file_data=types.FileData(file_uri="https://www.youtube.com/watch?v=9hE5-98ZeCg"),
video_metadata=types.VideoMetadata(start_offset="30s", end_offset="150s", fps=0.5),
),
types.Part(text="总结这 2 分钟片段的操作步骤,标出每步对应的 MM:SS 时间点。"),
]
),
)
print(response.text)
使用 YouTube 直传需遵守三条官方限制:
- 只支持公开视频:私享(Private)与不公开列出(Unlisted)链接无法读取;
- 免费层每日时长上限:API 免费层每天累计最多解析 8 小时 YouTube 视频,开通付费层后解除该每日时长上限;
- 抽帧率调节技巧:默认按
1 FPS采样并同步读取音轨。快速动作视频可把fps调高到2至5防漏帧;静态讲座调低到0.5可节省大量视觉 token。
三、视频 token 换算规则与报错排查

图:本站根据 Gemini API 官方文档:Video understanding 整理的排错与省费示意图
把长视频塞进模型前,建议先按官方口径估算开销,避免一次请求把每分钟 token 限额(TPM)打满:
| 分辨率与抽帧设置 | 每秒约占 token | 10 分钟约占 | 1 小时约占 | 适用场景 |
|---|---|---|---|---|
| 默认分辨率(1 FPS + 音频) | 约 258–300 | 约 16 万–18 万 | 约 95 万–108 万 | 需看清画面小字、代码框或精细动作的视频 |
低分辨率(low)(1 FPS + 音频) | 约 100 | 约 6 万 | 约 36 万 | 长篇访谈、大屏演示、两三小时录像塞进百万窗口 |
超一小时的长视频,建议在 GenerateContentConfig 里把 media_resolution 设为低分辨率(MEDIA_RESOLUTION_LOW)或降低 fps 分段处理;此外新版高级模型还支持可选的智能体视频理解模式(Agentic video understanding),允许模型先检索时间轴与转写文本、再按需拉取关键时刻的高清帧,从而大幅压低超长视频的输入成本。各模型输入单价与限流处理详见 Gemini API 官方价格表 与 Gemini API 429 限流报错排查。若需准备个人 Google 账号登录 AI Studio 先免费拖入视频测试,可查看本站 谷歌账号购买说明 或访问 充值服务总览。
常见问题
问:Gemini API 解析视频时只看画面,还是连说话声音一起听?
答:画面和音轨会同时读取。即使视频没有内嵌字幕,模型也能听懂口播内容并结合画面标出对应时间戳。
问:为什么模型给出的时间戳偶尔有一两秒偏差?
答:因为默认按每秒 1 帧(1 FPS)抽样。若某个快闪镜头只持续半秒,恰好落在两帧之间就会有秒级误差;卡点要求高的短视频可在 VideoMetadata 把 fps 设成 2 或更高。
问:能把正在直播的 YouTube Live 链接传进这个接口吗?
答:标准 generateContent 接口面向已定长的点播或录制视频;实时画面流交互请改用 Gemini Live API(或 AI Studio 的 Stream Realtime 模式)。
问:没有可用的个人谷歌账号,或者同时想开其他主流 AI 会员怎么办?
答:本站提供即买即发的 谷歌邮箱成品号(登录方法见 谷歌账号购买页),同时支持支付宝、微信支付与 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服务,实时价格与质保细则以各商品页说明为准。
相关教程
- Gemini API Python 调用教程:安装 SDK、流式输出与多模态输入
- Gemini API 免费额度是多少:免费层级与 TPM 速率限制查询
- Gemini API 429 错误怎么解决:RESOURCE_EXHAUSTED 与 400 排查
- Google AI Studio 怎么用:先在网页端上传文件调试再导出代码
参考资料
- Gemini API 官方文档:Video understanding — https://ai.google.dev/gemini-api/docs/video-understanding
- Gemini API 官方文档:Files API — https://ai.google.dev/gemini-api/docs/files
- Gemini Developer API pricing — https://ai.google.dev/gemini-api/docs/pricing
0 条评论
还没有评论,来抢沙发~