Análisis de video con Gemini API: guía paso a paso para contenido arquitectónico

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

Con Gemini API, puedes hacer más que pedir un resumen de un video: también puedes preguntar sobre su contenido, solicitar descripciones de escenas específicas y consultar información relacionada con marcas de tiempo. Estas funciones pueden utilizarse para revisar presentaciones de proyectos arquitectónicos, recorridos por interiores, grabaciones de obra o videos que muestran el proceso de diseño. Los pasos siguientes se centran en proporcionar el video como entrada de forma adecuada y formular una pregunta clara.

Los prompts de ejemplo se han creado específicamente para flujos de trabajo de arquitectura e interiores. El enfoque general de la documentación consiste en enviar el archivo de video al modelo junto con una solicitud de texto que incluya instrucciones sobre el contenido.

Requisitos y selección de la entrada

Para empezar, necesitas acceso a Gemini API, un entorno de trabajo con el cliente de API configurado y un video para analizar. La guía oficial incluye ejemplos para Python, JavaScript, Go y REST. El ejemplo de Python importa el módulo genai del paquete google; como no se especifica una versión concreta del SDK, aquí no indicamos ningún número de versión.

Elige el método de entrada según el tamaño del archivo y el uso que le darás:

• Files API: Se recomienda para archivos grandes, videos largos y contenido que se vaya a reutilizar. La tabla de la guía indica un límite máximo de 20 GB para el nivel de pago y de 2 GB para el nivel gratuito. Puedes esperar a que se procese el archivo subido y usar la referencia de archivo devuelta en la solicitud de contenido.

• Datos en línea: Se pueden utilizar para videos pequeños y de un solo uso. En distintas secciones de la guía, el límite aparece como menos de 100 MB en la tabla y menos de 20 MB para la solicitud total en la descripción de la aplicación. Por eso, si eliges el método en línea, toma como referencia el límite más prudente: 20 MB para la solicitud total.

• URL de YouTube: Se pueden proporcionar directamente como entrada videos públicos. Esta función está en fase de vista previa; se indica que los precios y los límites de velocidad podrían cambiar. En el nivel gratuito no se pueden subir más de 8 horas de videos de YouTube al día; no se especifica un límite basado en la duración para el nivel de pago.

La documentación también incluye el registro mediante Cloud Storage: el límite máximo es de 2 GB por archivo y no se especifica un límite de almacenamiento. Se presenta como una opción para archivos persistentes y reutilizables.

Análisis de video paso a paso

1. Define el video y la pregunta objetivo. Primero, aclara si quieres resumir todo el video o encontrar un momento concreto. Por ejemplo, buscar dónde comienza el recorrido en un tour de interiores es una tarea distinta de pedir un resumen general.

2. Elige el método de entrada adecuado. Para un clip pequeño, corto y de un solo uso, puedes considerar los datos en línea. Si la solicitud total supera los 20 MB, el video es largo o se reutilizará, Files API es la opción preferida según la guía. Para usar YouTube, el video debe ser público.

3. Añade el archivo a la solicitud. En el ejemplo oficial de Python, el archivo se sube con client.files.upload(...); después, el objeto de archivo devuelto y las instrucciones de texto se pasan juntos a la llamada client.models.generate_content(...). Esperar a que el archivo se procese también forma parte del flujo del ejemplo. Para la entrada de YouTube, se añade el enlace a la solicitud como archivo de video.

4. Convierte el prompt en una tarea observable. En lugar de una instrucción amplia como «analiza el video», describe qué información quieres y en qué formato debe presentarse la respuesta. Pedir primero un resumen general y después preguntar por un elemento o una marca de tiempo concretos facilita la evaluación de los resultados.

El siguiente prompt está orientado a extraer información general de un video corto de presentación arquitectónica:

Bu mimari proje videosunu kısa bir özetle anlat. Görünen mekânları ve videoda açıkça seçilebilen tasarım özelliklerini ayrı maddelerde belirt. Görüntüde doğrulanamayan bilgileri tahmin etme.

Este prompt se basa en las funciones de describir videos y extraer información de su contenido. También establece límites para evitar que el modelo invente detalles como el nombre del proyecto, los materiales o las medidas, que no se puedan verificar en la imagen.

Para encontrar el momento en que ocurre un evento concreto durante una grabación de obra o un recorrido por interiores, utiliza una pregunta más específica:

Videoda giriş mekânından ana yaşam alanına geçişin görüldüğü anı bul. Bu geçişin yaklaşık zaman damgasını ver ve görüntüde hangi mekânsal değişikliğin seçildiğini kısaca açıkla. Emin olmadığın bir zaman damgasını kesinmiş gibi sunma.

La guía indica que se pueden consultar marcas de tiempo específicas del video. Por ello, describir con claridad el evento que buscas dentro de la pregunta resulta más útil que una solicitud imprecisa como «encuentra los momentos importantes».

Para preparar un video de presentación para una revisión de diseño, puedes usar esta pregunta:

Bu videoda görülen mekânsal düzenlemeleri sırayla incele. Dolaşım, gün ışığı ve yüzey malzemeleri hakkında yalnızca görüntüden desteklenebilen gözlemleri yaz; her gözlemi ilgili zaman damgasıyla eşleştir. Görünmeyen teknik özellikleri çıkarım olarak belirtme.

Este prompt utiliza la circulación, la luz y los materiales como lista de comprobación. También pide al modelo que no presente como datos ciertos las características técnicas que no pueda verificar en las imágenes. Considera el resultado como notas para una revisión inicial, no como una decisión de proyecto.

Errores habituales y selección del modo de procesamiento

El problema más frecuente es elegir un método de entrada inadecuado para el tamaño o la duración del video. La guía recomienda Files API si la solicitud total supera los 20 MB, el video es largo o el mismo contenido se utilizará en otras solicitudes. Como los límites de los datos en línea no se indican de la misma manera en distintas secciones de la documentación, no fuerces este método para archivos grandes.

El segundo aspecto es el modo de procesamiento. El método estático predeterminado extrae fotogramas del video a una velocidad fija de un fotograma por segundo. Se recomienda para clips cortos, resúmenes generales que cubran todo el video, tareas sensibles a la latencia o análisis a nivel de fotograma durante todo el clip. El procesamiento agentic, en cambio, se desplaza de forma dinámica por la línea de tiempo; puede utilizarse para buscar un evento concreto en videos largos o encontrar un dato específico dentro de una grabación extensa. La guía considera que esta opción es adecuada para contenidos largos que superen los 5–10 minutos y para búsquedas dirigidas.

El modo agentic está disponible para los modelos Gemini 4 Argon, 3.8 Flash, 3.6 Flash y 3.5 Flash Lite. Google señala que, en contenidos largos, este modo puede usar hasta un 88 por ciento menos de tokens y ofrecer una mejora de calidad de aproximadamente un 7 por ciento; se trata de una declaración del proveedor, no de una garantía para todos los videos. Otra fuente de errores es pedir al prompt que presente como hechos verificados medidas, tipos de materiales o datos del proyecto que no se puedan determinar con certeza a partir de la imagen.

Próximos pasos y repercusiones en los flujos de trabajo de arquitectura

Haz la primera prueba con un video de trabajo corto, que no sea público, y una solicitud de resumen general; después, pasa a preguntas sobre una escena concreta. En videos largos, considera el procesamiento agentic y, para archivos que se vayan a reutilizar, Files API. Ten en cuenta que la función de URL de YouTube está en fase de vista previa y que los precios y los límites de velocidad podrían cambiar. La generación de video es un caso de uso distinto: la guía actual de video de Gemini API indica Gemini Omni Flash para la generación y la edición con diálogo; se señala que Veo 3.1 Preview se desactivó en la API el 22 de octubre de 2026.

Para los estudios de arquitectura y los equipos de visualización, el uso más concreto consiste en obtener un resumen inicial y notas de observación consultables a partir de recorridos de proyectos o videos de obra. Esto no significa que se hayan verificado una decisión de diseño o una medida; los resultados deben contrastarse con el video. La guía no proporciona requisitos de hardware local ni precios de la API. Por ello, al planificar el flujo de trabajo, comprueba por separado el tamaño de los archivos, el proceso de carga, las condiciones de acceso y licencia; no presupongas que se necesita una GPU local.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de las guías de Google sobre comprensión y generación de video con Gemini API. La guía de comprensión de video está bajo la licencia CC BY 4.0. Los prompts de ejemplo se han redactado específicamente para esta guía; los ejemplos de código no se han tomado del texto fuente.