视频理解
要了解视频生成,请参阅 Gemini Omni Flash 指导。
Gemini 模型可以处理视频,从而支持许多以前需要特定领域模型的前沿开发人员用例。 Gemini 的一些视觉功能包括:描述、分段和从视频中提取信息,回答有关视频内容的问题,以及引用视频中的特定时间戳。
您可以通过以下方式提供视频作为 Gemini 的输入:
输入法 | 最大尺寸 | 推荐用例 |
|---|---|---|
20GB(付费)/2GB(免费) | 大文件(100MB+)、长视频(10分钟以上)、可重复使用的文件。 | |
2GB(每个文件,无存储限制) | 大文件 (100MB+)、长视频 (10 分钟以上)、持久、可重复使用的文件。 | |
< 100MB | 文件小(<100MB)、持续时间短(<1分钟)、一次性输入。 | |
N/A | 公开 YouTube 视频。 |
要了解其他文件输入方法,例如使用外部 URL 或 Google Cloud 中存储的文件,请参阅 文件输入方式 指导。
上传视频文件 #
以下代码下载示例视频,然后使用 Files API,等待处理完毕,然后使用上传的文件参考来总结视频。
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)
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-4-hydrogen",
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();
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-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
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-4-hydrogen: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
要优化 token 效率和性能,请考虑使用 智能体视频处理.
当总请求大小(包括文件、文本提示、系统指令等)大于 20 MB、视频持续时间较长或打算在多个提示中使用相同视频时,请始终使用 Files API。文件 API 直接接受视频文件格式。
要了解有关使用媒体文件的更多信息,请参阅 Files API.
内嵌传递视频数据 #
您可以直接在请求中传递较小的视频,而不是使用文件 API 上传视频文件 generateContent。这适用于总请求大小低于 20MB 的较短视频。
以下是提供内嵌视频数据的示例:
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)
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-4-hydrogen",
contents: contents,
});
console.log(response.text);
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-4-hydrogen: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 URL #
您可以将 YouTube URL 作为请求的一部分直接传递给 Gemini API,如下所示:
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)
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-4-hydrogen",
contents: contents,
});
console.log(response.text);
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-4-hydrogen",
contents,
nil,
)
fmt.Println(result.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen: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
限制:
- 对于免费套餐,您每天不能上传超过 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%,而无需填充上下文窗口。
设置处理模式 #
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)
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-4-hydrogen",
contents: [
{
fileData: {
fileUri: videoFile.uri,
mimeType: videoFile.mimeType,
},
mediaProcessing: "AGENTIC"
},
{ text: "What are the three main arguments presented?" }
]
});
console.log(response.text);
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
videoFile, err := client.Files.Upload(ctx, "path/to/lecture.mp4", nil)
if err != nil {
log.Fatal(err)
}
part := genai.NewPartFromURI(videoFile.URI, videoFile.MIMEType)
part.MediaProcessing = genai.MediaProcessingAgentic
contents := []*genai.Content{
genai.NewContentFromParts([]*genai.Part{
part,
genai.NewPartFromText("What are the three main arguments presented?"),
}, genai.RoleUser),
}
result, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{
"file_data": {
"file_uri": "'${file_uri}'",
"mime_type": "video/mp4"
},
"media_processing": "AGENTIC"
},
{"text": "What are the three main arguments presented?"}
]
}]
}' 2> /dev/null
响应结构 #
启用智能体处理后,响应包括公开内部导航跟踪的其他部分:
tool_call零件 (tool_type: "MEDIA_PROCESSING"):每次模型请求视频片段或音频脚本时发出。tool_response零件 (tool_type: "MEDIA_PROCESSING"):每次加载操作的结果。
您不需要手动处理或回复这些部分:将完整的响应作为对话历史记录传回,它们会自动处理。
如果 include_thoughts=True 设置于 ThinkingConfig,推理步骤显示为 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"
}
]
}
}
]
}
跨视频混合处理模式 #
您可以在同一个请求中为每个视频设置不同的处理模式:
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)
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-4-hydrogen",
contents: [
{
fileData: {
fileUri: lecture.uri,
mimeType: lecture.mimeType,
},
mediaProcessing: "AGENTIC"
},
{
fileData: {
fileUri: experiment.uri,
mimeType: experiment.mimeType,
},
mediaProcessing: "STATIC"
},
{ text: "Compare the lecture content with the experiment results." }
]
});
console.log(response.text);
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
lecture, _ := client.Files.Upload(ctx, "path/to/long-lecture.mp4", nil)
experiment, _ := client.Files.Upload(ctx, "path/to/short-experiment.mp4", nil)
lecturePart := genai.NewPartFromURI(lecture.URI, lecture.MIMEType)
lecturePart.MediaProcessing = genai.MediaProcessingAgentic
experimentPart := genai.NewPartFromURI(experiment.URI, experiment.MIMEType)
experimentPart.MediaProcessing = genai.MediaProcessingStatic
contents := []*genai.Content{
genai.NewContentFromParts([]*genai.Part{
lecturePart,
experimentPart,
genai.NewPartFromText("Compare the lecture content with the experiment results."),
}, genai.RoleUser),
}
result, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-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."}
]
}]
}' 2> /dev/null
使用上下文缓存拍摄长视频 #
对于长度超过 10 分钟的视频,或者当您计划对同一视频文件发出多个请求时,请使用 上下文缓存 以降低成本并改善延迟。上下文缓存可让您处理一次视频并重复使用 token 进行后续查询,使其成为聊天会话或长格式内容重复分析的理想选择。
参考内容中的时间戳 #
您可以使用以下形式的时间戳询问有关视频中特定时间点的问题 MM:SS.
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)
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: [
myfile,
"What are the examples given at 00:05 and 00:10 supposed to show us?",
],
});
console.log(response.text);
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-4-hydrogen",
[]*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
nil,
)
fmt.Println(result.Text())
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen: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)。此默认采样率适用于大多数内容,但请注意,它可能会错过快速运动或快速场景变化的视频中的细节。对于此类高动态内容,请考虑 设置自定义帧速率.
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)
const response = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: [
myfile,
"Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
],
});
console.log(response.text);
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-4-hydrogen",
[]*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
nil,
)
fmt.Println(result.Text())
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen: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 带有开始和结束偏移。
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.')
]
)
)
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-4-hydrogen';
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();
设置自定义帧速率 #
您可以通过传递一个来设置自定义帧速率采样 fps 论证 videoMetadata.
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.')
]
)
)
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-4-hydrogen",
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/mp4video/mpegvideo/quicktimevideo/avivideo/x-flvvideo/mpgvideo/webmvideo/wmvvideo/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 上受支持。参见 智能体视频理解 了解详情。
- 智能体:模型会动态浏览视频,按需加载转写文本、视频帧和音频。对于长视频内容,token 用量最多可减少 88%;但对于短片(不足 5 分钟)或宽泛查询,内部推理及工具往返可能增加首个 token 延迟(TTFT)和 token 总用量。响应包括
代币计算(静态模式):视频的每一秒都按如下方式标记: - 各个帧(以 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或超时错误。流式传输使连接保持活动状态并显示中间推理和工具调用进度。