Видео понимание

Чтобы узнать больше о создании видео, ознакомьтесь с руководством по Gemini Omni Flash .

Модели Gemini способны обрабатывать видео, что открывает множество новых возможностей для разработчиков, которые ранее требовали использования специализированных моделей. К числу возможностей Gemini в области компьютерного зрения относятся: описание, сегментация и извлечение информации из видео, ответы на вопросы о содержании видео и указание на конкретные временные метки в видео.

Вы можете предоставлять видеоматериалы для Gemini следующими способами:

Метод ввода Максимальный размер Рекомендуемый вариант использования
Файловый API 20 ГБ (платно) / 2 ГБ (бесплатно) Большие файлы (100 МБ и более), длинные видеоролики (10 мин и более), файлы для многократного использования.
Регистрация в облачном хранилище 2 ГБ (на файл, без ограничений по объему хранилища) Большие файлы (100 МБ и более), длинные видеоролики (10 мин и более), файлы, сохраняемые и используемые повторно.
Встроенные данные < 100 МБ Небольшие файлы (<100 МБ), короткая продолжительность (<1 мин), одноразовые входные данные.
URL-адреса YouTube Н/Д Общедоступные видео на YouTube.

Примечание: API для работы с файлами рекомендуется использовать в большинстве случаев, особенно для файлов размером более 100 МБ или когда необходимо повторно использовать файл в нескольких запросах.

Чтобы узнать о других методах ввода файлов, таких как использование внешних 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-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();

Идти 

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())

ОТДЫХ 

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

Всегда используйте Files API, если общий размер запроса (включая файл, текстовое сообщение, системные инструкции и т. д.) превышает 20 МБ, длительность видео значительна или если вы планируете использовать одно и то же видео в нескольких сообщениях. File API принимает видеофайлы напрямую.

Чтобы узнать больше о работе с медиафайлами, см. раздел «API файлов» .

Передача видеоданных в режиме реального времени.

Вместо загрузки видеофайла с помощью File API, вы можете передавать более короткие видеофайлы непосредственно в запросе функции generateContent . Это подходит для коротких видеофайлов общим размером запроса менее 20 МБ.

Вот пример предоставления видеоданных непосредственно в видеофайле:

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);

ОТДЫХ

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

Передайте URL-адреса YouTube

Вы можете передавать URL-адреса YouTube непосредственно в API Gemini в рамках вашего запроса следующим образом:

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);

Идти 

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())
}

ОТДЫХ 

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 кадр в секунду). Модели Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash и 3.5 Flash Lite также поддерживают агентное понимание видео , при котором модель динамически исследует временную шкалу видео, выборочно проверяя текстовые фрагменты и адаптивно регулируя частоту кадров и разрешение в режиме реального времени на основе запроса.

Режим Описание Поддерживаемые модели
Статический (по умолчанию) Извлекает кадры с фиксированной частотой (1 кадр в секунду) и помещает их в контекст за один проход. Хорошо подходит для коротких видеороликов. Все модели Gemini
Агентский Модель динамически перемещается по временной шкале видео, загружая только необходимый контент в соответствии с запросом. Это обеспечивает до 88% большую эффективность использования токенов и примерно на 7% более высокое качество для длинных видеороликов. Вспышки Gemini 3.8, 3.7, 3.6, 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);

Идти 

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())

ОТДЫХ 

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 . Наличие частей tool_call и tool_response с типом инструмента MEDIA_PROCESSING указывает на то, что модель динамически перемещалась по видео.

Примечание: В отличие от других серверных инструментов (таких как поиск Google или контекст URL), для работы с видео от Agentic не требуется устанавливать параметр include_server_side_tool_invocations=True в ToolConfig для возврата или потоковой передачи вызовов инструментов и результатов. Части tool_call и tool_response для навигации по видео возвращаются автоматически, если для любой входной части установлено значение media_processing="AGENTIC" .

Структура ответа

При включении агентной обработки ответ включает дополнительные части, раскрывающие внутренний след навигации:

  • 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);

Идти 

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())

ОТДЫХ 

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 минут или при планировании нескольких запросов к одному и тому же видеофайлу используйте контекстное кэширование для снижения затрат и улучшения задержки. Контекстное кэширование позволяет обработать видео один раз и повторно использовать токены для последующих запросов, что идеально подходит для чатов или многократного анализа длинного контента.

Обратитесь к временным меткам в содержимом.

Вы можете задавать вопросы о конкретных моментах видео, используя временные метки в формате MM:SS .

Python 

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript 

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Идти 

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
          // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

ОТДЫХ 

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Извлеките подробную информацию из видео.

Модели Gemini обладают мощными возможностями для понимания видеоконтента, обрабатывая информацию как из аудио-, так и из видеопотоков . Это позволяет извлекать богатый набор деталей, включая создание описаний происходящего в видео и ответы на вопросы о его содержании.

Для визуального описания модель считывает видео с частотой 1 кадр в секунду (FPS). Эта частота дискретизации по умолчанию хорошо подходит для большинства материалов, но следует отметить, что она может упускать детали в видео с быстрым движением или быстрой сменой сцен. Для такого динамичного контента рекомендуется установить пользовательскую частоту кадров .

Python 

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript 

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Идти 

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

ОТДЫХ 

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Настройка обработки видео

В API Gemini можно настроить обработку видео, задав интервалы обрезки или указав пользовательскую частоту дискретизации кадров. Эти параметры настройки поддерживаются только при обработке видео в "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();

Установите пользовательскую частоту кадров

Вы можете задать пользовательскую частоту дискретизации кадров, передав аргумент 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-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.')
        ]
    )
)

По умолчанию из видео берется 1 кадр в секунду (FPS). Для длинных видеороликов может потребоваться установить низкую частоту кадров (< 1). Это особенно полезно для преимущественно статичных видео (например, лекций). Используйте более высокую частоту кадров для видео, требующих детального временного анализа, например, для понимания быстро развивающихся событий или высокоскоростного отслеживания движения.

Поддерживаемые форматы видео

Gemini поддерживает следующие MIME-типы видеоформатов:

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

Технические подробности о видео

  • Поддерживаемые модели и контекст : Все модели Gemini могут обрабатывать видеоданные.
    • Модели с контекстным окном размером 1 Мб могут обрабатывать видео продолжительностью до 3 часов по умолчанию (при низком разрешении медиафайлов) или до 1 часа при высоком разрешении медиафайлов.
  • Режимы обработки : модели Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite и более поздние поддерживают два режима обработки видео:
    • Статический режим : Кадры извлекаются с частотой 1 кадр в секунду и помещаются в контекст (по умолчанию для всех моделей). Аудио обрабатывается со скоростью 1 кбит/с (один канал). Временные метки добавляются каждую секунду. Лучше всего подходит для коротких клипов или когда важен каждый кадр (например, покадровый анализ). Обратите внимание, что в динамичных сценах может наблюдаться потеря детализации из-за частоты дискретизации 1 кадр в секунду.
    • Agentic : Модель динамически перемещается по видео, загружая текстовую расшифровку и/или кадры и/или аудио по запросу. Это позволяет использовать до 88% меньше токенов для длинных видеороликов, хотя навигация может немного увеличить время до первого токена (TTFT) для коротких клипов (<5 минут) из-за внутренних рассуждений и обращений инструментов перед началом генерации. Ответы включают части вызова и ответа инструмента MEDIA_PROCESSING для сохранения контекста рассуждений между обращениями. Лучше всего подходит для длинных видеороликов для оптимизации затрат токенов и качества ответов. Поддерживается на Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash и 3.5 Flash Lite. Подробнее см. раздел «Понимание видео Agentic» .
  • Расчет токенов (статический режим) : Каждая секунда видео токенизируется следующим образом:
    • Отдельные кадры (с частотой 1 кадр в секунду):
      • Если media_resolution установлен на low, кадры токенизируются по 66 токенов на кадр.
      • В противном случае, кадры токенизируются по 258 токенов на кадр.
    • Аудио: 32 токена в секунду.
    • Также включены метаданные.
    • Итого: приблизительно 100 токенов в секунду видео при стандартном (низком) разрешении или приблизительно 300 токенов в секунду видео при высоком разрешении.
  • Расчет токенов (агентный режим) : Использование токенов зависит от сложности контента и стратегии навигации модели. Токены, генерируемые во время просмотра видео, учитываются как токены размышления ( thoughts_token_count ), в то время как кадры, аудио и стенограмма, загружаемые по запросу, учитываются как токены подсказок инструмента ( tool_use_prompt_token_count ). Агентная обработка обычно использует до 88% меньше токенов, чем статическая обработка, для длинноформатного контента, поскольку модель загружает только стенограмму и/или кадры и/или аудио, необходимые для ответа на подсказку (см. руководство по токенам ).
  • Разрешение медиафайлов : Gemini 3 предоставляет детальный контроль над обработкой мультимодального изображения с помощью параметра media_resolution . Параметр media_resolution определяет максимальное количество токенов, выделяемых на каждое входное изображение или видеокадр. Более высокое разрешение улучшает способность модели считывать мелкий текст или идентифицировать мелкие детали, но увеличивает использование токенов и задержку. Параметры media_resolution и media_processing независимы: вы можете установить оба параметра для одной и той же части видео.

Более подробную информацию о расчетах токенов см. в руководстве по токенам .

  • Формат временной метки : При указании конкретных моментов видео в вашем задании используйте формат MM:SS (например, 01:15 для 1 минуты и 15 секунд).
  • Размещение подсказки : Если вы объединяете текст и одно видео, разместите текстовую подсказку после видеочасти в массиве contents .
  • Тайм-ауты для длительных запросов : Для видео, требующих длительного времени обработки или сложных многоэтапных вычислений, используйте потоковую передачу ( client.models.generate_content_stream ). Синхронные запросы без потоковой передачи, которые подвергаются повторным попыткам на бэкэнде при высокой нагрузке, могут превышать окна действия соединения или токена аутентификации, что может привести к неожиданным ошибкам 401 Unauthorized или тайм-ауту. Потоковая передача поддерживает соединение активным и отображает промежуточные вычисления и ход выполнения вызовов инструментов.

Что дальше?

  • Разрешение медиафайлов : Настройте разрешение видеокадров, чтобы сбалансировать качество и использование ресурсов.
  • Токены : Разберитесь, как происходит токенизация видеоконтента как в статическом, так и в агентном режимах обработки.
  • Системные инструкции : Системные инструкции позволяют управлять поведением модели в соответствии с вашими конкретными потребностями и сценариями использования.
  • API для работы с файлами : Узнайте больше о загрузке и управлении файлами для использования с Gemini.
  • Стратегии запроса файлов : API Gemini поддерживает запрос файлов с использованием текста, изображений, аудио и видеоданных, также известный как мультимодальный запрос.
  • Рекомендации по безопасности : Иногда модели генеративного ИИ выдают неожиданные результаты, например, неточные, предвзятые или оскорбительные. Постобработка и оценка человеком необходимы для минимизации риска причинения вреда от таких результатов.