Доступна новая модель Gemini 4 Argon. Попробовать

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

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

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

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

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

Примечание. File API рекомендуется для большинства случаев, особенно для файлов размером более 100 МБ или когда вы хотите повторно использовать файл в нескольких запросах.

Чтобы узнать о других способах ввода файлов, например об использовании внешних URL или файлов, хранящихся в Google Cloud, ознакомьтесь с руководством по способам ввода файлов.

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

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

Python

from google import genai
import time

client = genai.Client()

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

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "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 ".steps[].content[0].text" response.json

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

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

Подробнее о работе с медиафайлами можно узнать в документации по Files API.

Как передавать данные о видео в коде

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

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

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

Передача URL YouTube

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

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null

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

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

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

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

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

Примечание. Для длинных видео или сложных запросов, обработка которых агентом занимает больше времени, используйте потоковую передачу (stream=True) или фоновое выполнение (background=True). Это позволяет поддерживать активное подключение, показывать промежуточные этапы рассуждений и избегать тайм-аутов подключения или аутентификации.

Как задать режим обработки

Чтобы использовать агентное понимание видео, задайте значение "processing": "agentic" в части видео в массиве input.

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

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

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Upload a long video
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 });
}

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Примечание. Чтобы проверить, использовалась ли обработка с помощью агента, изучите interaction.steps. Наличие processing_call и processing_result означает, что модель динамически перемещалась по видео.

Действия в ответ на инцидент

Агентная обработка добавляет два новых типа шагов в массив steps:

processing_call – модель запросила видеосегмент или расшифровку аудио, идентифицированные как id.
processing_result – результат загрузки, связанный с помощью call_id.

Они чередуются с шагами thought (если включены сводки) и предшествуют последнему шагу model_output. Их можно использовать для отображения прогресса в интерфейсе, но они не требуют ответа.

В примере ниже показана полезная нагрузка ответа с чередующимися этапами обработки:

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Использовать разные режимы обработки для разных видео

Задайте разные режимы обработки для каждого видео в одном запросе:

Python

import time
from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_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" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Многоходовые диалоги о видео

Контекст видео сохраняется на протяжении всей беседы. При использовании агентной обработки:

Режим с сохранением состояния (используется previous_interaction_id). Сервер сохраняет контекст видео. Дополнительная обработка не требуется.
Режим без отслеживания состояния (с использованием step_list). В этом режиме ответ включает шаги processing_call и processing_result, которые кодируют контекст видео. Чтобы сохранить контекст видео, в следующий запрос step_list нужно включить все шаги из ответа. Если не указать эти параметры, API не вернет ошибку, но контекст видео будет потерян, что значительно снизит качество ответов на последующие вопросы. Обратите внимание, что возвращенные шаги, отправленные в последующих запросах, учитываются в количестве входных токенов.

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

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

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?"

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Java

String prompt = "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?"

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Извлечение подробной информации из видео

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

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

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.";

Java

String prompt =
    "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."

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Как настроить обработку видео

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

Как задать интервалы для клипов

Вы можете обрезать видео, указав start_offset и end_offset в объекте конфигурации processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

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

Вы можете задать собственную частоту кадров, передав аргумент fps в объекте конфигурации processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

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

Gemini поддерживает следующие MIME-типы видео:

video/mp4
video/mpeg
video/mov
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 минут) или широких запросов из-за внутренних рассуждений и циклов работы инструмента. Лучше всего подходит для длинных видео и целевых запросов, чтобы оптимизировать стоимость токенов и качество ответов. Поддерживается в Gemini 4 Argon, 3.8 Flash, 3.6 Flash и 3.5 Flash Lite. Подробнее о понимании видео с помощью агентов…
Расчет токенов (статический режим). Каждая секунда видео токенизируется следующим образом:
- Отдельные кадры (с частотой 1 кадр/с):
  - Если для параметра media_resolution задано значение low, кадры токенизируются по 66 токенов на кадр.
  - В противном случае кадры токенизируются по 258 токенов на кадр.
- Аудио: 32 токена в секунду.
- Метаданные также включаются.
- Итого: примерно 100 токенов на секунду видео при стандартном (низком) разрешении или примерно 300 токенов на секунду видео при высоком разрешении.
Расчет токенов (агентский режим). Использование токенов зависит от сложности контента и стратегии навигации модели. Токены, сгенерированные во время исследования видео, учитываются как токены рассуждений (total_thought_tokens), а кадры, аудио и расшифровка, загруженные по запросу, – как токены использования инструментов (total_tool_use_tokens). При обработке с помощью агента обычно используется на 88% меньше токенов, чем при статической обработке длинного контента, поскольку модель загружает только расшифровку и/или кадры и/или аудио, необходимые для ответа на запрос (см. руководство по токенам).
Разрешение медиаконтента. В Gemini 3 реализовано точное управление обработкой мультимодального контента с помощью параметра media_resolution. Параметр media_resolution определяет максимальное количество токенов, выделяемых на каждое входное изображение или кадр видео. Более высокое разрешение позволяет модели лучше распознавать мелкий текст и небольшие детали, но увеличивает количество используемых токенов и время ожидания. Параметры media_resolution и processing не зависят друг от друга, поэтому их можно задавать для одного и того же видео.

Подробнее о расчете токенов…

Формат временных меток. Если вы хотите указать в запросе определенный момент видео, используйте формат MM:SS (например, 01:15 для 1 минуты и 15 секунд).
Размещение запроса. Если вы комбинируете текст и одно видео, разместите текстовый запрос после видео в массиве input.
Тайм-ауты для длинных запросов. Для видео, требующих длительной обработки или сложных многоэтапных рассуждений, используйте потоковую передачу (stream=True) или фоновое выполнение (background=True). Синхронные непотоковые запросы, которые повторно выполняются в серверной части при высокой нагрузке, могут превысить окна действия токенов подключения или аутентификации, что может привести к непредвиденным ошибкам 401 Unauthorized или тайм-аута. Потоковая передача позволяет поддерживать активное подключение и показывать промежуточные рассуждения и прогресс вызова инструментов.

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

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