Руководство по API Gemini agentic video understanding

Двухчасовую лекцию и 20-секундный ролик о продукте нельзя анализировать одинаково. Новый режим agentic video understanding в Gemini стоит рассматривать в первую очередь для длинных записей и вопросов о конкретных моментах. Но заявленная Google экономия «до» — это результат бенчмарков, а не гарантированное снижение каждого счёта API на 66%.

Выбирайте режим по задаче, а не по длительности ролика

Gemini agentic video understanding лучше подходит для запросов, где нужно найти или повторно проверить определённый фрагмент. Статическая обработка остаётся более простым вариантом, если короткий ролик должен быстро вернуть результат или требуется равномерно покрыть все интервалы выборки.

На старте Google выделила четыре сценария: поиск момента с точностью до долей секунды, поиск «иголки в стоге сена» в длинных видео, обнаружение аномалий и подсчёт действий или объектов. В официальном анонсе приведены примеры от 10-минутных инструкций до 90-минутных лекций и многочасовых записей.

Публичного порога по длительности нет: агентная обработка может быть оправдана и для пятиминутного видео с одним скрытым событием, тогда как длинная однообразная запись — не обязательно.

Одна возможность, два формата API-запросов

«Agentic» — не универсальное поле JSON для всех API. В примере из анонса Google используется Interactions API, где processing: "agentic" задаётся внутри видеовхода. В GenerateContent обработка медиа настраивается в самой части с медиафайлом.

Interactions API: параметр processing указывается во входе видео

В анонсе Google приведён такой паттерн Python для ролика YouTube:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

Параметр должен находиться в объекте видео, а не в несвязанном поле верхнего уровня.

GenerateContent: обработка медиа задаётся в media part

В документации Gemini по пониманию видео формат GenerateContent описан отдельно. В таком запросе для медиа используется media_processing: "AGENTIC"; в JavaScript ему соответствует свойство в camelCase — mediaProcessing.

Минимальный вариант на Python выглядит так:

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

Для локального видео замените YOUR_VIDEO_FILE_URI на URI, который вернёт процесс загрузки файлов Gemini, и дождитесь готовности файла перед отправкой media part. Сверяйте детали SDK для установленной версии клиента с актуальным официальным руководством по пониманию видео.

При переходе с client.interactions.create на generateContent не смешивайте эти примеры.

Как на самом деле работает agentic video understanding

При статической обработке видео выбираются кадры с фиксированной частотой. По словам Google, по умолчанию это 1 кадр в секунду, а частоту можно менять через API; затем модель анализирует полученные кадры.

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

1. Запрашивает сегмент или модальность, релевантные вопросу.
2. Изучает возвращённые кадры, аудио или транскрипт.
3. При необходимости большей временной точности повторно просматривает более узкий интервал.

Статическая выборка даёт разработчику понятное правило покрытия. Агентная обработка сильнее полагается на решение модели о том, куда смотреть, поэтому в продакшене стоит проверять таймстемпы и подсчёты на репрезентативных видео.

«До 66%» — не фиксированная скидка

Google приводит следующие результаты на стандартных бенчмарках анализа видео, отдельно подчёркивая наибольший эффект для длинных записей:

Согласно анонсу Google, agentic video understanding тарифицируется по стандартным ценам Gemini API за токены и не требует отдельной платы за функцию. Итоговая стоимость всё равно зависит от модели, извлечённого контента, самого запроса и ответа. Более широкий контекст по стоимости токенов и моделей — в руководстве по ценам Gemini 3.7 Flash API.

Если вы неоднократно задаёте вопросы по одной записи, кэшируйте видеоконтекст там, где это поддерживает API-процесс. В практических заметках Google Cloud по анализу видео context caching назван одним из ключевых способов сократить расходы при повторном анализе.

Доступность и границы развёртывания

Agentic video understanding — это возможность обработки для трёх моделей семейства Flash, а не отдельная анонсированная видеомодель. Google сообщает, что она была запущена 1 сентября 2026 года для следующих моделей и платформ:

Планируемое появление функции в потребительском Gemini и YouTube не означает, что она уже доступна всем аккаунтам.

Четыре прогона перед сменой режима по умолчанию

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

1. Поиск по таймстемпам: Добавьте клипы со сменой сцен, краткими появлениями и одним событием, для которого важны точные моменты начала и конца. Сравните возвращённые таймстемпы с проверенным человеком эталоном.
2. Подсчёт быстрых действий: Возьмите видео с повторяющимися движениями или объектами, пересекающими кадр. Проверьте общий результат и то, объясняет ли ответ окно, в котором выполнялся подсчёт.
3. Привязка к аудио и транскрипту: Задавайте вопросы, в которых произнесённые слова расходятся с видимым действием. Убедитесь, что ответ не подменяет одну модальность другой без явного указания.
4. Операционное поведение: Запустите одинаковые файлы в обоих режимах и логируйте входные и выходные токены, задержку по фактическому времени, повторные попытки, пустые ответы, пропущенные события и результат статического fallback. Сохраняйте fallback, если избирательное извлечение пропускает подтверждения или добавляет неприемлемую задержку.

Не выводите из анонса жёсткое правило «использовать agentic после X минут». Опубликованные материалы поддерживают выбор по задаче, а не универсальный порог длительности.

FAQ по Gemini agentic video understanding API

Agentic video understanding — это новая модель Gemini?

Нет. Google представляет её как возможность понимания видео, доступную в Gemini 3.7 Flash, Gemini 3.6 Flash и Gemini 3.5 Flash-Lite.

Можно использовать загруженное видео вместо URL YouTube?

Да. Google указывает среди поддерживаемых входов API загруженные видеофайлы и ролики YouTube. Локальный файл сначала нужно загрузить, а затем передать возвращённый URI файла в media part после завершения обработки.

Нужно ли отдельно платить за agentic-обработку видео?

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

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