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

What will you learn in this guide?

With the Gemini API, you can do more than ask for a video summary: you can ask questions about its content, request descriptions of specific scenes, and query information tied to timestamps. These capabilities can be used to review architectural project presentations, interior walkthroughs, site recordings, or videos showing the design process. The steps below focus on providing the video as input in the right way and asking a clear question.

The sample prompts were created specifically for architecture and interior design workflows. The documentation’s basic approach is to send the video to the model in a request and include text instructions about it in that same request.

Requirements and input selection

To get started, you need access to the Gemini API, an environment configured with an API client, and a video to analyze. The official guide includes examples for Python, JavaScript, Go, and REST. The Python example imports the genai module from the google package; since no specific SDK version is given, we do not list one here.

Choose an input method based on the file size and how you plan to use it:

• Files API: Recommended for large files, long videos, and content you plan to reuse. The guide’s table lists a maximum of 20 GB for paid usage and 2 GB for free usage. You can wait for the uploaded file to finish processing, then use the returned file reference in a content request.

• Inline data: Can be used for small, one-off videos. Different sections of the guide give different limits: under 100 MB in the table, but under 20 MB for the total request in the implementation notes. If you choose inline data, use the more conservative limit of 20 MB for the total request.

• YouTube URL: Public videos can be provided directly as input. This feature is in preview, and pricing and rate limits may change. The free tier does not allow more than 8 hours of YouTube video uploads per day; no duration-based limit is specified for the paid tier.

The documentation also covers storing files in Cloud Storage: the maximum file size is 2 GB, with no storage limit specified. This is presented as an option for persistent files that will be reused.

Video analysis, step by step

1. Choose the video and define the question. First, decide whether you want a summary of the whole video or want to find a specific moment. For example, looking for where circulation begins in an interior tour is a different task from requesting a general summary.

2. Choose the right input method. Inline data may work for a small, short, one-off clip. If the total request exceeds 20 MB, the video is long, or you plan to reuse it, the Files API is the preferred option in the guide. For YouTube, the video must be public.

3. Add the file to the request. In the official Python example, the file is uploaded with client.files.upload(...); the returned file object is then passed along with text instructions to a client.models.generate_content(...) call. Waiting for the file to finish processing is also part of the example workflow. For YouTube input, the link is added to the request as a video file.

4. Turn the prompt into an observable task. Instead of a broad instruction such as “analyze the video,” specify what information you need and how you want the response formatted. Starting with a general summary, then asking a follow-up question about a specific element or timestamp, makes it easier to evaluate the results.

The following prompt is designed to extract general information from a short architectural project video:

Summarize this architectural project video briefly. List the visible spaces and the design features that can be clearly identified in the video separately. Do not guess at information that cannot be verified from the footage.

This prompt draws on the model’s ability to describe videos and extract information from their content. It also sets a boundary to discourage the model from inventing details—such as a project name, material, or measurement—that are not visible in the footage.

To find the moment when a specific event occurs in a site or interior walkthrough, ask a more targeted question:

Find the moment in the video when the transition from the entrance space to the main living area is shown. Give the approximate timestamp of this transition and briefly explain what spatial change is visible. Do not present a timestamp as exact if you are unsure.

The guide states that you can query specific timestamps in a video. Clearly describing the event you are looking for is therefore more useful than making a vague request such as “find the important moments.”

You can use the following question to prepare a presentation video for design review:

Review the spatial arrangements shown in this video in order. Write only observations about circulation, daylight, and surface materials that can be supported by the footage, and match each observation to the relevant timestamp. Do not infer technical features that are not visible.

This prompt uses circulation, light, and materials as a checklist. It also asks the model not to present technical information that it cannot verify from the footage as fact. Treat the output as an initial review note, not as a project decision.

Common mistakes and choosing a processing mode

The most common issue is choosing an input method that is unsuitable for the video’s size or length. The guide recommends the Files API when the total request exceeds 20 MB, the video is long, or the same content will be used in other requests. Since the inline data limits are not consistent across different sections of the documentation, do not force this method for large files.

The second consideration is the processing mode. By default, the static method extracts frames from the video at a fixed rate of one frame per second. This mode is recommended for short clips, general summaries covering the whole video, latency-sensitive tasks, or frame-level analysis across an entire clip. Agentic processing dynamically navigates the timeline; it can be used to search for a specific event in a long video or find a single piece of information in a lengthy recording. The guide considers this option suitable for long content exceeding 5–10 minutes and targeted searches.

Agentic mode is listed for the Gemini 4 Argon, 3.8 Flash, 3.6 Flash, and 3.5 Flash Lite models. Google says that for long content, this mode can use up to 88 percent fewer tokens and deliver an approximately 7 percent increase in quality; this is a vendor claim, not a guarantee for every video. Another source of error is prompting the model to present measurements, material types, or project information that cannot be determined with certainty from the footage as verified facts.

Next steps and the impact on architectural workflows

Start with a short, non-public work video and a general summary request, then move on to a question about a specific scene. For long videos, consider agentic processing; for files you plan to reuse, consider the Files API. Keep in mind that the YouTube URL feature is in preview and that pricing and rate limits may change. Video generation is a different use case: the current Gemini API video guide points to Gemini Omni Flash for generation and conversational editing; Veo 3.1 Preview is stated to have been shut down in the API on 22 October 2026.

For architecture firms and visualization teams, the most practical use is to produce an initial summary and searchable observation notes from a project walkthrough or site video. This does not mean a design decision or measurement has been verified; outputs should be checked against the footage. The guide does not provide local hardware requirements or API pricing. When planning a workflow, separately check file size, upload requirements, access, and licensing terms; do not assume that a local GPU is required.

Sources and licensing

This guide has been adapted into Turkish using Google’s Gemini API video understanding and video generation guides. The video understanding guide is licensed under CC BY 4.0. The sample prompts were written specifically for this guide; code examples were not copied from the source text.