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

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

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

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

Прежде чем начать

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

Видео вход

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

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

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

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

File API напрямую принимает форматы видеофайлов. В этом примере используется короткометражный фильм НАСА «Большое красное пятно Юпитера сжимается и растет» . Фото: Центр космических полетов Годдарда (GSFC)/Дэвид Лэдд (2018).

«Большое красное пятно Юпитера сжимается и растет» находится в свободном доступе и не показывает идентифицируемых людей. ( Руководство НАСА по использованию изображений и медиа. )

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

Питон

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

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

response = client.models.generate_content(
    model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });

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

Идти

file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

ОТДЫХ

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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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

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

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

  • Вы не можете загружать более 8 часов видео на YouTube в день.
  • По одному запросу можно загрузить только 1 видео.
  • Вы можете загружать только общедоступные видео (но не частные или частные видео).

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

Питон

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

Идти

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
  genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
  genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

ОТДЫХ

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
         // Adjusted timestamps for the NASA video
        genai.Text("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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
        genai.Text("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."

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

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

Что дальше

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

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