Analizar videos arquitectónicos con Gemini API: guía paso a paso

Qué aprenderás en esta guía

Este tutorial explica cómo crear un flujo de trabajo básico para analizar, mediante Gemini API, un video de presentación arquitectónica, una grabación de obra, un recorrido por un interior o un video del proceso de diseño. El objetivo no es generar un video nuevo, sino proporcionar al modelo uno existente y pedirle un resumen, respuestas sobre escenas concretas o una descripción del contenido. La documentación de Google sobre comprensión de videos enumera capacidades como describir el video, dividirlo en segmentos y extraer información; responder preguntas sobre su contenido y consultar marcas de tiempo.

Los ejemplos incluyen solicitudes de texto que se enviarán a la API. No son instrucciones que garanticen un resultado; sirven para indicar con claridad qué tipo de información se busca en el video. Antes de utilizar la respuesta para tomar decisiones sobre un proyecto, realizar mediciones o verificar aspectos técnicos, compárala con las imágenes originales.

Requisitos y selección del archivo

Para este flujo de trabajo necesitas acceso a Gemini API y una integración que permita enviar el video. Los ejemplos oficiales utilizan Python, JavaScript, Java, Go y REST; los pasos siguientes no dependen de un lenguaje de programación específico. El ejemplo de REST utiliza una clave llamada GEMINI_API_KEY. La documentación de video utilizada aquí no detalla las condiciones de acceso a la API ni los requisitos de cuenta.

En el ejemplo de solicitud a la API, el nombre del modelo es gemini-3.8-flash. Este es el modelo utilizado en el ejemplo de comprensión de video. Para generar videos, hay una guía aparte: Google menciona Gemini Omni Flash para la generación general de video y la edición con diálogo, y Veo 3.1 para necesidades como extender escenas o controlar el último fotograma. No confundas estos dos casos de uso.

Antes de enviar el archivo, comprueba su tamaño y si se utilizará más de una vez:

• Google recomienda Files API para videos de más de 100 MB o de larga duración, así como para archivos que se vayan a reutilizar. La tabla de la documentación indica un límite de Files API de 2 GB para el uso gratuito y de 20 GB para el uso de pago.

• Para la opción Cloud Storage Registration, se especifica un límite de 2 GB por archivo; también se indica que no hay un límite adicional de almacenamiento.

• El método de URL de YouTube se indica para videos públicos de YouTube.

• Los datos en línea son adecuados para archivos pequeños de un solo uso. La tabla de la documentación relaciona este método con archivos de menos de 100 MB y videos cortos; además, la sección de implementación indica que la solicitud total debe pesar menos de 20 MB. Como se trata de dos criterios distintos, lo más prudente al enviar datos en línea es respetar el límite inferior de 20 MB para la solicitud total.

Flujo de análisis paso a paso

1. Define qué pregunta quieres responder sobre el video. En lugar de pedir simplemente “analiza el video”, especifica qué información necesitas. Por ejemplo, en un recorrido interior puedes solicitar por separado la distribución de los espacios, los materiales visibles y las zonas por las que pasa la cámara. No des por sentado que el modelo detectará medidas que no aparecen en la imagen o capas ocultas de la construcción.

2. Envía el archivo con el método adecuado. Si el archivo es grande o se va a reutilizar, opta por Files API. En el flujo oficial de ejemplo se carga el video, se espera a que se procese y, cuando su estado es ACTIVE, se envía la referencia del archivo junto con la solicitud de texto. Si el procesamiento falla, el ejemplo de la documentación trata el estado FAILED como un error. Para videos pequeños se pueden usar datos en línea; comprueba el tamaño del archivo teniendo en cuenta el límite de la solicitud total.

3. Envía la solicitud junto con el contenido del video. La solicitud incluye la entrada de video y la petición de análisis como entrada de texto. En el ejemplo de Python, el archivo se carga mediante Files API; en el ejemplo para contenido más pequeño, los bytes del video se envían en línea. Independientemente de la integración que elijas, es necesario proporcionar correctamente el tipo MIME del video y la referencia al archivo.

4. En la primera prueba, pide un resultado acotado. Puedes añadir por separado los siguientes ejemplos a la parte de texto de la solicitud. Cada uno se centra en un objetivo distinto de análisis arquitectónico.

Bu mimari iç mekân videosunu sahne sırasına göre özetle. Görüntüde açıkça görülen mekânları, malzeme izlenimlerini ve kamera hareketlerini ayrı maddeler hâlinde belirt. Görüntüde olmayan bilgileri tahmin etme; belirsiz noktaları açıkça işaretle.

Esta solicitud organiza la descripción general en espacios, materiales y movimientos de cámara. Considera las menciones de materiales como impresiones visuales observadas en el video, no como descripciones técnicas definitivas.

Videoda girişten ana yaşam alanına geçişin görüldüğü bölümü bul. İlgili zaman damgasını belirt ve o anda kadrajda görünen mekânsal ilişkileri kısaca açıkla. Bölüm net değilse bunu söyle; zaman veya plan bilgisi uydurma.

Este texto plantea una pregunta sobre una escena basándose en una marca de tiempo. Abre el video y comprueba el momento indicado en la respuesta; aunque la documentación menciona la capacidad de hacer referencia a marcas de tiempo, no garantiza una correspondencia perfecta en cada solicitud.

Bu şantiye videosunda tamamlanmış görünen imalatları ve hâlen devam ettiği açıkça anlaşılan işleri ayır. Her bulguyu videoda görülen sahneyle ilişkilendir; yapısal güvenlik, ölçü veya mevzuat uygunluğu hakkında çıkarım yapma.

Este ejemplo pide una clasificación que puede ayudar a organizar un registro visual, pero no proporciona una aprobación de seguridad ni de cumplimiento. Compara las respuestas con los registros del equipo de obra.

1. Revisa la respuesta y acota la solicitud. Si el resumen general no es suficiente, formula una nueva pregunta describiendo un espacio, una escena o un intervalo de tiempo concreto que aparezca en el video. Las capacidades de comprensión de video de Gemini incluyen hacer preguntas sobre el contenido y consultar marcas de tiempo. Verifica los hallazgos importantes en el video antes de utilizar la respuesta.

Errores frecuentes

No comprobar el método según el tamaño del archivo: Se recomienda Files API para archivos grandes o que se vayan a reutilizar. Aunque se considere el método en línea para archivos pequeños, la documentación también establece un límite de 20 MB para la solicitud total; quizá no baste con comprobar solo el tamaño del archivo de video.

Solicitar el análisis antes de que termine el procesamiento: El ejemplo de Files API espera a que el archivo pase a ACTIVE después de cargarlo. Utilizar la referencia al archivo sin esperar a que se complete el procesamiento no coincide con el flujo de ejemplo.

Confundir el análisis de video con su generación: Para analizar una grabación existente, utiliza la guía de comprensión de video. La documentación describe Gemini Omni Flash y Veo 3.1 como flujos de trabajo distintos para la generación y edición de video.

Extraer conclusiones técnicas definitivas de la imagen: Pide al modelo que describa los elementos visibles; no presentes como información verificada las medidas, propiedades de los materiales o el cumplimiento de la obra si no aparecen en la imagen. Comprueba también la correspondencia entre las marcas de tiempo y las escenas en el video original.

Efectos en los flujos de trabajo de arquitectura e interiores

Este método puede ser un punto de partida para estudios de arquitectura, interioristas y estudiantes que quieran localizar escenas en videos de presentación largos, organizar un recorrido interior por temas o identificar trabajos visibles en una grabación de obra. Files API resulta práctico, especialmente para archivos grandes que se reutilizarán; el envío en línea es una alternativa para pruebas pequeñas de un solo uso. Sin embargo, la fuente no explica el costo de uso ni los requisitos específicos de hardware. Por ello, antes de implementarlo, conviene revisar aparte las condiciones de costo y compatibilidad; la respuesta del modelo no debe sustituir una validación técnica.

Próximos pasos

Primero, genera un resumen general de una grabación breve y representativa; después, concreta el resultado con preguntas centradas en escenas o marcas de tiempo. Si vas a enviar varias solicitudes sobre el mismo video, considera la recomendación de Google de utilizar Files API. Si también necesitas generar videos con la API, consulta la documentación de Gemini Omni Flash y Veo 3.1 por separado del flujo de comprensión de video.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de la documentación de Google sobre comprensión de video y generación de video con Gemini API. Ambas fuentes tienen licencia CC BY 4.0.