# Gemini API ile mimari görselleri JSON çıktısına dönüştürme rehberi

Kaynak: https://3dsinifi.com/haber/gemini-api-ile-mimari-gorselleri-json-ciktisina-donusturme · Kategori: Eğitimler · Yayın: 1 Kasım 2026

> Bu rehberde Gemini API’ye mimari görsel ileterek görseldeki unsurları analiz etmeyi ve yanıtı JSON şemasına göre düzenlemeyi ele alıyoruz. Görsel yükleme, istem hazırlama ve çıktıyı kontrol etme adımları anlatılıyor.

## Kısaca
- Gemini API, görsellerle birlikte metin girdisi alarak görsel açıklama, sınıflandırma ve görsel soru-cevap görevlerinde kullanılabiliyor.
- Görsel, base64 kodlu veriyle veya Files API’ye yüklenip URI üzerinden isteğe eklenebiliyor.
- Structured outputs, yanıtın JSON Schema ile tanımlanan yapıya uymasını sağlayabiliyor.
- Küçük görseller için satır içi veri kullanılabilir; toplam istek boyutu 20 MB’ı aşarsa Files API öneriliyor.

## Bu rehberde ne öğreneceksiniz?

Bir mimari görselden mekân, nesne veya görünür özelliklerle ilgili düzenli notlar çıkarmak; ardından bu notları JSON biçiminde almak mümkün. Bu rehberde Gemini API’ye metin ve görseli birlikte göndermeyi, istemi açık yazmayı ve yanıt yapısını şemayla tarif etmeyi adım adım ele alıyoruz. Örnekler iç mekân görseli üzerinden hazırlanmıştır; görselde bulunmayan ölçü veya malzemeyi tahmin ettirmemek için istemlerde belirsizliği belirtmeye de yer veriyoruz.

Google’ın Gemini API belgelerinde görsel anlama; görsel açıklama, sınıflandırma ve görsel soru-cevap gibi kullanım alanlarıyla anlatılıyor. Görsel girdisi URL, satır içi veri veya Files API üzerinden aktarılabiliyor. Bu örnekte model adı olarak belgelerdeki örneklerde yer alan `gemini-3.8-flash` kullanılıyor.

## Gereksinimler

- Gemini API ile çalışabilecek bir istemci veya REST isteği. Belgeler Python ve JavaScript örneklerinin yanında Java ve Go örnekleri de sunuyor.
- Görseli API’ye iletmek için bir yöntem: küçük görsellerde base64 kodlu satır içi veri, büyük dosyalarda veya tekrar kullanılacak görsellerde Files API.
- JSON çıktısı isteniyorsa, yanıtın hangi alanlardan oluşacağını tanımlayan bir JSON Schema. Google GenAI SDK’larında şema Python için Pydantic, JavaScript için Zod ile tanımlanabiliyor.
- REST kullanılıyorsa istekte API anahtarı. Bu rehberde hesap açma, ücret veya kullanım kotası hakkında kaynaklarda yer almayan bir varsayım yapılmıyor.

Örnek olarak, bir iç mekân görselindeki görünür nesneleri ve konum tariflerini düzenli bir dizi olarak almak istediğimizi düşünelim. Aşağıdaki şema, bu amaçla kullanılabilecek basit bir yapıyı gösterir. Alanları gerçek iş akışına göre değiştirmek mümkündür; önemli olan, istemde beklenen çıktıyla şemadaki alanların birbiriyle örtüşmesidir.

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

## Uygulama adımları

### 1. Görseli ve hedefi belirleyin

Analiz edilecek görselin hangi soruya yanıt vermesi gerektiğini önce netleştirin. Örneğin amaç, bir perspektifte görünen mobilyaları listelemek olabilir; başka bir kullanımda görünür yüzey özellikleri tarif edilebilir. Görselde yer almayan ölçü, yapı sistemi veya ürün bilgilerini isteme dahil etmeyin. Bu tür bilgiler görüntüden kesin olarak çıkarılamıyorsa modelin bunu açıkça söylemesini isteyin.

### 2. İstemi açık ve sınırları belli yazın

Google’ın istem tasarımı rehberi, görev ve kısıtların açıkça belirtilmesini; istenen yanıt biçiminin de tarif edilmesini öneriyor. Aşağıdaki örnek, iç mekân görseli için bu yaklaşımı uygular:

```prompt
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.
```

İstem, görevi ve kapsamı belirler; şema ise yanıtın hangi alanlarda döneceğini tanımlar. Sadece “görseli analiz et” demek, hangi ayrıntıların önemli olduğunu modele bırakır. Gerekli alanları ve tahmin edilmemesi gereken bilgileri baştan yazmak, çıktıyı proje notlarında kullanmayı kolaylaştırır. Yine de sonuç, görselin içeriğine dair doğrulanmış bir ölçüm veya teknik inceleme yerine geçmez.

### 3. Görseli API isteğine ekleyin

Küçük bir görseli base64 kodlayıp `data` alanıyla gönderebilirsiniz. Belgelerde bu yöntem için metin istemiyle birlikte görsel verisi ve MIME türü kullanılıyor. Satır içi görsel verisi, istem metni ve sistem talimatlarıyla beraber toplam istek boyutunu 20 MB ile sınırlar. Bu sınır aşılabilecekse dosyayı Files API’ye yükleyip dönen URI’yi isteğe eklemek gerekir.

Files API, büyük dosyalar veya aynı görseli birden fazla istekte kullanma durumları için belgelerde öneriliyor. İstek içinde metin girdisiyle görsel girdisini birlikte iletin; görselin MIME türünü de uygun biçimde belirtin. Belgelerde örneklenen görsel türlerinden biri `image/jpeg`.

### 4. JSON yanıt biçimini yapılandırın

Structured outputs özelliğinde yanıt biçimini JSON olarak ayarlayıp şemayı isteğe eklersiniz. Belgelerdeki REST örneğinde bunun için `mime_type` değeri `application/json` olarak veriliyor ve şema `schema` alanına konuyor. Python örneği de Pydantic modelinden JSON Schema üretip yanıtı bu modelle doğruluyor; JavaScript örneği Zod şemasından yararlanıyor.

Mimari iş akışında şemayı gereksiz yere büyütmeyin. Örneğin yalnızca unsur, konum ve görünür özellik gerekiyorsa, iş akışının kullanmadığı ek alanları eklemek bakım ve kontrol yükü yaratabilir. Şemadaki zorunlu alanları da istemde beklediğiniz bilgilerle eşleştirin.

### 5. Yanıtı kontrol edin ve kullanıma alın

Modelden gelen JSON’u, belirlenen alanların dolu olup olmadığı ve içeriklerin görselle uyuşup uyuşmadığı açısından inceleyin. Structured outputs biçimsel olarak şemaya uygun yanıtlar üretmeyi kolaylaştırır; bu, görsel yorumunun her durumda doğru olduğu anlamına gelmez. Özellikle malzeme, ölçü veya tasarım kararı gibi sonuçları çizim, proje dokümanı ya da uzman incelemesiyle ayrıca doğrulayın.

Birden fazla görsel için aynı şemayı kullanmak, sonuçları karşılaştırmayı kolaylaştırabilir. Her istekte görselin hangi açıdan inceleneceğini açıkça belirtin ve aynı görev için istemi küçük değişikliklerle deneyerek çıkan yanıtları değerlendirin. İstem tasarımı yinelemeli bir süreçtir; ilk denemeyi nihai kabul etmek yerine, hatalı veya gereksiz alanları gözlemleyip açıklamaları netleştirin.

## Sık yapılan hatalar

- **Görselde görünmeyeni kesin bilgi gibi istemek:** Perspektif, çözünürlük veya kadraj bazı ayrıntıları belirsiz bırakabilir. İstemde modelden tahmin yerine belirsizliği bildirmesini isteyin.
- **Şema ile istemi farklı kurmak:** İstemde istenen alan şemada yoksa ya da şema zorunlu bir alan içerip görev bunu açıklamıyorsa sonuçların kullanımı zorlaşır. İkisini birlikte gözden geçirin.
- **Büyük dosyayı satır içi veriyle göndermek:** Satır içi görsel verisi için toplam istek boyutu 20 MB sınırı geçerlidir. Büyük dosyalarda Files API yolunu tercih edin.
- **JSON biçimini doğruluk garantisi sanmak:** Yapılandırılmış yanıt, bilgilerin görselle kesin olarak örtüştüğünü kanıtlamaz. Önemli tasarım ve teknik kararları ayrıca kontrol edin.
- **İlk istemi son sürüm kabul etmek:** Görev ve kısıtlar ne kadar açık olursa olsun, gerçek örneklerde çıktıyı gözden geçirip istemi iyileştirmek gerekir.

## Mimarlık ve archviz iş akışına etkisi

Bu yöntem, görsel arşivindeki iç mekân karelerini açıklamak, sunum görsellerinden düzenli gözlem listeleri oluşturmak veya farklı görselleri ortak alanlarla karşılaştırmak isteyen mimarlık ofisleri, iç mimarlar ve öğrenciler için yararlı olabilir. JSON biçimi, aynı alanların tekrar tekrar kullanılacağı değerlendirme ve sınıflandırma işlerinde veriyi daha düzenli tutar. Ancak sonuçları proje paftasına veya teknik dokümana doğrudan doğrulanmış bilgi olarak aktarmamak gerekir.

Uyumluluk açısından çalışılan istemci ve API isteğinin belgelerdeki görsel girdisi ve structured output biçimlerini desteklemesi gerekir. Görseli satır içi göndermek ile Files API üzerinden kullanmak arasında dosya boyutu ve tekrar kullanımına göre seçim yapılmalıdır. API erişimi ve maliyet koşulları bu rehberin kaynaklarında belirtilmediğinden, gerçek bir ofis iş akışına geçmeden önce güncel erişim ve lisans koşulları ayrıca kontrol edilmelidir.

## Sonraki adımlar

Önce birkaç temsilî görsel üzerinde küçük bir şema deneyin. Yanıtlarda sık tekrarlanan ve iş akışında gerçekten kullanılacak alanları belirleyin; belirsiz kalan gözlemleri ayrıca işaretleyin. Ardından istemi, şemayı ve görsel gönderim yöntemini birlikte gözden geçirin. Daha kapsamlı JSON yapıları gerektiğinde Gemini API’nin structured output belgelerindeki SDK örnekleri, görsel girdisi için de Image understanding rehberi incelenebilir.

## Kaynak ve lisans

Bu içerik, Google AI for Developers’ın “Structured outputs”, “Image understanding” ve “Prompt design strategies” rehberlerinden yararlanılarak Türkçeye uyarlanmıştır. Üç kaynak da CC BY 4.0 lisansıyla sunulmuştur.

## Pro ipucu
Görselde doğrulanamayan ölçü, marka veya malzeme için tahmin istemek yerine, istemde belirsizliğin açıkça belirtilmesini talep edin.

## 3dsınıfı yorumu
Mimarlık ofisleri ve öğrenciler için bu yaklaşımın en somut faydası, görsel gözlemlerini tekrar kullanılabilir alanlara ayırması. Özellikle arşiv düzenleme ve görselleri ortak ölçütlerle inceleme işlerinde JSON yapısı pratik olabilir; ancak çıktı, teknik doğrulamanın yerini tutmaz.

Türkiye’deki ekipler uygulamaya geçmeden önce API erişimi, kullanım maliyeti ve kendi yazılım akışlarıyla uyumluluk konularını ayrıca netleştirmeli. Kaynaklar fiyat veya lisans koşullarını açıklamıyor. Bu nedenle önce sınırlı bir deneme yapmak, görsel aktarım yöntemini dosya boyutuna göre seçmek ve sonuçları insan kontrolünden geçirmek daha sağlıklı bir başlangıç olur.

## Kaynaklar
- [ai.google.dev (CC BY 4.0)](https://ai.google.dev/gemini-api/docs/structured-output) (özet)
- [ai.google.dev (CC BY 4.0)](https://ai.google.dev/gemini-api/docs/image-understanding) (özet)
- [ai.google.dev (CC BY 4.0)](https://ai.google.dev/gemini-api/docs/prompting-strategies) (özet)

_Yapay zekâ ile yazıldı, kaynaklarla doğrulandı. © 3dsınıfı_