Analyze Architecture Videos with the Gemini API: A Step-by-Step Guide

What will you learn in this guide?

The Gemini API can help identify the spaces shown in a project video, turn a presentation recording into a short summary, or answer questions about what happens at a particular second. Google’s video understanding guide documents use cases such as describing videos, extracting information from their content, and answering questions based on timestamps.

This guide focuses on analyzing existing videos used in architectural visualization (archviz), interior design, and project presentations. Unlike video generation, the input here is a pre-existing video file or a publicly available YouTube video. Depending on the question you ask, the result may be a summary or an answer about specific details.

Requirements and choosing a video

The examples in Google’s Gemini API documentation cover Python, JavaScript, Java, Go, and REST. The Python examples use the google-genai library, but the guide does not specify a required library version. No version number is therefore given here. You’ll need to use your development environment’s API configuration to access and authenticate with the API; the source does not detail account setup.

Before sending a video, consider its file size and how you plan to use it:

• Google’s comparison table lists a 20 GB limit for the Files API on paid usage and a 2 GB limit on free usage. This method is suitable for large files, long videos, and files you plan to reuse.

• Cloud Storage Registration is listed with a 2 GB per-file limit and no overall storage limit. It is presented as an option for persistent, reusable files.

• Inline Data is shown in the table for files under 100 MB. However, the same guide recommends attaching short videos directly to a request only when the total request is under 20 MB. When choosing a method, account for the size of the entire request, not just the video file.

• Public YouTube videos are also listed as an input method.

Google recommends the Files API for most use cases, especially for videos larger than 100 MB or those that will be reused across different requests. The documentation also advises using the Files API if the total request exceeds 20 MB, the video is long, or the same file will be used in multiple prompts.

Video analysis, step by step

1. Set your analysis goal. Instead of a broad request such as “Summarize the video,” specify what information you need. For example, you could ask separately about the sequence of spaces, visible changes in materials and lighting, or design decisions explained in the presentation. Rather than asking the model to infer details that aren’t in the video, tell it to base its response on evidence from the visuals or narration.

2. Choose a transfer method. Inline data may work for a small, one-off clip; the Files API is a better fit for large, long, or reusable videos. Don’t skip the step of uploading the file and waiting for it to be processed: Google’s examples check the file’s status until it becomes ACTIVE. The example also accounts for the possibility that file processing may fail.

3. Include the video and text input together in the request. In the guide’s examples, the video is passed as a file URI and MIME type, along with a text instruction for the analysis. The model name used in the examples is gemini-3.8-flash. Check the API documentation for model and availability information relevant to your application; no version or availability guarantee is assumed here beyond the name shown in the example.

You can use the following text as an instruction alongside the video input:

Bu mimari proje videosunu kısa bir özette anlat. Görünen mekânları videoda izlendikleri sırayla listele. Videoda açıkça görülmeyen özellikleri tahmin etme; emin olmadığın ayrıntıları belirt.

This prompt can help turn a project recording into a structured summary. Compare the results with the footage before using them as presentation notes or for an initial team review.

1. Ask a specific review question. Gemini models can answer questions about video content and refer to timestamps. To find a key moment in a presentation board walkthrough or camera tour, narrow the question to a space or event:

Videoda mutfak mekânının ilk göründüğü zamanı bul. Zaman damgasını ver ve o anda görülebilen sabit donatıları, yalnızca görüntüde seçilebildikleri ölçüde açıkla.

This prompt directs the model to look for a specific space. Check the timestamp against the edit or presentation sequence; the source guide does not guarantee that results will always be error-free.

1. Ask separately about materials and lighting. Breaking the review into categories makes it easier to evaluate the response than asking for many details in one broad question:

Bu iç mekân videosunda görülebilen yüzey ve malzeme özelliklerini sıralı biçimde açıkla. Her gözlemi ilgili zaman damgasıyla eşleştir; malzeme türü kesin seçilemiyorsa bunu tahmin olarak sunma.

This prompt focuses on describing visible surfaces; it does not ask the model to identify an exact product or material brand. Base design decisions on the actual project documents.

1. Turn the response into a short checklist. If the team needs to follow up on points from a presentation video, ask the model to separate information that is explicitly stated from information that is not:

Bu proje sunumunda açıkça belirtilen tasarım kararlarını ve çözümsüz bırakılan soruları iki ayrı listede özetle. Her maddeyi destekleyen zaman damgasını ekle; videoda yanıtı olmayan noktaları boşlukları doldurmadan belirt.

This type of output can help organize post-meeting notes. Verify important decisions against the meeting recording or project documents.

Common mistakes

Using the wrong method for the file size: Although the documentation table lists Inline Data for files under 100 MB, the same guide limits direct inline use to short videos where the total request is under 20 MB. Follow the Files API recommendation for large files or long videos.

Starting analysis before the file is ready: Google’s examples check the processing status after upload and wait until the file becomes ACTIVE. Don’t move on to the next request until this step is complete.

Inferring details that aren’t clear from the video: The actual material, dimensions, or product name of a surface may not be visible. Asking only for observable evidence and explicitly flagging uncertainty can reduce the risk of false certainty.

Confusing video analysis with video generation: The Gemini API video generation page states that Veo 3.1 Preview was shut down on 22 October 2026, and directs users to Gemini Omni Flash for video generation. This is a different operation from the steps in this guide for analyzing existing videos.

Using video analysis in architecture and visualization workflows

This approach can be a starting point for architecture firms, interior designers, and visualization teams that want to quickly review project presentations, interior walkthroughs, or construction-site footage. For example, you can find when a particular space appears, compile design decisions from a meeting recording, or produce an initial summary of a presentation. However, the sources do not say that the model directly analyzes BIM files, drawings, or 3D scenes; this guide covers working with video content.

Before setting up a workflow, choose a transfer method based on file size, duration, and whether you’ll reuse the file. Large or long recordings point to the Files API; the source lists different file limits for paid and free usage. The guide does not provide information about pricing, project privacy, retention periods, or the hardware required on a particular workstation; assess these separately based on your own use case.

Next steps

Run your first test on a short project recording that does not contain critical decisions. Start by asking for a general summary, then test the results with questions focused on a specific space or timestamp. Distinguish visible evidence from the model’s interpretation, and compare notes shared with the team against the source video and project documents. If you’ll use the same video across multiple requests, follow Google’s recommendation to use the Files API.

Sources and license

This guide is adapted into Turkish from Google’s Gemini API guides “Video understanding” and “Video generation in the Gemini API.” Both pages specify a CC BY 4.0 license for their content unless otherwise stated.