Распознавание видео

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

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

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

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

Примечание. File 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())

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

Чтобы оптимизировать эффективность и производительность токенов, используйте агентную обработку видео.

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

Подробнее о работе с медиафайлами можно узнать в документации по Files 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);

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

Передача URL YouTube

Вы можете передавать URL 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);

Проложить маршрут

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

Ограничения:

  • В бесплатном плане нельзя загружать более 8 часов видео YouTube в день.
  • В платной версии ограничений по длительности видео нет.
  • В моделях до Gemini 2.5 в одном запросе можно загрузить только одно видео. Для Gemini 2.5 и более поздних моделей можно загрузить не более 10 видео на запрос.
  • Вы можете загружать только видео с открытым доступом (не с ограниченным доступом или доступом по ссылке).

Анализ видео агентом

По умолчанию для видео во всех моделях, включая Gemini 4, используется статическая обработка (извлечение кадров с частотой 1 кадр/с). Модели Gemini 4 Argon, 3.8 Flash, 3.6 Flash и 3.5 Flash Lite также поддерживают агентное понимание видео – режим, требующий согласия пользователя, в котором модель динамически исследует временную шкалу видео, выборочно проверяет расшифровки и адаптивно настраивает частоту кадров и разрешение на лету на основе запроса.

Режим Описание Поддерживаемые модели
Статический (по умолчанию). Извлекает кадры с фиксированной частотой (1 кадр/с) и помещает их в контекст за один проход. Значение по умолчанию для всех моделей Gemini, включая Gemini 4. Все модели Gemini
Агентные возможности Модель динамически перемещается по временной шкале видео, загружая только тот контент, который ей нужен для ответа на запрос. До 88% эффективнее использует токены и примерно на 7% лучше обрабатывает длинный контент. Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite

Выберите режим обработки

Выберите режим обработки в зависимости от длительности видео и типа запроса:

  • Статический (по умолчанию). Лучше всего подходит для коротких клипов (до пяти минут), общих пересказов видео, где вся запись имеет значение, запросов, чувствительных к задержке, или точности на уровне кадров во всем клипе. При обработке коротких видео или запросов, требующих анализа большей части видео, статическая обработка позволяет избежать дополнительных токенов (thoughts_token_count) и вызовов инструментов (tool_use_prompt_token_count), которые возникают при навигации по временной шкале.
  • Агентный. Лучше всего подходит для длинных видео (более 5–10 минут), поиска иголки в стоге сена или запросов, связанных с определенными моментами или темами. Модель сначала проверяет расшифровки и загружает только релевантные визуальные сегменты по запросу, сокращая использование токенов видеоввода на 88% без заполнения окна контекста.

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

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

Примечание. В отличие от других серверных инструментов, таких как Google Поиск или URL-контекст, для агентного видео не требуется задавать 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())

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

Указывайте временные метки в контенте

Вы можете задавать вопросы о конкретных моментах видео, используя временные метки в формате 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);

Проложить маршрут

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

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

Проложить маршрут

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

Как задать собственную частоту кадров

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

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 кадр в секунду. Для длинных видео можно установить низкую частоту кадров (< 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 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite и более поздние модели поддерживают два режима обработки видео:
    • Статичный. Кадры извлекаются с частотой 1 кадр/с и помещаются в контекст (по умолчанию для всех моделей). Аудио обрабатывается со скоростью 1 кбит/с (один канал). Временные метки добавляются каждую секунду. Лучше всего подходит для коротких клипов или когда важен каждый кадр (например, при покадровом просмотре). Обратите внимание, что при частоте дискретизации 1 кадр в секунду быстрые последовательности действий могут быть не очень подробными.
    • Агентный. Модель динамически перемещается по видео, загружая расшифровку, кадры и/или аудио по запросу. При этом для длинного контента используется на 88 % меньше токенов, хотя навигация может увеличить время до первого токена (TTFT) и общее количество токенов для коротких клипов (менее 5 минут) или широких запросов из-за внутренних рассуждений и циклов работы инструмента. Ответы включают части вызова инструмента MEDIA_PROCESSING и ответа, чтобы сохранить контекст рассуждений между ходами. Лучше всего подходит для длинных видео и целевых запросов, чтобы оптимизировать стоимость токенов и качество ответов. Поддерживается в Gemini 4 Argon, 3.8 Flash, 3.6 Flash и 3.5 Flash Lite. Подробнее о понимании видео с помощью агентов…
  • Расчет токенов (статический режим). Каждая секунда видео токенизируется следующим образом:
    • Отдельные кадры (с частотой 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 или тайм-аутам. Потоковая передача позволяет поддерживать активное подключение и получать промежуточные результаты рассуждений и выполнения вызовов инструментов.

Дальнейшие действия

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