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

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

  • Описывать, сегментировать и извлекать информацию из видеороликов.
  • Ответьте на вопросы о видеоконтенте.
  • Обратитесь к конкретным временным меткам в видеоролике.

Gemini изначально создавался как мультимодальный сервис, и мы продолжаем расширять границы возможного. В этом руководстве показано, как использовать API Gemini для генерации текстовых ответов на основе видеовходных данных.

видеовход

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

  • Перед отправкой запроса на generateContent загрузите видеофайл с помощью File API. Используйте этот метод для файлов размером более 20 МБ, видео продолжительностью более 1 минуты или если вы хотите повторно использовать файл в нескольких запросах.
  • Передайте встроенные видеоданные вместе с запросом к методу generateContent . Используйте этот метод для файлов меньшего размера (<20 МБ) и меньшей продолжительности.
  • Передайте URL-адреса YouTube в рамках запроса generateContent .

Загрузите видеофайл

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

Приведенный ниже код загружает образец видео, выгружает его через File API, ожидает обработки, а затем использует ссылку на файл в запросе generateContent .

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-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-2.5-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-2.5-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-2.5-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

Чтобы узнать больше о работе с медиафайлами, см. раздел «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='models/gemini-2.5-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.')
        ]
    )
)

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-2.5-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-2.5-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 в рамках запроса generateContent следующим образом:

Python

response = client.models.generate_content(
    model='models/gemini-2.5-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.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.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-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

ОТДЫХ

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-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 видео за один запрос.
  • Вы можете загружать только общедоступные видео (не частные или скрытые видео).

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

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

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

Установить интервалы обрезки

Вы можете обрезать видео, указав в параметре videoMetadata начальное и конечное смещения.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-2.5-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-2.5-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-2.5-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/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

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

  • Поддерживаемые модели и контекст : Все модели Gemini 2.0 и 2.5 могут обрабатывать видеоданные.
    • Модели с контекстным окном размером 2 МБ могут обрабатывать видео продолжительностью до 2 часов при стандартном разрешении или до 6 часов при низком разрешении, в то время как модели с контекстным окном размером 1 МБ могут обрабатывать видео продолжительностью до 1 часа при стандартном разрешении или до 3 часов при низком разрешении.
  • Обработка через File API : При использовании File API видеофайлы сохраняются со скоростью 1 кадр в секунду (FPS), а аудио обрабатывается со скоростью 1 Кбит/с (один канал). Временные метки добавляются каждую секунду.
  • Расчет токенов : Каждая секунда видео токенизируется следующим образом:
    • Отдельные кадры (с частотой 1 кадр в секунду):
      • Если mediaResolution установлен на low, кадры токенизируются по 66 токенов на кадр.
      • В противном случае, кадры токенизируются по 258 токенов на кадр.
    • Аудио: 32 токена в секунду.
    • Также включены метаданные.
    • Итого: приблизительно 300 токенов в секунду видео при стандартном разрешении или 100 токенов в секунду видео при низком разрешении.
  • Среднее разрешение : Gemini 3 обеспечивает детальный контроль над обработкой мультимодального зрения с помощью параметра media_resolution . Параметр media_resolution определяет максимальное количество токенов, выделяемых на каждое входное изображение или видеокадр. Более высокое разрешение улучшает способность модели считывать мелкий текст или идентифицировать мелкие детали, но увеличивает использование токенов и задержку.

    Для получения более подробной информации о параметре и о том, как он может влиять на вычисления токенов, см. руководство по разрешению медиаконтента .

  • Формат временной метки : При указании конкретных моментов видео в вашем задании используйте формат MM:SS (например, 01:15 для 1 минуты и 15 секунд).

  • Передовые методы :

    • Для достижения оптимальных результатов используйте только одно видео на каждый запрос.
    • При объединении текста и одного видео, поместите текстовую подсказку после видеочасти в массиве contents .
    • Учтите, что в динамичных сценах из-за частоты дискретизации 1 кадр в секунду может наблюдаться потеря детализации. При необходимости рассмотрите возможность замедления таких видеороликов.

Что дальше?

В этом руководстве показано, как загружать видеофайлы и генерировать текстовый вывод на основе видеовходов. Для получения дополнительной информации см. следующие ресурсы:

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