Gemini视频分析教程：使用Gemini 2.0理解视频

本教程面向有编程基础的开发者，深入讲解如何使用 Gemini 2.0 进行视频理解。通过实际代码示例，展示如何利用 Gemini 的多模态能力和长上下文窗口，实现视频搜索、文本提取、结构化信息分析、屏幕录制分析以及 YouTube 视频分析。教程涵盖环境搭建、API 使用、视频上传与处理，并探讨自定义视频预处理等高级功能，帮助开发者快速掌握 Gemini 在视频分析领域的工程实践。

技术背景

传统视频分析依赖人工或复杂的计算机视觉流水线，难以处理长视频和复杂语义。Gemini 作为原生多模态模型，具备长上下文窗口，能直接理解视频中的视觉、音频和文本信息，简化了视频分析流程。适用于内容审核、用户研究、教育、媒体检索等场景。主要限制包括视频大小和处理时间，以及 API 调用成本。

核心原理

Gemini 模型通过将视频分解为帧序列，结合音频和文本信息，利用 Transformer 架构的注意力机制，在长上下文窗口内进行联合推理。视频上传后，File API 将其处理为可访问的 URI，模型通过 Interactions API 接收视频 URI 和文本提示，生成结构化输出。核心设计决策包括：使用统一的 API 处理多种媒体类型，通过提示词控制输出格式，以及支持自定义预处理（如剪辑间隔和帧率）以优化分析。

架构分析

系统架构包括客户端 SDK、Gemini API 和 File API。客户端通过 API 密钥初始化，上传视频至 File API 获取 URI，然后通过 Interactions API 发送包含视频 URI 和文本提示的请求。模型处理视频并返回文本响应。组件关系：SDK 封装 API 调用，File API 管理视频存储与处理，Interactions API 提供交互式对话能力。设计思想强调模块化和灵活性，允许开发者通过不同提示词实现多种分析任务，并支持自定义预处理以适配不同场景。

完整实战教程

#@title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

使用 Gemini 进行视频理解

Gemini 从一开始就是一个多模态模型，能够利用其长上下文窗口分析各种媒体。

Gemini 模型将视频分析提升到了一个全新的水平，如此视频所示。

注意： 本笔记本使用 Interactions API，这是与 Gemini 模型交互的最新方式。正在寻找 generateContent 版本？请查看归档分支。

本笔记本将向您展示如何轻松使用 Gemini 执行同样的视频分析。每个分析都有不同的提示，您可以通过下拉菜单选择，也欢迎您尝试自己的提示。

您还可以查看在线演示，并在 AI Studio 上对您自己的视频进行尝试。

设置

本部分将安装 SDK，使用你的 API 密钥进行设置，导入相关库，下载示例视频并将其上传到 Gemini。

如果你好奇，可以展开此部分，但也可以直接运行（由于包含大文件，可能需要几分钟），然后直接进入示例。

安装 SDK

%pip install -U -q "google-genai>=2.9.0"

设置你的 API 密钥

要运行以下单元格，你的 API 密钥必须存储在名为 GEMINI_API_KEY 的 Colab Secret 中。如果你还没有 API 密钥，或者不确定如何创建 Colab Secret，请参阅身份验证获取详细指南。

from google.colab import userdata

GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')

初始化 SDK 客户端

使用新版 SDK，你现在只需使用 API 密钥（或如果使用 Vertex AI 则使用 OAuth）初始化一个客户端即可。模型现在在每次调用中设置。

from google import genai
from google.genai import types

client = genai.Client(api_key=GEMINI_API_KEY)

选择 Gemini 模型

选择您想要用于视频理解的 Gemini 模型。

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

获取示例视频

你将先从上传的视频开始，因为这是一个更常见的用例，但你稍后也会看到，你也可以使用 YouTube 视频。

# Load sample images
!wget assets/images/2641f230233fd687.mp4 -O Pottery.mp4 -q
!wget assets/images/1dfdbe1a0dc3e93.mp4 -O Trailcam.mp4 -q
!wget assets/images/5067f19533bd8b27.mp4 -O Post_its.mp4 -q
!wget assets/images/f3449d578739fe89.mp4 -O User_study.mp4 -q

上传视频

使用 File API 上传所有视频。你可以在 Get Started 笔记本中找到关于如何使用它的更多详细信息。

由于视频需要处理和分词，这可能需要几分钟时间。

import time

def upload_video(video_file_name):
  video_file = client.files.upload(file=video_file_name)

  while video_file.state == "PROCESSING":
      print('Waiting for video to be processed.')
      time.sleep(10)
      video_file = client.files.get(name=video_file.name)

  if video_file.state == "FAILED":
    raise ValueError(video_file.state)
  print(f'Video processing complete: ' + video_file.uri)

  return video_file

pottery_video = upload_video('Pottery.mp4')
trailcam_video = upload_video('Trailcam.mp4')
post_its_video = upload_video('Post_its.mp4')
user_study_video = upload_video('User_study.mp4')

导入

import json
from PIL import Image
from IPython.display import display, Markdown, HTML

在视频中搜索

首先，尝试使用模型在您的视频中进行搜索，并描述 trailcam 视频中所有动物目击情况。

prompt = "For each scene in this video, generate captions that describe the scene along with any spoken text placed in quotation marks. Place each caption into an object with the timecode of the caption in the video."  # @param ["For each scene in this video, generate captions that describe the scene along with any spoken text placed in quotation marks. Place each caption into an object with the timecode of the caption in the video.", "Organize all scenes from this video in a table, along with timecode, a short description, a list of objects visible in the scene (with representative emojis) and an estimation of the level of excitement on a scale of 1 to 10"] {"allow-input":true}

video = trailcam_video # @param ["trailcam_video", "pottery_video", "post_its_video", "user_study_video"] {"type":"raw","allow-input":true}

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": video.uri},
        {"type": "text", "text": prompt},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

这里使用的提示词相当通用，但如果你根据自己的需求进行定制（比如专门要求狐狸），可以获得更好的结果。

AI Studio 上的实时演示展示了如何通过后处理此输出，点击时间码直接跳转到视频的特定部分。如果你感兴趣，可以查看 GitHub 上该演示的代码。

提取并整理文本

Gemini 模型还能读取视频中的内容，并以有条理的方式提取出来。你甚至可以利用 Gemini 的推理能力为你生成新的想法。

prompt = "Transcribe the sticky notes, organize them and put it in a table. Can you come up with a few additional user stories of your own?"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": post_its_video.uri},
        {"type": "text", "text": prompt},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

结构信息

Gemini 不仅能够读取文本，还能对现实世界中的物体进行推理和结构化处理。就像这段关于展示带有手写价格和备注的陶瓷制品的视频一样。

prompt = "Give me a table of my items and notes" # @param ["Give me a table of my items and notes", "Is this a house or an office?", "Give me a list of all the items you can see there, with their descriptions"] {"allow-input":true}

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": user_study_video.uri},
        {"type": "text", "text": prompt},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

如你所见，Gemini 能够理解每个音符对应的物品，包括最后一个。

分析屏幕录制以捕捉关键时刻

您还可以使用模型来分析屏幕录制。假设您正在进行关于用户如何使用您的产品的用户研究，因此您最终会得到许多屏幕录制，例如这一个，您必须手动梳理。

只需一个提示，模型就可以描述视频中的所有操作。

prompt = "Generate a paragraph that summarizes this video. Keep it to 3 to 5 sentences with corresponding timestamps"

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": pottery_video.uri},
        {"type": "text", "text": prompt},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

分析 YouTube 视频

除了使用你自己的视频，你还可以让 Gemini 从 YouTube 获取视频并进行分析。下面是一个使用 Google IO 2023 主题演讲的例子。猜猜主题是什么？

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "Find all the instances where Sundar says \"AI\". Provide timestamps and broader context for each instance."},
        {"type": "video", "uri": "https://www.youtube.com/watch?v=ixRanV-rdAQ"},
    ],
)

Markdown(interaction.steps[-1].content[0].text)

自定义视频预处理

Gemini API 允许您定义一些预处理步骤，以增强您理解和提取视频信息的能力。

您可以使用剪辑间隔（或定义时间偏移以专注于特定视频部分）和自定义 FPS（以定义将考虑多少帧来分析视频）。

有关这些功能的更多详细信息，请参阅 Gemini API 文档中的自定义视频预处理。

自定义视频预处理

注意： 视频元数据功能（剪辑间隔和帧率配置）在 Interactions API 中尚不可用。

后续步骤

使用 AI Studio 的实时演示尝试您自己的视频，或使用本笔记本中的示例进行尝试（如果您还没有看到，下拉菜单中还有其他提示可以尝试）。

有关 Gemini 功能的更多示例，请查看 Cookbook 中的其他指南。您将学习如何使用 Live API、处理多个工具或使用 Gemini 的空间理解能力。

Cookbook 中的 examples 文件夹也充满了很好的代码示例，展示了使用 Gemini 多模态功能和长上下文的创造性方法。

常见问题

常见错误包括：API 密钥未设置或无效，导致认证失败；视频上传后状态为 FAILED，可能是文件格式不支持或大小超限；处理时间过长，可检查网络或视频大小。排查方法：确认环境变量 GEMINI_API_KEY 已正确设置；检查视频文件是否损坏或格式正确；查看 API 返回的错误信息。生产环境优化：使用异步上传和处理，避免阻塞；对视频进行压缩或剪辑以减少处理时间；利用缓存机制避免重复上传；合理设置模型参数以平衡质量和成本。

企业应用扩展

可扩展方向：结合 Gemini 的空间理解能力，实现更精细的视频内容分析；利用 Live API 进行实时视频流处理；集成多个工具（如搜索、代码执行）构建复杂工作流；开发自定义预处理模块，如人脸识别、物体跟踪；将视频分析结果用于自动化内容生成、摘要和推荐系统。

总结

内容来源与验证

内容等级：PREMIUM_A
质量等级：S_CANDIDATE
难度：初级
验证等级：V1
原文作者：
原文日期：
来源许可：Apache-2.0
来源版本：c6b9eb7b4dcf4e46e68636e7c81abcbf68b1a3ed
查看原文

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员