Как анализировать видео в Gemini API с таймкодами и выбором FPS

Gemini обрабатывает визуальный и звуковой поток. Документация указывает стандартную выборку видео 1 кадр в секунду, из-за чего быстрые события могут быть пропущены. В static processing можно задавать start_offset, end_offset и пользовательскую частоту кадров.

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

Подготовка теста

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

До первого запроса заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Заполните expected заранее. Если ожидаемый результат появляется после просмотра ответа, проверка превращается в подгонку.

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

Пошаговая настройка

1. Загрузите MP4 через Files API либо используйте поддерживаемый URI. Сохраните mime_type и URI из ответа, не подставляйте тип по расширению вслепую.
2. Создайте interaction с текстовой инструкцией и объектом type video. Попросите возвращать массив событий с start, end, visual_evidence и audio_evidence.
3. Для длинного файла сначала ограничьте релевантный отрезок через processing type static и start_offset/end_offset. Значения сверяйте с длительностью исходника.
4. Если в ролике быстрые переключения, задайте подходящий FPS в static processing и прогоните тестовый фрагмент. Не утверждайте, что деталь найдена, если её нет в sampled frames.
5. Сверьте не менее пяти таймкодов вручную в проигрывателе. Ошибка больше заданного вашим проектом допуска отправляет запись на повторную проверку.

Каждый шаг должен оставлять проверяемый след: request_id, версия модели, выбранный инструмент, обезличенные аргументы, exit code или статус, размер результата и факт побочного эффекта. Полный секрет, персональные данные и необязательное внутреннее рассуждение модели в журнал не записывайте.

Копируемый шаблон

Проанализируй видео как инструкцию. Верни JSON-массив событий: {start_seconds,end_seconds,action,visible_object,spoken_claim,evidence}. Не описывай действие, если оно не видно и не звучит. Отдельно перечисли quick_change_candidates, которые могли быть пропущены между кадрами.

Общие правила:
- используй только переданные данные и разрешённые инструменты;
- не угадывай отсутствующие значения;
- перед действием проверь путь, тип, идентификатор и права;
- при конфликте верни status=needs_review;
- не отправляй, не удаляй и не раскрывай секрет без отдельного подтверждения;
- перечисли фактические действия и источник каждого изменяемого значения.

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

Реалистичный пример и ожидаемый результат

В тестовом ролике на 00:05 открывают меню Settings, на 00:08 включают Airplane mode, на 00:12 появляется значок самолёта. Ожидаются три события с этими доказательствами; выдуманного нажатия Wi‑Fi нет.

Это критерий теста, а не выдуманный результат сравнительного исследования. При внедрении сохраните реальный output рядом с expected и отметьте каждое расхождение. Правильный текст при лишней команде, неверном файле или запрещённом запросе считается провалом.

Проверка результата по четырём уровням

Сначала транспорт: запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 не доказывает корректность. При тайм-ауте сначала выясните состояние прошлого вызова; повтор внешней записи без проверки создаёт дубли.

Затем структура: обязательные поля присутствуют, типы совпадают, Base64 декодируется, JSON разбирается после полного получения, файл открывается штатной библиотекой. Пустое поле не превращается в число или факт без явного правила.

Третий уровень — смысл. Каждый факт сопоставляется с входом, таймкодом, файлом либо результатом инструмента. Числа пересчитываются обычным кодом. Имена и идентификаторы сравниваются посимвольно. Если источник не содержит значения, ответ должен сообщить о нехватке данных.

Четвёртый уровень — действие. Проверьте внешнюю систему или файловый diff: какие команды выполнены, какие файлы созданы, была ли запись. Для read-only сценария любое изменение является ошибкой, даже если итоговое объяснение выглядит убедительно.

Приёмка на конкретных данных