Análisis de videos de arquitectura con Gemini API: guía paso a paso

¿Qué aprenderás en esta guía?

Gemini API puede utilizarse para extraer información de videos y responder preguntas sobre su contenido. Esta guía aborda los pasos para elegir el método de transferencia adecuado, esperar a que se procese el archivo y preparar prompts relevantes para analizar videos como presentaciones de proyectos arquitectónicos, grabaciones de obras o recorridos por espacios. Los modelos Gemini pueden describir el video, extraer información de su contenido y hacer referencia a marcas de tiempo específicas. Así, en vez de revisar manualmente una grabación larga de principio a fin, se puede solicitar un resumen o una respuesta centrada en un aspecto concreto.

Los ejemplos de esta guía se centran en comprender videos existentes, no en generarlos. La guía de generación de video de Google identifica Gemini Omni Flash para esa tarea; la comprensión de videos es un uso distinto. Mantener clara esta diferencia reduce el riesgo de elegir un modelo o flujo de trabajo inadecuado para una solicitud de análisis.

Requisitos

Este flujo de trabajo requiere acceso a Gemini API, un archivo de video o un video público de YouTube y un prompt de texto. El ejemplo oficial utiliza el cliente de Python google-genai, Files API e Interactions API. Como la fuente no especifica una versión concreta del SDK ni pasos para crear una cuenta, aquí no se indica un número de versión ni requisitos de registro. Configura la autenticación del cliente API según tu entorno; el ejemplo REST de la fuente utiliza la variable GEMINI_API_KEY.

Elige el método de transferencia según el tamaño del archivo y si necesitas reutilizarlo:

• Files API: La fuente recomienda este método para archivos de más de 100 MB, videos largos y contenido que se vaya a reutilizar. El documento indica una capacidad de 20 GB para el uso de pago y de 2 GB para el uso gratuito.

• Cloud Storage Registration: Se especifica un límite de 2 GB por archivo y que no hay límite de almacenamiento; está pensado para contenido grande, que se conservará durante mucho tiempo y se reutilizará.

• Datos en línea: El documento indica que es adecuado para archivos pequeños. Las instrucciones detalladas recomiendan este método para enviar videos cortos cuando el tamaño total de la solicitud sea inferior a 20 MB; por tanto, en la práctica, aplica el umbral más restrictivo de 20 MB.

• URL de YouTube: Es un método de entrada admitido para videos públicos.

Análisis de video paso a paso

1. Define el objetivo del análisis

Antes de enviar el video, concreta qué resultado esperas obtener. En una presentación de proyecto, podrías pedir un resumen general; en un recorrido por un espacio, una lista de los materiales visibles; o una explicación de un momento concreto de la grabación. En lugar de solicitar resultados muy distintos en una sola consulta, indica claramente el objetivo principal y el formato de respuesta. También puedes pedir que el modelo informe solo de lo que aparece en la grabación para evitar que complete información que no está en el video.

Por ejemplo, puedes utilizar este prompt para obtener un resumen breve y organizado de las observaciones de un video de un interior:

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.

Este prompt organiza en apartados distintos los espacios, la circulación, la iluminación y los materiales visibles en el video. En vez de nombrar con certeza un material que no se distinga en la imagen, pide que la respuesta se base únicamente en detalles observables.

2. Elige el método de transferencia adecuado para el archivo

Si el video es grande, largo o se reutilizará en solicitudes posteriores, opta por Files API. Para un archivo corto, puedes considerar la transferencia en línea, pero asegúrate de que la solicitud total no supere los 20 MB. Para un video público de YouTube, considera el método de URL. Comprueba el tamaño del archivo y las condiciones de uso antes de enviarlo; la fuente presenta por separado los límites de capacidad para el uso gratuito y el de pago.

3. Sube el archivo con Files API y espera a que se procese

El ejemplo oficial de Python carga el archivo con client.files.upload y comprueba su estado hasta que sea ACTIVE. Que el archivo se haya cargado no significa que esté listo para analizarse: espera a que termine el procesamiento. En el ejemplo siguiente, el estado se consulta cada cinco segundos. Este código se basa en el ejemplo de licencia abierta de la fuente:

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)

Sustituye path/to/sample.mp4 por la ruta del archivo que quieras analizar. El ejemplo de la fuente muestra cómo utilizar la referencia al archivo como entrada de video una vez que esté lista. Si el procesamiento falla, no des por hecho que el archivo está listo: comprueba que su estado avance.

4. Envía el video junto con el prompt mediante Interactions API

Cuando el archivo alcance el estado ACTIVE, añade el URI del video y el prompt de texto a las entradas de la misma interacción. El ejemplo de la fuente utiliza el nombre de modelo gemini-3.8-flash. El siguiente prompt está pensado para examinar la secuencia espacial y las transiciones de un video de presentación:

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.

Pedir marcas de tiempo ayuda a relacionar las observaciones con secciones concretas de la grabación. Indicar explícitamente que el modelo no debe inferir dimensiones ni intenciones de diseño que no puedan verificarse en el video mantiene la respuesta dentro de los límites de la inspección visual.

5. Ajusta el resultado a las necesidades del proyecto

Si la primera respuesta es demasiado general, en vez de volver a describir el video, centra la pregunta de seguimiento en un tema concreto. La guía de video de Gemini explica la edición mediante conversaciones de varios turnos en el contexto de la generación de video; el documento sobre comprensión de videos describe la capacidad de hacer preguntas sobre videos y referirse a marcas de tiempo. En este caso de análisis, limita la pregunta a la sección que se debe revisar o al tipo de observación que buscas.

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.

Este prompt limita la respuesta a los cambios de iluminación y de apariencia de los materiales. Pedir que se marque como «poco claro» lo que no sea seguro ayuda a evitar que los detalles con baja calidad de imagen o fuera de cuadro se presenten como información confirmada.

Errores frecuentes

• Enviar un video grande en línea: Las instrucciones detalladas de la fuente consideran adecuada la transferencia en línea para videos cortos cuya solicitud total sea inferior a 20 MB. Para archivos grandes, considera Files API.

• Solicitar el análisis antes de que se procese el archivo: Comprueba que el estado sea ACTIVE después de la carga; en el ejemplo, el estado del archivo se consulta periódicamente.

• Redactar un prompt demasiado amplio o impreciso: En lugar de una petición general como «analiza el video», céntrate en un objetivo, como un resumen, las transiciones espaciales o los materiales visibles.

• Esperar información que no aparece en la imagen: La comprensión de videos sirve para examinar la información visual del contenido; no debe suponerse que verifica dimensiones del proyecto o decisiones de diseño que no figuran en la grabación.

• Confundir la guía de generación de video con la de análisis: Para comprender un video existente, consulta la documentación sobre comprensión de videos. Google informa que Veo 3.1 Preview dejará de estar disponible en Gemini API el 22 de octubre de 2026 y que, para generar videos, se debe pasar a Gemini Omni Flash; este cambio no sustituye los pasos de análisis.

Usos en flujos de trabajo de arquitectura, diseño de interiores y archviz

Los equipos de arquitectura y diseño de interiores pueden probar este método para obtener un primer resumen de observaciones a partir de una presentación de proyecto o una grabación de un espacio, localizar momentos importantes mediante marcas de tiempo y responder preguntas sobre la grabación. Los equipos de archviz también pueden explorar un flujo de preguntas y respuestas sobre el contenido de un video de presentación existente. Sin embargo, el resultado debe limitarse a lo que muestra el video; las dimensiones, la viabilidad técnica o la aplicabilidad en el proyecto, entre otros aspectos que no puedan verificarse en la grabación, deben comprobarse por separado.

Como los límites de Files API se especifican de forma distinta para el uso gratuito y el de pago, los equipos deben revisar el tamaño del archivo del proyecto y las condiciones de acceso que utilizan antes de enviarlo. La fuente no explica los requisitos de hardware, los detalles de precios ni la integración con software local; por tanto, no des por sentado que este flujo de trabajo esté conectado con las herramientas de modelado o render existentes.

Próximos pasos

Empieza con un video corto y autorizado de un proyecto y prueba un prompt de resumen; después, añade preguntas de seguimiento sobre marcas de tiempo o tipos concretos de observaciones. Si el archivo es grande o se va a reutilizar, considera el método Files API. Antes de incorporar los resultados a las notas del proyecto, abre el video en los momentos pertinentes y verifica las observaciones del modelo. Para obtener detalles de implementación sobre la carga de archivos o la selección de modelos, consulta la documentación oficial de Gemini API sobre comprensión y generación de videos.

Fuente y licencia

Esta guía se ha adaptado al turco a partir de la información de los documentos de Google sobre comprensión y generación de videos con Gemini API. Ambas fuentes están bajo la licencia CC BY 4.0. El ejemplo de código Python procede del documento de comprensión de videos, publicado bajo una licencia abierta.