Guía para convertir imágenes arquitectónicas en resultados JSON con Gemini API

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

Es posible extraer notas organizadas sobre espacios, objetos o características visibles en una imagen arquitectónica y después recibirlas en formato JSON. En esta guía explicamos paso a paso cómo enviar texto e imágenes a Gemini API, redactar instrucciones claras y definir la estructura de la respuesta mediante un esquema. Los ejemplos se basan en una imagen de interior; también indicamos cómo expresar la incertidumbre en las instrucciones para evitar que el modelo deduzca medidas o materiales que no se aprecian en la imagen.

La documentación de Gemini API de Google presenta la comprensión de imágenes en aplicaciones como la descripción y clasificación de imágenes, así como la respuesta a preguntas visuales. Las imágenes pueden enviarse mediante una URL, como datos en línea o a través de Files API. En este ejemplo se utiliza gemini-3.8-flash, que aparece en los ejemplos de la documentación.

Requisitos

• Un cliente o una solicitud REST que permita trabajar con Gemini API. Además de ejemplos para Python y JavaScript, la documentación incluye ejemplos para Java y Go.

• Un método para enviar la imagen a la API: datos en línea codificados en base64 para imágenes pequeñas, o Files API para archivos grandes o imágenes que se vayan a reutilizar.

• Si se necesita una respuesta JSON, un JSON Schema que defina los campos de la respuesta. En los SDK de Google GenAI, el esquema se puede definir con Pydantic para Python y Zod para JavaScript.

• Si se utiliza REST, una clave de API en la solicitud. Esta guía no presupone información sobre la creación de cuentas, los precios o las cuotas de uso que no aparezca en las fuentes.

Imaginemos, por ejemplo, que queremos obtener una lista estructurada de los objetos visibles y su ubicación en una imagen de interior. El siguiente esquema muestra una estructura sencilla que puede servir para este propósito. Los campos se pueden adaptar al flujo de trabajo real; lo importante es que coincidan con la respuesta esperada en las instrucciones.

{
  "type": "object",
  "properties": {
    "gozlemler": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unsur": { "type": "string" },
          "konum": { "type": "string" },
          "gorunur_ozellik": { "type": "string" }
        },
        "required": ["unsur", "konum", "gorunur_ozellik"]
      }
    }
  },
  "required": ["gozlemler"]
}

Pasos de implementación

1. Define la imagen y el objetivo

Primero, aclara qué pregunta debe responder el análisis de la imagen. Por ejemplo, el objetivo puede ser enumerar los muebles visibles en una perspectiva o describir las características visibles de las superficies. No solicites medidas, sistemas constructivos ni información sobre productos que no aparezcan en la imagen. Si estos datos no se pueden determinar con certeza a partir de la imagen, pide al modelo que lo indique explícitamente.

2. Redacta instrucciones claras y delimitadas

La guía de diseño de instrucciones de Google recomienda especificar con claridad la tarea y sus restricciones, y describir el formato de respuesta deseado. El siguiente ejemplo aplica este enfoque a una imagen de interior:

Görseli bir iç mekân sunum paftasını inceler gibi değerlendir. Yalnızca görüntüde açıkça seçilebilen unsurları listele. Her unsur için kısa bir konum tarifi ve görülebilir özelliğini yaz. Ölçü, marka veya malzeme türünü görüntüden kesin biçimde belirleyemiyorsan tahmin etme; bunu belirt. Yanıtı, tanımladığım JSON şemasındaki alanlara uygun biçimde ver.

Las instrucciones definen la tarea y su alcance; el esquema establece los campos de la respuesta. Decir únicamente «analiza la imagen» deja en manos del modelo la decisión sobre qué detalles son importantes. Especificar de antemano los campos necesarios y la información que no debe inferirse facilita el uso de los resultados en las notas del proyecto. Aun así, el resultado no sustituye una medición verificada ni una inspección técnica del contenido de la imagen.

3. Añade la imagen a la solicitud de la API

Puedes codificar una imagen pequeña en base64 y enviarla en el campo data. En la documentación, este método utiliza los datos de la imagen y su tipo MIME junto con una instrucción de texto. El tamaño total de la solicitud —incluidas las imágenes en línea, el texto de la instrucción y las instrucciones del sistema— está limitado a 20 MB. Si se puede superar ese límite, hay que subir el archivo a Files API y añadir a la solicitud la URI que devuelve.

La documentación recomienda Files API para archivos grandes o cuando se vaya a utilizar la misma imagen en varias solicitudes. Incluye tanto la entrada de texto como la imagen en la solicitud y especifica el tipo MIME correspondiente. image/jpeg es uno de los tipos de imagen que aparecen en los ejemplos de la documentación.

4. Configura el formato de respuesta JSON

Con la función Structured outputs, se establece el formato JSON y se añade el esquema a la solicitud. En el ejemplo REST de la documentación, se asigna a mime_type el valor application/json y el esquema se incluye en el campo schema. El ejemplo de Python también genera JSON Schema a partir de un modelo Pydantic y valida la respuesta con ese modelo; el ejemplo de JavaScript utiliza un esquema Zod.

Evita que el esquema crezca innecesariamente en los flujos de trabajo arquitectónicos. Por ejemplo, si solo necesitas el objeto, su ubicación y sus características visibles, añadir campos que el flujo de trabajo no utiliza puede aumentar el trabajo de mantenimiento y revisión. Asegúrate también de que los campos obligatorios del esquema coincidan con la información solicitada en las instrucciones.

5. Revisa la respuesta antes de utilizarla

Comprueba si los campos definidos están completos y si su contenido coincide con la imagen. Structured outputs facilita obtener respuestas que se ajusten formalmente al esquema, pero eso no significa que la interpretación visual sea siempre correcta. Verifica por separado las conclusiones sobre materiales, medidas o decisiones de diseño con planos, documentación del proyecto o una revisión profesional.

Usar el mismo esquema para varias imágenes puede facilitar la comparación de resultados. En cada solicitud, indica claramente desde qué perspectiva debe analizarse la imagen y prueba pequeñas variaciones en las instrucciones para comparar las respuestas. El diseño de instrucciones es un proceso iterativo: en lugar de considerar definitivo el primer intento, observa los campos incorrectos o innecesarios y aclara las instrucciones.

Errores frecuentes

• Solicitar como dato seguro algo que no se ve en la imagen: La perspectiva, la resolución o el encuadre pueden hacer que ciertos detalles sean ambiguos. Pide al modelo que exprese la incertidumbre en lugar de hacer suposiciones.

• Plantear el esquema y las instrucciones de forma inconsistente: Si las instrucciones solicitan campos que no están en el esquema, o si el esquema exige un campo que la tarea no explica, será más difícil aprovechar los resultados. Revisa ambos elementos conjuntamente.

• Enviar archivos grandes como datos en línea: Los datos de imagen en línea están sujetos al límite de 20 MB para el tamaño total de la solicitud. Para archivos grandes, utiliza Files API.

• Confundir el formato JSON con una garantía de exactitud: Una respuesta estructurada no demuestra que la información coincida con certeza con la imagen. Comprueba por separado las decisiones técnicas y de diseño importantes.

• Considerar definitiva la primera versión de las instrucciones: Aunque la tarea y las restricciones estén bien explicadas, es necesario revisar los resultados con ejemplos reales e iterar las instrucciones.

Efectos en los flujos de trabajo de arquitectura y archviz

Este método puede ser útil para estudios de arquitectura, interioristas y estudiantes que quieran describir imágenes de interiores de sus archivos, generar listas estructuradas de observaciones a partir de imágenes de presentación o comparar distintas imágenes con campos comunes. El formato JSON ayuda a mantener los datos organizados en tareas de evaluación y clasificación que utilizan los mismos campos de forma recurrente. Sin embargo, los resultados no deben incorporarse directamente a planos o documentación técnica como información verificada.

Para garantizar la compatibilidad, el cliente y la solicitud a la API deben admitir los formatos de entrada de imágenes y structured outputs descritos en la documentación. La elección entre enviar la imagen en línea o utilizar Files API debe depender del tamaño del archivo y de si se va a reutilizar. Como las fuentes de esta guía no especifican las condiciones de acceso a la API ni los costos, conviene comprobar las condiciones vigentes de acceso y licencia antes de incorporarla a un flujo de trabajo real de estudio.

Próximos pasos

Empieza probando un esquema pequeño con algunas imágenes representativas. Identifica los campos que se repiten en las respuestas y que realmente se utilizarán en el flujo de trabajo; marca aparte las observaciones que sigan siendo ambiguas. Después, revisa conjuntamente las instrucciones, el esquema y el método de envío de imágenes. Si necesitas estructuras JSON más completas, consulta los ejemplos de los SDK en la documentación de structured outputs de Gemini API. Para la entrada de imágenes, puedes consultar también la guía Image understanding.

Fuentes y licencia

Este contenido se ha adaptado al turco a partir de las guías «Structured outputs», «Image understanding» y «Prompt design strategies» de Google AI for Developers. Las tres fuentes se publican bajo la licencia CC BY 4.0.