Architectural Video Analysis with the Gemini API: A Step-by-Step Guide

What you'll learn in this guide

The Gemini API can be used to extract information from videos and answer questions about their content. This guide covers how to choose an appropriate upload method, wait for the file to be processed, and prepare task-focused prompts for videos such as architectural project presentations, construction site recordings, or walkthroughs. Gemini models can describe a video, extract information from its content, and refer to specific timestamps. This lets you request a summary or a focused answer for review, rather than watching a long recording from beginning to end yourself.

The examples here focus on understanding existing videos, not generating them. Google’s video generation guide identifies Gemini Omni Flash for that task; video understanding is a separate use case. Keeping the distinction clear helps avoid choosing the wrong model or workflow for an analysis request.

Requirements

The workflow requires Gemini API access, a video file or a publicly available YouTube video, and a text prompt. The official example uses the Python client google-genai, the Files API, and the Interactions API. Since the source does not specify an SDK version or account setup steps, no version number or registration requirements are given here. Complete API client authentication for your environment; the source’s REST example uses the GEMINI_API_KEY variable.

Choose an upload method based on the file size and whether you need to reuse the content:

• Files API: The source recommends this method for files over 100 MB, long videos, and content you plan to reuse. The documented limits are 20 GB for paid use and 2 GB for free use.

• Cloud Storage Registration: The source specifies a 2 GB limit per file and no storage limit; this option is intended for large content that will be stored long-term and reused.

• Inline data: The documentation says this method is suitable for small files. Its detailed guidance recommends sending short videos inline when the total request size is under 20 MB, so use the more restrictive 20 MB threshold in practice.

• YouTube URL: A supported input method for publicly available videos.

Step-by-step video analysis

1. Define your review objective

Before submitting the video, decide what you want the analysis to produce. You might request a general summary of a project presentation, a list of visible materials in a walkthrough, or a description of a specific moment in a recording. Instead of asking for several unrelated outputs in one prompt, state the main objective and desired response format clearly. You can also ask the model to report only what is visible in the recording to avoid having it fill in information that is not there.

For example, you can use this prompt to get a concise, structured set of observations from an interior video:

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.

This prompt groups the visible spaces, circulation, lighting, and materials under separate headings. It asks the model to rely only on observable details rather than naming a material with certainty when it cannot be clearly identified in the footage.

2. Choose an upload method that fits the file

Use the Files API if the video is large or long, or if you plan to reuse it in later prompts. Inline upload may work for a short file, but make sure the total request stays under 20 MB. For a publicly available YouTube video, consider using its URL. Check file sizes and usage limits before uploading; the source lists capacity separately for free and paid use.

3. Upload with the Files API and wait for processing

The official Python example uploads the file with client.files.upload and checks its status until it becomes ACTIVE. Uploading a file does not mean it is immediately ready for analysis; wait until processing is complete. The example below checks the status at five-second intervals. This code is based on the source’s openly licensed example:

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)

Replace path/to/sample.mp4 with the path to the file you want to analyze. The source example shows how to use the file reference as video input once it is ready. If processing fails, do not treat the file as ready; confirm that its status has progressed.

4. Send the video and prompt to the Interactions API

Once the file reaches the ACTIVE state, include the video URI and text prompt in the same interaction input. The source example uses the model name gemini-3.8-flash. The prompt below is designed to examine the spatial sequence and transitions in a presentation video:

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.

Asking for timestamps helps tie observations to specific parts of the recording. Explicitly telling the model not to infer details that cannot be verified from the video, such as measurements or design intent, keeps the response within the bounds of visual review.

5. Narrow the output to your project needs

If the initial response is too general, focus your follow-up question on a specific topic rather than asking the model to describe the video again. Gemini’s video guide discusses multi-turn conversational editing in the context of video generation; its video understanding documentation describes the ability to ask questions about videos and refer to timestamps. For this analysis workflow, narrow the question to the section or type of observation you want to review.

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.

This prompt limits the response to changes in lighting and material appearance. Asking the model to mark uncertain details as “unclear” can help prevent details that are difficult to see because of low image quality or framing from being presented as certain.

Common mistakes

• Sending a large video inline: The source’s detailed guidance recommends inline upload for short videos with a total request size under 20 MB. Consider the Files API for larger files.

• Requesting analysis before the file is processed: Check for the ACTIVE status after uploading; the example polls the file status regularly.

• Writing a broad or vague prompt: Instead of a general request such as “Analyze the video,” focus on one objective, such as a summary, spatial transitions, or visible materials.

• Expecting information that is not in the footage: Video understanding can be used to review visual information in the content; it should not be assumed to verify project measurements or design decisions that are not shown in the recording.

• Confusing the video generation guide with the analysis guide: Use the video understanding documentation to understand existing videos. Google says Veo 3.1 Preview was shut down in the Gemini API on 22 October 2026 and recommends moving to Gemini Omni Flash for video generation; this change does not replace the analysis steps.

Uses in architecture, interior design, and archviz workflows

Architecture and interior design teams can try this method to produce an initial summary of observations from a project walkthrough or space recording, find key moments using timestamps, and answer questions about the footage. Archviz teams can also explore question-and-answer workflows about the content of an existing video presentation. However, keep the output limited to what the video shows; separately verify anything the recording cannot confirm, such as measurements, technical suitability, or whether something can be implemented in the project.

Since Files API limits differ between free and paid use, teams should review the project file size and their access terms before uploading. The source does not explain hardware requirements, pricing details, or local software integration, so do not assume this workflow is connected to existing modeling or rendering tools.

Next steps

Start by testing the summary prompt on a short, authorized project video, then add follow-up questions requesting timestamps or specific types of observations. Consider the Files API for large files or content you plan to reuse. Before adding the results to project notes, open the video at the relevant timestamps and verify the model’s observations. For implementation details about file uploads or model selection, consult the official Gemini API documentation on video understanding and video generation.

Source and license

This guide has been adapted into Turkish based on Google’s Gemini API video understanding and video generation documentation. Both sources are licensed under CC BY 4.0. The Python code example is from the openly licensed video understanding documentation.