Architekturbilder mit der Gemini API in JSON umwandeln: Anleitung

Was lernen Sie in diesem Leitfaden?

Aus einem Architekturbild lassen sich strukturierte Notizen zu Räumen, Objekten oder sichtbaren Merkmalen erstellen und anschließend im JSON-Format ausgeben. In diesem Leitfaden zeigen wir Schritt für Schritt, wie Sie Text und Bild gemeinsam an die Gemini API senden, den Prompt klar formulieren und die Antwortstruktur mit einem Schema festlegen. Die Beispiele basieren auf einer Innenraumansicht. Außerdem zeigen wir, wie Sie in Prompts auf Unsicherheiten hinweisen, damit keine Maße oder Materialien geschätzt werden, die im Bild nicht zu erkennen sind.

In der Dokumentation zur Gemini API von Google wird Bildverständnis unter anderem für Bildbeschreibungen, Klassifizierung und visuelle Frage-Antwort-Aufgaben beschrieben. Bilder können per URL, als Inline-Daten oder über die Files API übermittelt werden. In diesem Beispiel verwenden wir gemini-3.8-flash, einen Modellnamen aus den Beispielen in der Dokumentation.

Voraussetzungen

• Ein Client oder eine REST-Anfrage, mit dem bzw. der sich die Gemini API verwenden lässt. Die Dokumentation enthält neben Beispielen für Python und JavaScript auch Beispiele für Java und Go.

• Eine Methode, um das Bild an die API zu übermitteln: Base64-codierte Inline-Daten für kleine Bilder, die Files API für größere Dateien oder Bilder, die wiederverwendet werden sollen.

• Wenn eine JSON-Ausgabe gewünscht ist, ein JSON Schema, das die Felder der Antwort festlegt. In den Google-GenAI-SDKs lassen sich Schemas mit Pydantic für Python und Zod für JavaScript definieren.

• Bei Verwendung von REST ein API-Schlüssel in der Anfrage. Dieser Leitfaden trifft keine Annahmen zu Kontoerstellung, Gebühren oder Nutzungskontingenten, die in den Quellen nicht genannt werden.

Nehmen wir als Beispiel an, dass wir sichtbare Objekte und ihre Positionen in einem Innenraumbild als strukturierte Liste erfassen möchten. Das folgende Schema zeigt eine einfache Struktur, die sich dafür verwenden lässt. Die Felder können an den jeweiligen Workflow angepasst werden. Wichtig ist, dass die erwartete Ausgabe im Prompt mit den Schemafeldern übereinstimmt.

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

Schritte zur Umsetzung

1. Bild und Ziel festlegen

Legen Sie zuerst fest, welche Frage das zu analysierende Bild beantworten soll. Das Ziel kann beispielsweise sein, die in einer Perspektive sichtbaren Möbel aufzulisten. In einem anderen Anwendungsfall lassen sich sichtbare Oberflächenmerkmale beschreiben. Angaben zu Maßen, Konstruktionssystemen oder Produkten, die im Bild nicht zu sehen sind, sollten Sie nicht in den Prompt aufnehmen. Falls sich solche Informationen nicht zuverlässig aus dem Bild ableiten lassen, bitten Sie das Modell, dies ausdrücklich mitzuteilen.

2. Den Prompt klar und eindeutig formulieren

Der Prompt-Design-Leitfaden von Google empfiehlt, Aufgabe und Einschränkungen klar zu benennen und auch das gewünschte Antwortformat zu beschreiben. Das folgende Beispiel setzt diesen Ansatz für ein Innenraumbild um:

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.

Der Prompt legt Aufgabe und Umfang fest; das Schema definiert, in welchen Feldern die Antwort zurückgegeben wird. Eine bloße Aufforderung wie „Analysiere das Bild“ überlässt dem Modell die Entscheidung, welche Details wichtig sind. Wenn Sie die erforderlichen Felder und Angaben, die nicht geschätzt werden sollen, von Anfang an festlegen, lassen sich die Ergebnisse leichter in Projektnotizen weiterverwenden. Die Ausgabe ersetzt jedoch weder eine verifizierte Messung noch eine fachliche Prüfung des Bildinhalts.

3. Das Bild in die API-Anfrage einbinden

Ein kleines Bild können Sie Base64-codieren und mit dem Feld data senden. In der Dokumentation wird dafür zusammen mit dem Textprompt auch die Bilddaten und der MIME-Typ verwendet. Bei Inline-Bilddaten ist die Gesamtgröße der Anfrage einschließlich Prompttext und Systemanweisungen auf 20 MB begrenzt. Wenn diese Grenze überschritten werden könnte, müssen Sie die Datei über die Files API hochladen und die zurückgegebene URI in die Anfrage einbinden.

Laut Dokumentation eignet sich die Files API für große Dateien oder wenn dasselbe Bild in mehreren Anfragen verwendet wird. Übermitteln Sie Texteingabe und Bildeingabe gemeinsam in der Anfrage und geben Sie den passenden MIME-Typ für das Bild an. Einer der in der Dokumentation gezeigten Bildtypen ist image/jpeg.

4. Das JSON-Antwortformat konfigurieren

Bei der Structured-Outputs-Funktion legen Sie das Antwortformat als JSON fest und fügen das Schema zur Anfrage hinzu. Im REST-Beispiel der Dokumentation wird dafür mime_type auf application/json gesetzt und das Schema im Feld schema übergeben. Das Python-Beispiel erzeugt außerdem ein JSON Schema aus einem Pydantic-Modell und validiert die Antwort anhand dieses Modells; das JavaScript-Beispiel verwendet ein Zod-Schema.

Halten Sie das Schema in einem Architektur-Workflow möglichst schlank. Wenn Sie beispielsweise nur Element, Position und sichtbares Merkmal benötigen, können zusätzliche Felder, die im Workflow nicht genutzt werden, den Wartungs- und Prüfaufwand erhöhen. Stimmen Sie auch die Pflichtfelder im Schema auf die im Prompt erwarteten Informationen ab.

5. Die Antwort prüfen und verwenden

Prüfen Sie das vom Modell zurückgegebene JSON darauf, ob die festgelegten Felder ausgefüllt sind und die Inhalte mit dem Bild übereinstimmen. Structured outputs erleichtern Antworten, die formal dem Schema entsprechen. Das bedeutet jedoch nicht, dass die Bildinterpretation in jedem Fall korrekt ist. Prüfen Sie insbesondere Ergebnisse zu Materialien, Maßen oder Entwurfsentscheidungen zusätzlich anhand von Zeichnungen, Projektdokumentation oder einer fachlichen Beurteilung.

Bei mehreren Bildern kann ein einheitliches Schema den Vergleich der Ergebnisse erleichtern. Geben Sie in jeder Anfrage klar an, unter welchem Blickwinkel das Bild analysiert werden soll, und bewerten Sie die Antworten, indem Sie den Prompt für dieselbe Aufgabe mit kleinen Änderungen testen. Prompt-Design ist ein iterativer Prozess: Betrachten Sie den ersten Versuch nicht als endgültig, sondern prüfen Sie, welche Angaben fehlerhaft oder unnötig sind, und präzisieren Sie die Anweisungen.

Häufige Fehler

• Informationen verlangen, die im Bild nicht zu sehen sind: Perspektive, Auflösung oder Bildausschnitt können Details unklar lassen. Bitten Sie das Modell im Prompt, Unsicherheiten zu benennen, statt zu raten.

• Schema und Prompt unterschiedlich formulieren: Wenn ein im Prompt gefordertes Feld im Schema fehlt oder das Schema ein Pflichtfeld enthält, das in der Aufgabe nicht erklärt wird, wird die Nutzung der Ergebnisse schwieriger. Prüfen Sie beides gemeinsam.

• Große Dateien als Inline-Daten senden: Für Inline-Bilddaten gilt eine Gesamtgrenze von 20 MB pro Anfrage. Verwenden Sie bei großen Dateien die Files API.

• Das JSON-Format als Genauigkeitsgarantie verstehen: Eine strukturierte Antwort beweist nicht, dass die Angaben genau mit dem Bild übereinstimmen. Prüfen Sie wichtige Entwurfs- und technische Entscheidungen zusätzlich.

• Den ersten Prompt als endgültige Version betrachten: Auch wenn Aufgabe und Einschränkungen klar formuliert sind, müssen Sie die Ausgabe anhand realer Beispiele prüfen und den Prompt verbessern.

Auswirkungen auf Architektur- und Archviz-Workflows

Diese Methode kann für Architekturbüros, Innenarchitektinnen und Innenarchitekten sowie Studierende hilfreich sein, die Innenraumansichten in Bildarchiven beschreiben, strukturierte Beobachtungslisten aus Präsentationsbildern erstellen oder verschiedene Bilder anhand einheitlicher Felder vergleichen möchten. Das JSON-Format sorgt bei Auswertungs- und Klassifizierungsaufgaben, in denen dieselben Felder wiederholt verwendet werden, für eine übersichtlichere Datenstruktur. Die Ergebnisse sollten jedoch nicht ungeprüft als verifizierte Informationen in Projektpläne oder technische Dokumentationen übernommen werden.

Für die Kompatibilität müssen der verwendete Client und die API-Anfrage die in der Dokumentation beschriebenen Bildinputs und Structured-Output-Formate unterstützen. Ob Sie ein Bild als Inline-Daten senden oder über die Files API verwenden, sollten Sie anhand der Dateigröße und der Wiederverwendung entscheiden. Da die Quellen dieses Leitfadens keine Angaben zu API-Zugang und Kosten enthalten, sollten Sie die aktuellen Zugangs- und Lizenzbedingungen prüfen, bevor Sie den Workflow im Büro einsetzen.

Nächste Schritte

Testen Sie zunächst ein kleines Schema mit einigen repräsentativen Bildern. Ermitteln Sie, welche Felder in den Antworten häufig vorkommen und tatsächlich im Workflow verwendet werden, und kennzeichnen Sie unklare Beobachtungen gesondert. Überprüfen Sie anschließend Prompt, Schema und Übermittlungsmethode gemeinsam. Für umfangreichere JSON-Strukturen können Sie die SDK-Beispiele in der Dokumentation zu Structured Outputs der Gemini API heranziehen; für Bildeingaben eignet sich außerdem der Leitfaden Image understanding.

Quellen und Lizenz

Dieser Beitrag wurde auf Grundlage der Leitfäden „Structured outputs“, „Image understanding“ und „Prompt design strategies“ von Google AI for Developers ins Türkische übertragen und angepasst. Alle drei Quellen stehen unter der Lizenz CC BY 4.0.