Анализ архитектурного видео с Gemini API: пошаговое руководство

Что вы узнаете из этого руководства?

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

Примеры в этой статье предназначены для анализа уже существующих видео, а не для их генерации. В руководстве Google по генерации видео для этой задачи указан Gemini Omni Flash; понимание видео — отдельный сценарий использования. Разграничение этих задач помогает избежать выбора неподходящей модели или неверного рабочего процесса.

Требования

Для работы понадобятся доступ к Gemini API, видеофайл или общедоступное видео на YouTube и текстовый запрос. В официальном примере используются Python-клиент google-genai, Files API и Interactions API. Поскольку источник не указывает конкретную версию SDK или шаги для создания аккаунта, здесь не приводятся номер версии и условия регистрации. Настройте аутентификацию API-клиента в соответствии с вашей средой; в примере REST из источника используется переменная GEMINI_API_KEY.

Выбирайте способ передачи с учётом размера файла и необходимости повторного использования:

• Files API: источник рекомендует этот способ для файлов размером более 100 МБ, длинных видео и контента, который будет использоваться повторно. В документации указана ёмкость 20 ГБ при платном использовании и 2 ГБ при бесплатном.

• Cloud Storage Registration: указан лимит 2 ГБ на файл и отсутствие ограничений на объём хранилища; этот вариант предназначен для больших файлов, которые будут храниться долго и использоваться повторно.

• Данные непосредственно в запросе: согласно документации, этот способ подходит для небольших файлов. Подробные инструкции рекомендуют передавать таким образом короткие видео, если общий размер запроса не превышает 20 МБ; на практике ориентируйтесь на этот более строгий порог в 20 МБ.

• URL YouTube: поддерживаемый способ передачи общедоступных видео.

Пошаговый анализ видео

1. Определите цель анализа

До отправки видео сформулируйте ожидаемый результат. Для презентации проекта это может быть общий обзор, для экскурсии по пространству — перечень видимых материалов, а для конкретного эпизода записи — его описание. Вместо нескольких разнородных задач в одном запросе чётко укажите основную цель и желаемый формат ответа. Чтобы модель не дополняла сведения, которых нет в видео, можно также попросить описывать только то, что действительно видно в записи.

Например, чтобы получить краткое и структурированное описание интерьера, можно использовать такой запрос:

Analyze this interior architecture video. Summarize the visible spaces, circulation, lighting, and materials. Use only details that can be observed in the video, and organize the response by topic.

Этот запрос предлагает разделить видимые в видео пространства, маршруты движения, освещение и материалы по отдельным темам. Он также просит опираться только на наблюдаемые детали, а не указывать точное название материала, если его нельзя уверенно распознать.

2. Выберите способ передачи с учётом размера файла

Для большого или длинного видео, а также если вы планируете использовать его в последующих запросах, выбирайте Files API. Для короткого файла можно рассмотреть передачу данных непосредственно в запросе, но общий размер запроса должен оставаться меньше 20 МБ. Для общедоступного видео на YouTube можно использовать URL. Перед отправкой проверьте размер файла и условия использования: в источнике ёмкость указана отдельно для бесплатного и платного тарифов.

3. Загрузите видео через Files API и дождитесь обработки

В официальном примере на Python файл загружается с помощью client.files.upload, после чего его статус проверяется до тех пор, пока он не станет ACTIVE. Сам факт загрузки не означает, что файл уже готов к анализу: дождитесь завершения обработки. В примере ниже статус проверяется с интервалом в пять секунд. Код основан на примере источника с открытой лицензией:

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)

Замените path/to/sample.mp4 на путь к нужному файлу. В примере источника показано, как после подготовки ссылки на файл использовать её в качестве видеовхода. Если обработка завершилась с ошибкой, не считайте файл готовым — сначала убедитесь, что статус изменился соответствующим образом.

4. Передайте видео вместе с запросом через Interactions API

Когда файл получит статус ACTIVE, добавьте URI видео и текстовый запрос во входные данные одного взаимодействия. В примере источника используется модель gemini-3.8-flash. Следующий запрос предназначен для анализа пространственной последовательности и переходов в видеообзоре проекта:

Review this architectural walkthrough in chronological order. Describe how the spaces connect, identify visible transitions, and refer to relevant moments with timestamps when possible. Do not infer dimensions or design intent that the video does not show.

Запрос временных меток помогает соотнести наблюдения с конкретными фрагментами записи. Явно укажите, что модель не должна делать выводы о размерах или замысле проекта, если видео этого не подтверждает: так ответ останется в пределах визуального анализа.

5. Сузьте задачу с учётом проектной работы

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

From the video, list only the visible changes in lighting and material appearance between the main spaces. For each observation, include a timestamp when available and mark anything uncertain as unclear.

Этот запрос ограничивает ответ изменениями освещения и внешнего вида материалов. Просьба помечать неуверенные наблюдения как «неясные» помогает избежать выдачи за достоверные сведений, которые нельзя разобрать из-за низкого качества изображения или отсутствия нужного объекта в кадре.

Распространённые ошибки

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

• Запрос анализа до обработки файла: после загрузки проверьте, что статус стал ACTIVE; в примере состояние файла регулярно запрашивается.

• Слишком широкий или расплывчатый запрос: вместо общей формулировки вроде «проанализируй видео» сосредоточьтесь на одной задаче — например, кратком пересказе, пространственных переходах или видимых материалах.

• Ожидание сведений, которых нет в кадре: понимание видео предназначено для анализа визуальной информации в записи; не следует считать, что оно подтверждает размеры проекта или проектные решения, не показанные в видео.

• Путаница между руководствами по генерации и анализу видео: для понимания уже существующего видео используйте документацию по пониманию видео. Google сообщает, что Veo 3.1 Preview будет отключён в Gemini API 22 октября 2026 года и рекомендует перейти на Gemini Omni Flash для генерации видео; это изменение не заменяет шаги анализа.

Применение в архитектуре, дизайне интерьеров и archviz

Архитектурные и интерьерные команды могут попробовать этот подход, чтобы составить краткий обзор наблюдений по видеозаписи проекта или пространства, найти важные фрагменты по временным меткам и ответить на вопросы о записи. Команды archviz также могут изучить сценарии вопросов и ответов о содержании существующей видеопрезентации. Однако результаты следует ограничивать тем, что действительно показано в видео; отдельно проверяйте сведения, которые запись не подтверждает, — например, размеры, техническую пригодность или применимость решений в проекте.

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

Следующие шаги

Для начала попробуйте запрос на краткий пересказ на коротком видео проекта, на использование которого у вас есть разрешение. Затем добавьте уточняющие вопросы с временными метками или запросом конкретного типа наблюдений. Если файл большой или будет использоваться повторно, рассмотрите Files API. Прежде чем переносить результаты в проектные заметки, откройте видео на соответствующих временных отметках и проверьте наблюдения модели. За подробностями о загрузке файлов и выборе модели обратитесь к официальной документации Gemini API по пониманию и генерации видео.

Источник и лицензия

Это руководство адаптировано на турецкий язык на основе материалов Google по пониманию и генерации видео в Gemini API. Оба источника распространяются по лицензии CC BY 4.0. Пример кода на Python взят из документации по пониманию видео, опубликованной под открытой лицензией.