Guide : convertir des images d’architecture en JSON avec l’API Gemini

Ce que vous apprendrez dans ce guide

Il est possible d’extraire d’une image d’architecture des notes structurées sur l’espace, les objets ou les caractéristiques visibles, puis de les obtenir au format JSON. Ce guide vous accompagne pas à pas pour envoyer à l’API Gemini du texte et une image, rédiger une invite claire et définir la structure de la réponse à l’aide d’un schéma. Les exemples s’appuient sur une image d’intérieur ; ils indiquent aussi comment signaler l’incertitude dans les invites afin d’éviter de faire deviner des dimensions ou des matériaux absents de l’image.

Dans la documentation de l’API Gemini de Google, la compréhension des images couvre des usages tels que la description d’image, la classification et les questions-réponses visuelles. Les images peuvent être transmises par URL, sous forme de données en ligne ou via la Files API. Dans cet exemple, nous utilisons le nom de modèle gemini-3.8-flash, qui figure parmi les exemples de la documentation.

Prérequis

• Un client ou une requête REST permettant d’utiliser l’API Gemini. La documentation propose des exemples en Python et JavaScript, ainsi qu’en Java et Go.

• Une méthode pour transmettre l’image à l’API : des données en ligne encodées en base64 pour les petites images, et la Files API pour les fichiers volumineux ou les images qui seront réutilisées.

• Si vous souhaitez obtenir du JSON, un JSON Schema définissant les champs de la réponse. Les SDK Google GenAI permettent de définir un schéma avec Pydantic en Python et Zod en JavaScript.

• Si vous utilisez REST, une clé API dans la requête. Ce guide ne formule aucune hypothèse sur la création d’un compte, les tarifs ou les quotas d’utilisation, car les sources ne les précisent pas.

Imaginons que nous souhaitions obtenir une liste structurée des objets visibles et de leur emplacement dans une image d’intérieur. Le schéma ci-dessous illustre une structure simple adaptée à cet objectif. Vous pouvez modifier les champs en fonction de votre flux de travail ; l’essentiel est que ceux du schéma correspondent aux informations demandées dans l’invite.

{
  "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"]
}

Étapes de mise en œuvre

1. Définissez l’image et l’objectif

Commencez par préciser la question à laquelle l’image doit répondre. L’objectif peut, par exemple, être de répertorier le mobilier visible dans une perspective ; dans un autre cas, il peut s’agir de décrire les caractéristiques visibles des surfaces. N’incluez pas dans l’invite des dimensions, des systèmes constructifs ou des informations produit qui ne figurent pas dans l’image. Si ces informations ne peuvent pas être déterminées avec certitude à partir de l’image, demandez au modèle de le signaler clairement.

2. Rédigez une invite claire et bien délimitée

Le guide de conception des invites de Google recommande de préciser clairement la tâche et ses contraintes, ainsi que le format de réponse souhaité. L’exemple ci-dessous applique cette approche à une image d’intérieur :

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.

L’invite définit la tâche et son périmètre ; le schéma précise les champs dans lesquels la réponse doit être renvoyée. Une simple demande comme « analyse l’image » laisse au modèle le soin de décider quels détails sont importants. Indiquer dès le départ les champs requis et les informations qu’il ne faut pas deviner facilite l’utilisation du résultat dans les notes de projet. Cela dit, le résultat ne remplace ni une mesure vérifiée ni une expertise technique du contenu de l’image.

3. Ajoutez l’image à la requête API

Vous pouvez encoder une petite image en base64 et l’envoyer dans le champ data. Dans la documentation, cette méthode associe les données de l’image à une invite textuelle et à un type MIME. La taille totale de la requête, incluant les données d’image en ligne, l’invite et les instructions système, est limitée à 20 MB. Si cette limite risque d’être dépassée, importez le fichier via la Files API et ajoutez à la requête l’URI renvoyé.

La documentation recommande la Files API pour les fichiers volumineux ou lorsque la même image doit être utilisée dans plusieurs requêtes. Transmettez ensemble les entrées textuelles et visuelles, en indiquant également le type MIME approprié. image/jpeg est l’un des types d’image cités dans la documentation.

4. Configurez le format de réponse JSON

Avec la fonctionnalité structured outputs, définissez le format de réponse sur JSON et ajoutez le schéma à la requête. Dans l’exemple REST de la documentation, la valeur de mime_type est application/json et le schéma est placé dans le champ schema. L’exemple Python génère également un JSON Schema à partir d’un modèle Pydantic, puis valide la réponse avec ce modèle ; l’exemple JavaScript s’appuie sur un schéma Zod.

Évitez de rendre le schéma inutilement complexe pour un flux de travail architectural. Si vous avez uniquement besoin des champs « élément », « emplacement » et « caractéristique visible », ajouter des champs superflus que le flux de travail n’utilise pas augmente la charge de maintenance et de vérification. Faites aussi correspondre les champs obligatoires du schéma aux informations attendues dans l’invite.

5. Vérifiez la réponse et mettez-la en œuvre

Examinez le JSON renvoyé par le modèle pour vérifier que les champs définis sont renseignés et que leur contenu correspond à l’image. Les structured outputs facilitent la production de réponses conformes au schéma ; cela ne signifie pas que l’interprétation de l’image sera toujours exacte. Vérifiez aussi les conclusions concernant les matériaux, les dimensions ou les choix de conception à l’aide des plans, de la documentation du projet ou de l’avis d’un spécialiste.

Utiliser le même schéma pour plusieurs images peut faciliter la comparaison des résultats. Pour chaque requête, précisez l’angle d’analyse de l’image et évaluez les réponses en testant de légères variantes de l’invite pour une même tâche. La conception des invites est un processus itératif : plutôt que de considérer le premier essai comme définitif, repérez les champs erronés ou superflus et clarifiez les consignes.

Erreurs fréquentes

• Demander comme une certitude une information invisible dans l’image : la perspective, la résolution ou le cadrage peuvent rendre certains détails incertains. Demandez au modèle de signaler l’incertitude plutôt que de deviner.

• Ne pas faire correspondre le schéma et l’invite : si l’invite demande un champ absent du schéma, ou si le schéma impose un champ que la tâche n’explique pas, les résultats sont plus difficiles à exploiter. Vérifiez les deux ensemble.

• Envoyer un fichier volumineux sous forme de données en ligne : la taille totale de la requête est limitée à 20 MB pour les données d’image en ligne. Pour les fichiers volumineux, privilégiez la Files API.

• Prendre le format JSON pour une garantie d’exactitude : une réponse structurée ne prouve pas que les informations correspondent avec certitude à l’image. Vérifiez séparément les décisions importantes de conception et les éléments techniques.

• Considérer la première invite comme définitive : même lorsque la tâche et les contraintes sont clairement formulées, il faut examiner les résultats sur des exemples réels et améliorer l’invite.

Incidence sur les flux de travail en architecture et en archviz

Cette méthode peut être utile aux agences d’architecture, aux architectes d’intérieur et aux étudiants qui souhaitent décrire des vues d’intérieur dans une photothèque, créer des listes d’observations structurées à partir de visuels de présentation ou comparer différentes images selon des critères communs. Le format JSON permet de mieux organiser les données lorsqu’il s’agit de réutiliser les mêmes champs dans des tâches d’évaluation et de classification. Toutefois, les résultats ne doivent pas être intégrés directement à une planche de projet ou à une documentation technique comme s’il s’agissait d’informations vérifiées.

Pour assurer la compatibilité, le client et la requête API utilisés doivent prendre en charge les formats de saisie d’images et de structured outputs décrits dans la documentation. Le choix entre l’envoi de l’image en ligne et l’utilisation de la Files API dépend de la taille du fichier et de la fréquence de réutilisation. Les sources de ce guide ne précisant ni les conditions d’accès à l’API ni les coûts, vérifiez séparément les conditions d’accès et de licence à jour avant de passer à un flux de travail réel en agence.

Étapes suivantes

Commencez par tester un petit schéma sur quelques images représentatives. Repérez les champs qui reviennent souvent et qui seront réellement utilisés dans le flux de travail ; signalez séparément les observations incertaines. Examinez ensuite ensemble l’invite, le schéma et la méthode d’envoi des images. Si vous avez besoin de structures JSON plus complexes, consultez les exemples de SDK dans la documentation sur les structured outputs de l’API Gemini, ainsi que le guide Image understanding pour la saisie d’images.

Sources et licence

Cet article a été adapté en turc à partir des guides « Structured outputs », « Image understanding » et « Prompt design strategies » de Google AI for Developers. Les trois sources sont publiées sous licence CC BY 4.0.