Veo 3.1 уже здесь! Узнайте о новой модели и её функциях в блоге и документации .

Эта страница переведена с помощью Cloud Translation API.

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

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

Описывайте, сегментируйте и извлекайте информацию из видео
Ответьте на вопросы о видеоконтенте
Ссылайтесь на конкретные временные метки в видео

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

Видеовход

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

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

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

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

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

Питон

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

Подробнее о работе с медиафайлами читайте в разделе Files API .

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

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

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

Питон

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 следующим образом:

Питон

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

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

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

Сверяйтесь с временными метками в содержании.

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

Питон

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

Питон

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Идти

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

ОТДЫХ

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

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

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

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

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

Питон

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 .

Питон

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

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

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 часа при низком разрешении мультимедиа.
Обработка файлов API : при использовании файлов API видео сохраняется со скоростью 1 кадр в секунду (FPS), а аудио обрабатывается со скоростью 1 Кбит/с (один канал). Временные метки добавляются каждую секунду.
- В будущем эти ставки могут быть изменены для улучшения вывода.
- Вы можете переопределить частоту дискретизации 1 FPS , установив пользовательскую частоту кадров .
Расчет токена : каждая секунда видео токенизируется следующим образом:
- Отдельные кадры (выборка 1 FPS):
  - Если для mediaResolution установлено значение low, кадры токенизируются по 66 токенов на кадр.
  - В противном случае кадры токенизируются по 258 токенов на кадр.
- Аудио: 32 токена в секунду.
- Метаданные также включены.
- Итого: около 300 токенов в секунду видео при разрешении мультимедиа по умолчанию или 100 токенов в секунду видео при низком разрешении мультимедиа.
Формат временной метки : при указании конкретных моментов видео в подсказке используйте формат MM:SS (например, 01:15 для 1 минуты и 15 секунд).
Лучшие практики :
- Для достижения оптимальных результатов используйте только одно видео на каждый запрос.
- При объединении текста и одного видео разместите текстовую подсказку после видеочасти в массиве contents .
- Имейте в виду, что в динамичных сценах может наблюдаться потеря детализации из-за частоты дискретизации 1 кадр/с. При необходимости попробуйте замедлить такие клипы.

Что дальше?

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

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