视频理解

如需了解视频生成功能，请参阅 Gemini Omni Flash 指南。

Gemini 模型可以处理视频，从而实现许多前沿的开发者用例，而这些用例在过去需要使用特定领域的模型。 Gemini 的一些视觉功能包括：能够描述、分割和提取视频中的信息，回答有关视频内容的问题，以及引用视频中的特定时间戳。

您可以通过以下方式向 Gemini 提供视频输入：

输入法 最大大小 推荐的使用场景
文件 API 20 GB（付费）/ 2 GB（免费） 大文件（100MB 以上）、长视频（10 分钟以上）、可重复使用的文件。
Cloud Storage 注册 2 GB（每个文件，无存储空间限制） 大型文件（100MB 以上）、长视频（10 分钟以上）、持久性可重用文件。
内嵌数据 < 100MB 小型文件（<100MB）、短时长（<1 分钟）、一次性输入。
YouTube 网址 不适用 公开 YouTube 视频。

注意：建议在大多数使用情形下使用文件 API，尤其是当文件大于 100MB 或您想在多个请求中重复使用文件时。

如需了解其他文件输入方法（例如使用外部网址或存储在 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-3.8-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", nil)

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)

fmt.Println(result.Text())

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2> /dev/null > response.json

jq -r ".candidates[].content.parts[].text" response.json

如需优化令牌效率和性能，请考虑使用智能体视频处理。

如果总请求大小（包括文件、文本提示、系统指令等）超过 20 MB、视频时长较长，或者您打算在多个提示中使用同一视频，请务必使用 Files API。File API 直接接受视频文件格式。

如需详细了解如何处理媒体文件，请参阅 Files API。

以内嵌方式传递视频数据

您可以直接在对 generateContent 的请求中传递较小的视频，而无需使用 File API 上传视频文件。此方法适用于总请求大小不超过 20 MB 的较短视频。

下面是一个提供内嵌视频数据的示例：

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-3.8-flash',
    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)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2> /dev/null

传递 YouTube 网址

您可以将 YouTube 网址直接传递给 Gemini API，作为请求的一部分，如下所示：

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    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)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const contents = [
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  parts := []*genai.Part{
      genai.NewPartFromText("Please summarize the video in 3 sentences."),
      genai.NewPartFromURI("https://www.youtube.com/watch?v=9hE5-98ZeCg","video/mp4"),
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2> /dev/null

限制：

  • 对于免费层级，您每天上传的 YouTube 视频时长不得超过 8 小时。
  • 对于付费层级，没有视频时长限制。
  • 对于 Gemini 2.5 之前的模型，您每次请求只能上传 1 个视频。对于 Gemini 2.5 及更高版本的模型，您每次请求最多能上传 10 个视频。
  • 您只能上传公开视频（不能上传私享视频或未公开列出的视频）。

智能体视频理解

默认情况下，视频输入使用静态处理（以 1 FPS 的速率提取帧）。 Gemini 3.8 Flash、3.7 Flash、3.6 Flash 和 3.5 Flash Lite 模型还支持自主视频理解，即模型会动态探索视频时间轴，根据提示有选择地检查转写内容，并实时自适应地调整帧速率和分辨率。

Mode 说明 支持的模型
静态（默认） 以固定速率 (1 FPS) 提取帧，并在一次遍历中将它们放入上下文中。非常适合短视频。 所有 Gemini 模型
智能体 该模型会根据提示动态浏览视频时间轴，仅加载所需的内容。在长篇内容方面，token 效率最高可提升 88%，质量最高可提升约 7%。 Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.5 Flash Lite

选择处理模式

一般来说，建议您从智能体模式开始，尤其是在优化回答质量或令牌效率时。

  • Agentic：长视频或针对特定时刻的查询。模型会动态浏览时间轴，以定位与上下文相关的信息，而不会填满上下文窗口。
  • 静态：对短视频片段（5 分钟以内）进行延迟敏感型查询，或者需要整个视频片段达到帧级精度的情形。

注意：对于长视频或需要智能体处理时间较长的复杂提示，请使用流式传输 (client.models.generate_content_stream)。这样可以保持连接处于活动状态，显示中间推理步骤，并避免连接或身份验证超时。

设置处理模式

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-3.8-flash",
    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)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" },
});

while (videoFile.state === "PROCESSING") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        FileData: &genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

注意：如需验证是否使用了代理处理，请检查 response.candidates[0].content.parts。如果存在 MEDIA_PROCESSING 工具类型的 tool_call 和 tool_response 部分，则表示模型动态浏览了视频。

注意：与其他服务器端工具（例如 Google 搜索或网址上下文）不同，代理视频不需要在 ToolConfig 中设置 include_server_side_tool_invocations=True，即可返回或流式传输工具调用和结果。当任何输入部分设置了 media_processing="AGENTIC" 时，系统会自动返回用于视频导航的 tool_call 和 tool_response 部分。

响应结构

启用智能体处理后，回答中会包含用于显示内部导航轨迹的其他部分：

  • tool_call parts (tool_type: "MEDIA_PROCESSING")：每次模型请求视频片段或音频转写时都会发出。
  • tool_response parts (tool_type: "MEDIA_PROCESSING")：每次加载操作的结果。

您无需手动处理或回复这些部分：将完整响应作为对话历史记录传递回去，系统会自动处理这些部分。

如果在 ThinkingConfig 中设置了 include_thoughts=True，推理步骤将显示为 thought: true 部分，与工具调用/响应对交织在一起。停用思考功能后，系统会省略思考文本，但仍会显示工具部分。

以下示例展示了包含交错的工具调用和响应部分的响应载荷：

{
  "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-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" },
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Go

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

针对长视频使用上下文缓存

对于时长超过 10 分钟的视频，或者当您计划针对同一视频文件发出多个请求时，请使用上下文缓存来降低费用并缩短延迟时间。借助上下文缓存，您可以处理一次视频，然后将 token 重用于后续查询，非常适合聊天会话或对长篇内容进行重复分析。

参考内容中的时间戳

您可以使用 MM:SS 格式的时间戳，针对视频中的特定时间点提出问题。

Python

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

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "What are the examples given at 00:05 and 00:10 supposed to show us?",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("What are the examples given at 00:05 and 00:10 supposed to show us?"),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "What are the examples given at 00:05 and 00:10 supposed to show us?"}
        ]
      }]
    }' 2> /dev/null

从视频中提取详细的分析洞见

Gemini 模型能够处理音频和视频流中的信息，从而提供强大的视频内容理解能力。这样一来，您就可以提取丰富的细节信息，包括生成视频内容的说明和回答与视频内容相关的问题。

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

Python

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

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
        "Include timestamps for salient moments."),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."}
        ]
      }]
    }' 2> /dev/null

自定义视频处理

您可以在 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-3.8-flash',
    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.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

设置自定义帧速率

您可以通过向 videoMetadata 传递 fps 实参来设置自定义帧速率选段。

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-3.8-flash',
    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.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const myfile = await ai.files.upload({
  file: "path/to/sample.mp4",
  mimeType: "video/mp4",
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      fileData: {
        fileUri: myfile.uri,
        mimeType: myfile.mimeType,
      },
      videoMetadata: {
        fps: 5,
      },
    },
    "Please summarize the video in 3 sentences.",
  ],
});

console.log(response.text);

默认情况下，系统会按 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 模型都可以处理视频数据。
    • 上下文窗口为 100 万个 token 的模型默认可以处理时长不超过 3 小时（低媒体分辨率）或 1 小时（高媒体分辨率）的视频。
  • 处理模式：Gemini 3.8 Flash、3.7 Flash、3.6 Flash、3.5 Flash Lite 及更新型号支持两种视频处理模式：
    • 静态：以 1 FPS 的速率提取帧并将其放入上下文（所有模型的默认设置）。音频的处理速率为 1Kbps（单声道）。每秒都会添加时间戳。最适合短视频片段或需要关注每一帧的场景（例如逐帧检查）。请注意，如果选段率为 1 FPS，快速动作序列可能会丢失细节。
    • Agentic：模型会动态浏览视频，并根据需要加载转写内容和/或帧和/或音频。这样一来，长篇内容的令牌用量最多可减少 88%，不过，由于在开始生成之前需要进行内部推理和工具往返，因此导航可能会略微增加短视频（时长不到 5 分钟）的首次令牌时间 (TTFT)。响应包括 MEDIA_PROCESSING 工具调用和响应部分，以在对话轮次之间保留推理上下文。最适合长视频，可优化令牌费用和回答质量。支持 Gemini 3.8 Flash、3.7 Flash、3.6 Flash 和 3.5 Flash Lite。如需了解详情，请参阅智能体视频理解。
  • token 计算（静态模式）：视频的每一秒都按如下方式计算 token：
    • 各帧（选段率为 1 FPS）：
      • 如果 media_resolution 设置为低，则每帧按 66 个 token 计算。
      • 否则，每帧按 258 个 token 计算。
    • 音频：每秒 32 个 token。
    • 元数据也包含在内。
    • 总计：默认（低）媒体分辨率下，每秒视频大约需要 100 个 token；高媒体分辨率下，每秒视频大约需要 300 个 token。
  • 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)。在高需求下，同步非流式传输请求会经历后端重试，这可能会超出连接或身份验证令牌有效性窗口，从而导致意外的 401 Unauthorized 或超时错误。流式传输可保持连接处于活动状态，并显示中间推理和工具调用进度。

后续步骤

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