Gemini 中文指南
获取 API 密钥 ↗

视频理解

↓ 下载 Markdown

要了解视频生成,请参阅 Gemini Omni Flash 指导。

Gemini 模型可以处理视频,从而支持许多以前需要特定领域模型的前沿开发人员用例。 Gemini 的一些视觉功能包括:描述、分段和从视频中提取信息,回答有关视频内容的问题,以及引用视频中的特定时间戳。

您可以通过以下方式提供视频作为 Gemini 的输入:

输入法

最大尺寸

推荐用例

文件 API

20GB(付费)/2GB(免费)

大文件(100MB+)、长视频(10分钟以上)、可重复使用的文件。

云存储注册

2GB(每个文件,无存储限制)

大文件 (100MB+)、长视频 (10 分钟以上)、持久、可重复使用的文件。

内联数据

< 100MB

文件小(<100MB)、持续时间短(<1分钟)、一次性输入。

YouTube 网址

N/A

公开 YouTube 视频。

要了解其他文件输入方法,例如使用外部 URL 或 Google Cloud 中存储的文件,请参阅 文件输入方式 指导。

上传视频文件 #

以下代码下载示例视频,然后使用 Files API,等待处理完毕,然后使用上传的文件参考来总结视频。

python
  from google import genai

  client = genai.Client()

  myfile = client.files.upload(file="path/to/sample.mp4")

  response = client.models.generate_content(
      model="gemini-4-hydrogen", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
  )

  print(response.text)

要优化 token 效率和性能,请考虑使用 智能体视频处理.

当总请求大小(包括文件、文本提示、系统指令等)大于 20 MB、视频持续时间较长或打算在多个提示中使用相同视频时,请始终使用 Files API。文件 API 直接接受视频文件格式。

要了解有关使用媒体文件的更多信息,请参阅 Files API.

内嵌传递视频数据 #

您可以直接在请求中传递较小的视频,而不是使用文件 API 上传视频文件 generateContent。这适用于总请求大小低于 20MB 的较短视频。

以下是提供内嵌视频数据的示例:

python
  from google import genai
  from google.genai import types

  # Only for videos of size <20Mb
  video_file_name = "/path/to/your/video.mp4"
  video_bytes = open(video_file_name, 'rb').read()

  client = genai.Client()
  response = client.models.generate_content(
      model='gemini-4-hydrogen',
      contents=types.Content(
          parts=[
              types.Part(
                  inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
              ),
              types.Part(text='Please summarize the video in 3 sentences.')
          ]
      )
  )
  print(response.text)

传递 YouTube URL #

您可以将 YouTube URL 作为请求的一部分直接传递给 Gemini API,如下所示:

python
  from google import genai
  from google.genai import types

  client = genai.Client()
  response = client.models.generate_content(
      model='gemini-4-hydrogen',
      contents=types.Content(
          parts=[
              types.Part(
                  file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
              ),
              types.Part(text='Please summarize the video in 3 sentences.')
          ]
      )
  )
  print(response.text)

限制:

  • 对于免费套餐,您每天不能上传超过 8 小时的 YouTube 视频。
  • 对于付费套餐,视频长度没有限制。
  • 对于 Gemini 2.5, 之前的型号,您只能根据请求上传 1 视频。对于 Gemini 2.5 及更高版本,每个请求最多可以上传 10 视频。
  • 您只能上传公共视频(不能上传私有或不公开的视频)。

智能体视频理解 #

默认情况下,所有型号(包括 Gemini 4)的视频输入均使用静态处理(以 1 FPS 提取帧)。 Gemini 4 Carbon、Gemini 4 Argon、Gemini 4 Hydrogen、3.8 Flash、3.6 Flash 和 3.5 Flash Lite 型号还支持 智能体视频理解,一种选择加入模式,模型动态探索视频时间线,有选择地检查记录并根据提示动态自适应调整帧速率和分辨率。

模式说明支持的模型
静止的 (默认)以固定速率 (1 FPS) 提取帧并将其一次性放入上下文中。所有 Gemini 型号的默认设置,包括 Gemini 4。所有 Gemini 型号
智能体该模型动态导航视频时间线,根据提示仅加载所需的内容。最多88% 更多的token-高效和〜7% 长篇内容的质量更高。Gemini 4 Carbon、Gemini 4 Argon、Gemini 4 Hydrogen、3.8 Flash、3.6 Flash、3.5 Flash精简版

选择处理模式 #

选择与您的视频长度和查询类型匹配的处理模式:

  • 静态(默认): 最适合短剪辑(5 分钟以下)、整个录制相关的广泛的完整视频摘要、延迟敏感的查询或整个剪辑的帧级精度。在短视频或需要检查大部分视频的宽泛提示上,静态处理避免了额外的思考 token (thoughts_token_count)和工具调用往返(tool_use_prompt_token_count)由时间线导航引起。
  • 智能体: 最适合长视频(超过 5–10 分钟)、大海捞针检索或针对特定时刻或主题的查询。该模型首先检查文字记录,并根据需要仅加载相关的视觉片段,从而将视频输入 token 的使用量减少高达 88%,而无需填充上下文窗口。

设置处理模式 #

python
import time
from google import genai
from google.genai import types

client = genai.Client()

video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?"
    ]
)
print(response.text)

响应结构 #

启用智能体处理后,响应包括公开内部导航跟踪的其他部分:

  • tool_call 零件 (tool_type: "MEDIA_PROCESSING"):每次模型请求视频片段或音频脚本时发出。
  • tool_response 零件 (tool_type: "MEDIA_PROCESSING"):每次加载操作的结果。

您不需要手动处理或回复这些部分:将完整的响应作为对话历史记录传回,它们会自动处理。

如果 include_thoughts=True 设置于 ThinkingConfig,推理步骤显示为 thought: true 与工具调用/响应对交错的部分。禁用思想后,思想文本将被省略,但工具部分仍然存在。

以下示例显示了具有交错工具调用和响应部分的响应负载:

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

跨视频混合处理模式 #

您可以在同一个请求中为每个视频设置不同的处理模式:

python
from google import genai
from google.genai import types

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",
        ),
        "Compare the lecture content with the experiment results."
    ]
)
print(response.text)

使用上下文缓存拍摄长视频 #

对于长度超过 10 分钟的视频,或者当您计划对同一视频文件发出多个请求时,请使用 上下文缓存 以降低成本并改善延迟。上下文缓存可让您处理一次视频并重复使用 token 进行后续查询,使其成为聊天会话或长格式内容重复分析的理想选择。

参考内容中的时间戳 #

您可以使用以下形式的时间戳询问有关视频中特定时间点的问题 MM:SS.

python
response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        myfile,
        "What are the examples given at 00:05 and 00:10 supposed to show us?",
    ],
)
print(response.text)

从视频中提取详细见解 #

Gemini 型号通过处理来自以下两个方面的信息,提供了理解视频内容的强大功能: 音频和视频 溪流。这使您可以提取丰富的详细信息,包括生成视频中发生的情况的描述并回答有关其内容的问题。

对于视觉描述,模型以以下速率对视频进行采样 1 每秒帧数 (FPS)。此默认采样率适用于大多数内容,但请注意,它可能会错过快速运动或快速场景变化的视频中的细节。对于此类高动态内容,请考虑 设置自定义帧速率.

python
response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents=[
        myfile,
        "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
    ],
)
print(response.text)

自定义视频处理 #

您可以通过设置剪辑间隔或提供自定义帧速率采样来自定义 Gemini API 中的视频处理。仅在处理视频时才支持这些自定义选项 "static" 模式。

设置剪辑间隔 #

您可以通过指定来剪辑视频 videoMetadata 带有开始和结束偏移。

python
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-4-hydrogen',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

设置自定义帧速率 #

您可以通过传递一个来设置自定义帧速率采样 fps 论证 videoMetadata.

python
from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-4-hydrogen',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

默认情况下,从视频中采样 1 每秒帧数 (FPS)。您可能需要为长视频设置低 FPS (< 1)。这对于大多数静态视频(例如讲座)特别有用。对于需要精细时间分析(例如快速动作理解或高速运动跟踪)的视频,请使用更高的 FPS。

支持的视频格式 #

Gemini 支持以下视频格式 MIME 类型:

  • video/mp4
  • video/mpeg
  • video/quicktime
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

有关视频的技术细节 #

  • 支持的模型和上下文:所有Gemini型号都可以处理视频数据。 - 配备 1M 上下文窗口的型号默认可处理长达 3 小时的视频(在低媒体分辨率下),或在高媒体分辨率下处理长达 1 小时的视频。

  • 加工方式:Gemini 4 Carbon、Gemini 4 Argon、3.8 Flash、3.6 Flash、3.5 Flash Lite 及更高版本支持两种视频处理模式:- 静止的:在 1 FPS 中提取帧并将其放入上下文中(所有型号均默认)。音频以 1Kbps(单通道)处理。时间戳每秒添加一次。最适合短剪辑或每帧都很重要的情况(例如逐帧检查)。请注意,由于 1 FPS 采样率,快速动作序列可能会丢失细节。

    • 智能体:模型会动态浏览视频,按需加载转写文本、视频帧和音频。对于长视频内容,token 用量最多可减少 88%;但对于短片(不足 5 分钟)或宽泛查询,内部推理及工具往返可能增加首个 token 延迟(TTFT)和 token 总用量。响应包括 MEDIA_PROCESSING 工具调用和响应部分以保留各回合的推理上下文。最适合长视频和有针对性的查询,以优化 token 成本和响应质量。在 Gemini 4 Carbon、Gemini 4 Argon、3.8 Flash、3.6 Flash 和 3.5 Flash Lite 上受支持。参见 智能体视频理解 了解详情。
  • 代币计算(静态模式):视频的每一秒都按如下方式标记: - 各个帧(以 1 FPS 采样): - 如果 media_resolution 设置为低时,帧以每帧 66 token 标记。

    • 否则,帧将在每帧 258 token 处进行标记。

    • 音频:每秒 32 token。

    • 元数据也包括在内。

    • 总计:默认(低)媒体分辨率下每秒大约 100 token 视频,或高媒体分辨率下每秒大约 300 token 视频。

  • 代币计算(智能体模式):token的使用根据内容复杂性和模型的导航策略而变化。视频探索过程中生成的导航推理 token 计为 思考token (thoughts_token_count),而按需加载的帧、音频和文字记录则计为工具提示符 token(tool_use_prompt_token_count)。对于长格式内容,智能体处理通常比静态处理少使用最多 88% 的 token,因为模型仅加载回答提示所需的文字记录和/或帧和/或音频(请参阅 token指南).

  • 媒体分辨率:Gemini 3 引入了对多模态视觉处理的精细控制 media_resolution 参数。的 media_resolution 参数决定了 每个输入图像或视频帧分配的 token 的最大数量。 更高的分辨率可以提高模型读取精细文本或识别小细节的能力,但会增加 token 的使用率和延迟。的 media_resolution 和 media_processing 参数是独立的:您可以在同一个视频部件上设置这两个参数。

有关 token 计算的更多详细信息,请参阅 token 指导。

  • 时间戳格式:在提示中提及视频中的特定时刻时,请使用 MM:SS 格式(例如, 01:15 为 1 分钟和 15 秒)。
  • 及时安置:如果将文本和单个视频组合在一起,请放置文本提示 之后 视频部分在 contents 数组。
  • 长请求超时:对于需要延长处理时间或复杂的多步骤推理的视频,请使用流式传输(client.models.generate_content_stream)。在高需求下经历后端重试的同步、非流式请求可能会超出连接或身份验证 token 有效性窗口,这可能会表现为意外 401 Unauthorized 或超时错误。流式传输使连接保持活动状态并显示中间推理和工具调用进度。

后续步骤 #

  • 媒体分辨率:控制视频帧的分辨率以平衡质量和 token 使用情况。
  • token:了解如何在静态和智能体处理模式下对视频内容进行标记。
  • 系统指令:系统指令可让您根据您的特定需求和用例来控制模型的行为。
  • Files API:了解有关上传和管理用于 Gemini 的文件的更多信息。
  • 文件提示策略:Gemini API 支持文字、图片、音频、视频数据提示,也称为多模态提示。
  • 安全指导:有时生成式人工智能模型会产生意想不到的输出,例如不准确、有偏见或令人反感的输出。后处理和人工评估对于限制此类输出造成的危害风险至关重要。

搜索标题、API 名称或正文内容