Veo 3 теперь доступен в Gemini API! Подробнее Veo 3 теперь доступен в Gemini API! Подробнее

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

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

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

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

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

Видеовход

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

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

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

Вы можете использовать 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 МБ.

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

Питон

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

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

API Gemini и AI Studio поддерживают URL-адреса YouTube в качестве Part данных файла. Вы можете включить URL-адрес YouTube в запрос, чтобы модель могла обобщить, перевести или иным образом взаимодействовать с видеоконтентом.

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

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

В следующем примере показано, как включить URL-адрес YouTube в приглашение:

Питон

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-1.5-pro" });
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

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

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

Питон

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.')
        ]
    )
)

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

Вы можете задать пользовательскую частоту кадров, передав аргумент fps в videoMetadata .

Питон

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

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

Что дальше?

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

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