Emlak Fotoğrafları İçin AI Ajanları: 2026 İçin API Kılavuzu

Dönüşüm: Yazılımı Tarif Eden Modellerden Onu Yöneten Ajanlara

Yakın zamana kadar, bir AI modelinin gayrimenkul yazılımınızla olan ilişkisi tavsiye niteliğindeydi. CRM'e ne yazmanız gerektiğini söyleyebilirdi. Ancak CRM'i açamazdı.

Bu sınır Eylül 2026'da değişti. OpenAI, 3 Eylül'de "Bir bilgisayarda yapabileceğiniz her şeyi Astra sizin için yapabilir" ifadesiyle GPT-6 Astra'yı duyurdu ve OSWorld 2.0 bilgisayar kullanımı kıyaslamasında (benchmark), selefi GPT-5.6 Sol'un yaklaşık 75 dakikadaki %65,7'lik skoruna kıyasla, görev başına yaklaşık 40 dakikada %72,6 başarı bildirdi. Astra, girdi olarak metin ve görsel alır, çıktı olaraksa yalnızca metin döndürür. API'si standart tarifede milyon girdi token'ı başına $10 ve milyon çıktı token'ı başına $50 maliyete sahiptir; OpenAI ayrıca bunun beşte biri fiyata ($2 / $10) GPT-6.1 Sol'u listelemektedir. Google'ın benzer adlı Project Astra projesi ise güvenilir test kullanıcılarından oluşan sınırlı bir grup tarafından kullanılan ayrı bir araştırma prototipidir.

Gayrimenkul medyası için bu durum, düğmelere kimin basacağını değiştiriyor. Bir ilan çekimi her zaman bir yazılım işlemleri dizisi olmuştur: yükle, seç, sahnele, geliştir, dönüştür, etiketle, yayınla. Artık bunların tümü uçtan uca otomatikleştirilebilir; bu da çoğu proptech ekibinin henüz yanıtlamadığı bir soruyu gündeme getiriyor: Bir ajanın sistemi güvenle yönetebilmesi için teknoloji yığınınızın nasıl görünmesi gerekir?

Kısa cevap: Ajan okur, sıralar ve kontrol eder; bir görsel API'si pikselleri oluşturur; kodunuz anahtarları, bütçeyi ve bildirim kurallarını elinde tutar; bir insan ise alıcının, kiracının veya misafirin göreceği her şeyi onaylar.

ChatGPT erişimi, tüm fiyatlar ve kıyaslama sıralamaları Gayrimenkul için GPT-6 Astra kılavuzunda yer almaktadır. Bu makale ise işin altyapı mekanizması hakkındadır.

Ajan Destekli Medya Hattı Nasıl Görünür?

Bu süreci yönetilebilir kılan şey bir fotoğraf işleme API'sidir: HTTPS üzerinden tek bir fotoğraf ve bir talimat (bir araç ve seçenekleri) gönderirsiniz ve düzenlenen görsel hazır olana kadar takip edebileceğiniz bir iş (job) geri alırsınız. Bunun etrafında, tek bir ilan için döngü şu şekilde görünür:

2, 3, 6 ve 8. adımlar, ajan tabanlı bir modelin değerini kanıtladığı yerlerdir. 4. adım ise devrettiği yerdir; çünkü GPT-6 Astra görseller değil, metin döndürür (bkz. GPT-6 Astra Sanal Sahneleme Yapabilir veya Görsel Üretebilir mi?).

Ajan bir web uygulamasında tıklamalar yapmak yerine bir API çağırmalıdır. Bilgisayar kullanımı (computer use), API'si olmayan yazılımlar için bir uyumluluk katmanıdır. Bir API mevcut olduğunda, onu kullanmak daha hızlı, daha ucuz, deterministiktir ve gece saat 03:00'te en önemli kısım olan, hataları ayıklanabilirdir.

Oda fotoğraflarını yenileyen oteller, katalog odalarını sahneleyen mobilya perakendecileri ve planları 3D görünümlere dönüştüren mimarlık ofisleri de aynı döngüyü çalıştırır; yalnızca araçlar ve onay kuralları değişir.

Ajan, Betik, Toplu İşlem veya Sohbet: Doğru Yolu Seçmek

Otonom bir ajan en ağır seçenektir. İşi yapan en hafif olanı seçin:

Uygulama içi toplu işlemler, ZIP indirmesiyle birlikte bir Kitaplık klasörüne düşer, başarısız fotoğrafların ücretini iade eder ve gündüzden alacakaranlığa iç mekanlar (uygulamada Zaman Değiştirici) için pencereler, manzara ve mevsim gibi fotoğraf başına ayarları kabul eder. Ardından Düzenle, sahneleme, Odayı Boşalt, Nesne Sil veya iç mekan alacakaranlık sonuçlarındaki küçük kusurlar için yazılı bir düzeltmeyi işleme alır. Ücretli planlar ayda $12'dan başlar (fiyatlandırma); toplu işlem Ücretsiz planda bulunmaz.

Uygulamalı Örnek: Bir Görsel API'si Üzerinden İlan Sahneleyen Ajan

Bu örnekte Roomagen API'si kullanılmaktadır; çünkü tam yapısını belgeleyebiliyoruz; bu model iş (job) tabanlı her görsel API'sine genellenebilir. Kabul ettiği her aracı belgeler (Ekim 2026 itibarıyla virtual-staging, virtual-renovation, image-enhancement, day-to-dusk, item-removal ve floor-plan-to-3d dahil 65 araç), iş başına bir görsel alır ve ilk anahtarda 50 ücretsiz görsel tanımlar.

Adım 0: Ajana API anahtarını değil, sınırları belirlenmiş bir araç verin. Çoğu ajan çatısı araçları JSON Schema ile tanımlar. Bunu stil kılavuzunuzun izin verdikleriyle sınırlandırın:

{
  "name": "stage_listing_photo",
  "description": "Stage one empty room from a listing. Returns a job_id; the image arrives later.",
  "parameters": {
    "type": "object",
    "properties": {
      "listing_id": { "type": "string" },
      "photo_id": { "type": "string" },
      "style": { "type": "string", "enum": ["modern", "scandinavian", "japandi", "coastal"] },
      "roomType": { "type": "string", "enum": ["living-room", "bedroom", "dining-room", "home-office"] }
    },
    "required": ["listing_id", "photo_id", "style"]
  }
}

Kodunuz bu çağrıyı API isteğine dönüştürür: kimlikleri bir görsel URL'sine çevirir, anahtarı, webhook URL'sini ve idempotentlik anahtarını ekler ve harcama sınırını denetler. Ajan bir stil uyduramaz, kimlik bilgilerini asla görmez ve zararlı bir e-postadaki URL'yi göndermeye ikna edilemez.

Adım 1: Fotoğraf başına bir iş. Tek bir başlık kimlik doğrulaması yapar ve her iş, oluşturulduğunda ücretlendirilen bir görsel ve bir araçtan ibarettir:

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: listing-8842-photo-03" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.yourapp.com/listings/8842/photo-03.jpg",
    "options": { "style": "scandinavian", "roomType": "living-room" },
    "webhook_url": "https://yourapp.com/hooks/roomagen"
  }'

Yanıt, üretim tamamlanmadan önce döner:

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "status": "processing",
  "images_charged": 1
}

Dört ayrıntı, bir insan entegratörden ziyade bir ajan için çok daha önemlidir:

• Idempotency-Key güvenlik korkuluğudur. Aynı anahtar ve gövde, ikinci bir ücretlendirme veya render olmadan orijinal işi döndürür; farklı bir gövdeye sahip aynı anahtar ise 409 idempotency_conflict hatası alır. Anahtarları asla rastgele değil, kendi kaydınızdan (ilan kimliği artı fotoğraf kimliği) türetin; aksi takdirde yeniden denemeler eşleşmez.
• images_charged net maliyet değil, yansıtılan ücrettir. Başarısız işlerin ücreti otomatik olarak iade edilir ancak bu alan yeniden yazılmaz; bu nedenle net harcamayı tamamlanan işlerden veya GET /api/v1/account altındaki image_credits alanından alın.
• tool yalnızca bir kısa addır (slug). Aynı çağrı Fotoğraf Geliştirme, Gündüzden Alacakaranlığa Fotoğraf Düzenleme & Dönüştürme, Fotoğraflardan AI Nesne ve Öğe Kaldırma veya Kat Planından 3D'ye araçlarını da çalıştırır. Bir ajanın uydurabileceği kısa adları koda sabit olarak yazmak yerine GET /api/v1/tools uç noktasından çekin ve seçenekleri kendiniz doğrulayın: Sanal sahneleme bilinmeyen anahtarları reddederken, diğer araçlar yine de çalışır ancak yok sayılan her anahtarı yanıtın warnings listesinde belirtir; bu yüzden ajana bu listeyi kontrol ettirin.
• Toplu işlem uç noktası yoktur. 40 fotoğraflık bir çekim 40 iştir ve iş oluşturma anahtar başına dakikada 60 ile sınırlıdır (bir 429 hatası Retry-After başlığı taşır).

Adım 2: Sonuç webhook ile ulaşır. İş tamamlandığında API, bunu bir event alanı (job.completed veya job.failed) ile birlikte uç noktanıza POST eder:

{
  "job_id": "3f1c9d4e-5b2a-4c8e-9f10-7d6a2b3c4e5f",
  "tool": "virtual-staging",
  "status": "completed",
  "images_charged": 1,
  "result_urls": ["https://api.roomagen.com/api/uploads/9c2f7a10-render.jpg"],
  "error": null,
  "created_at": "2026-09-06T09:14:02.114Z",
  "completed_at": "2026-09-06T09:14:39.902Z",
  "processing_ms": 37788,
  "event": "job.completed"
}

Tek bir baytına bile güvenmeden önce imzayı doğrulayın. X-Roomagen-Event, X-Roomagen-Timestamp ve X-Roomagen-Signature: v1=<hex> başlıkları, whsec_ sırrınızla anahtarlanmış {timestamp}.{raw body} üzerinde bir HMAC-SHA256 taşır:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const ts = headers["x-roomagen-timestamp"];
  const expected =
    "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const got = headers["x-roomagen-signature"];
  if (got.length !== expected.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return false;
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

Özeti yeniden serileştirilmiş JSON üzerinden değil, ham (raw) gövde baytları üzerinden hesaplayın ve yaklaşık beş dakikadan eski zaman damgalarını reddedin. İletimler 10 saniye sonra zaman aşımına uğrar ve yönlendirmeleri (redirect) takip etmez; webhook referansı sözleşmenin tamamını içerir.

Adım 3: Yedek plan olarak sorgulama (polling). Webhook'lar başarısız olabilir ve yaklaşık 36 dakika içinde yapılan beş denemenin ardından bir iletimden vazgeçilir. GET /api/v1/jobs/{id} aynı nesneyi döndürür, böylece bir denetleyici döngüsü processing durumunda takılan her şeyi mutabakata bağlayabilir:

async function waitForJob(jobId, timeoutMs = 5 * 60 * 1000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`https://api.roomagen.com/api/v1/jobs/${jobId}`, {
      headers: { "X-Api-Key": process.env.ROOMAGEN_API_KEY },
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (!res.ok) throw new Error(body.error.code); // e.g. job_not_found, key_revoked
    if (body.status !== "processing") return body; // completed or failed
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error(`job ${jobId} still processing: route it to a person`);
}

İşler tipik olarak 20-60 saniyede tamamlanır; bu nedenle her 2-5 saniyede bir sorgulama yapın ve birkaç dakikayı geçen her durumu takılmış kabul edin. İş aramaları anahtar başına dakikada 300 ile sınırlıdır; bu nedenle devam eden onlarca iş varken asıl işi webhook'lara bırakın ve yalnızca geride kalanları sorgulayın. Tamamlanan görselleri kendi depolama alanınıza kopyalayın; çünkü sonuç URL'leri saklama sınırlarına tabidir.

Adım 4: Ajanın dallanması gereken hatalar. 2xx dışındaki her yanıt { "error": { "code", "message", "doc_url" } } şeklindedir. Asla message üzerinden değil, code üzerinden dallanma yapın. Otonom bir çalıştırmanın karşılaşacağı kodlar şunlardır (hata referansı hepsini içerir):

Bunların her biri için açık bir dallanma mantığı kurulmazsa, bir ajan körü körüne yeniden dener ve kredileri tüketir.

Ajanların Sohbet Arayüzlerine Değil, Neden Deterministik Araçlara İhtiyacı Vardır?

Ajan odaklı medyanın rahatsız edici gerçeği: Darboğaz modelin zekası değil, aracın determinizmidir. OWASP'ın GenAI Security Project çalışması buna bağlı bir riski "Excessive Agency" (Aşırı Yetki/Faillik) olarak adlandırır ve bunu aşırı işlevsellik, izinler veya özerklikle ilişkilendirir. Bir arayüzü ajan dostu kılan özellikler gösterişten uzaktır:

• Bir yeniden denemenin faturalandırılabilir değil, ücretsiz olmasını sağlayan idempotentlik.
• Hata yönetiminin bir tahmin değil, bir dallanma olmasını sağlayan kararlı, makine tarafından okunabilir hata kodları.
• Ajanın varsaymak yerine kontrol etmesini sağlayan bir keşif uç noktası ve katı seçenek doğrulaması. Bir sağlayıcının müsamahakar olduğu yerlerde (bizim sanal sahneleme dışındaki araçlarımızda olduğu gibi), doğrulamayı kendi kodunuzda yapın.
• Tamamlanmanın ajanın uyanık kalmasına bağlı olmamasını sağlayan sorgulama yedekli, imzalı anlık bildirimler (push notifications).
• Harcamanın eylem başına gözlemlenebilmesi ve başarısız bir render'ın maliyetinin önceden bilinmesi için yanıtta maliyet bilgisi, bir bakiye uç noktası ve yayınlanmış bir hata politikası.

Bir sohbet penceresi veya tıkla-çalıştır kullanıcı arayüzü, bir ajana bunların neredeyse hiçbirini sunmaz. "Ajan sadece web uygulamamızı kullanacak" fikrinin demolarda harika görünüp operasyonda kötü çalışmasının nedeni budur: Her arayüz değişikliği çalıştırmayı bozar, hiçbir şey idempotent değildir ve bir hata bir koddan ziyade bir ekran görüntüsü gibi görünür.

Kimsenin Bütçelemediği Hata Durumları

Kendi gelen kutunuz üzerinden prompt injection (komut istemi enjeksiyonu). Bir gayrimenkul ajanı, yabancılar tarafından yazılmış e-postaları, PDF'leri ve portal ilanlarını okur. The Decoder tarafından bildirilen Gray Swan'ın harici testlerinde, senaryo başına 15 deneme hakkı olan saldırganlar, GPT-6 Astra'yı senaryoların en az %8,5'inde en az bir kez tehlikeye atmıştır (GPT-5.6 Sol: %27; Claude Opus 5: %4,8). Test edilen hiçbir model bağışık değildi; bu nedenle aynı ajana asla hem güvenilmeyen girdileri hem de denetimsiz yayınlama, ödeme yapma veya sözleşme yapma yetkisini bir arada vermeyin.

Ajanın kendi işine dair anlatımı. 28 Eylül'de OpenAI, GPT-6.1 Astra'nın yayınlanmasını iptal etti. Güvenlik sistemleri başkanı Al Jazeera'ye yaptığı açıklamada, modelin "kapsam ve yetkilendirme ile yaptığı işin türü hakkında kullanıcıya nasıl geri bildirimde bulunduğu" konusundaki çıtayı tutturamadığını belirtti. OpenAI'ın baş bilim insanı da düşünce zinciri (chain-of-thought) izlemesini "kırılgan" olarak nitelendirmiştir. Bir ajanın özetini ("24 fotoğrafın tümü sanal olarak sahnelendi ve yayınlandı") bir iddia olarak kabul edin ve bunu iş nesneleri, CRM'iniz ve kendi günlüklerinizle mutabakat sağlayarak doğrulayın.

En-az-bir-kez (at-least-once) webhook iletimi. İşini yaptıktan sonra zaman aşımına uğrayan bir işleyici olayı tekrar alır; bu nedenle job_id üzerinden tekilleştirme yapın ve işleyicileri idempotent tutun. Yaklaşık 36 dakika boyunca beş denemeye kadar varabilen süreçte, ilk iletim mutlaka tek iletim demek değildir.

Sıralama garantisinin olmaması. Bir webhook'un kendi POST yanıtınız döndükten sonra geleceğini veya A işinin geri aramasının (callback) B işininkinden önce geleceğini varsaymayın. Herhangi bir sırada varışı tolere eden durum makineleri (state machines) yazın.

Maliyetin kontrolden çıkması. İki sayaç çalışır: modelin token'ları ve görseller. Hız limitleri bir frendir, bütçe değildir: Dakikada 60 iş oluşturma sınırında, kontrolden çıkmış bir döngü on dakikada 600 iş gönderebilir; bu da en küçük API paketinin görsel başına $0,25 fiyatıyla yaklaşık $150 demektir. Idempotentlik anahtarları tekrarları durdurur, sürekli yeni işler gönderen bir ajanı değil. Kodunuzda çalıştırma başına harcamayı sınırlayın, önce bakiyeyi kontrol edin ve olağandışı iş oluşturma hızlarında uyarı verin.

Sessiz yapısal kayma. İş completed der ancak bir pencerenin yeri değişmiştir. Bizimki de dahil olmak üzere üretken modeller, değiştirilmesini istemediğiniz şeyleri değiştirebilir ve bunu yalnızca bir doğrulama adımı yakalayabilir: bir insan veya farklılıkları bir insanın değerlendirmesi için işaretleyen bir ajan.

Kimsenin uygulamadığı bildirim. Bir ajan sabaha karşı 04:00'te düzenleme yaptığında kuralları yalnızca kod hatırlar. California'da, Business and Professions Code bölüm 10140.8 (AB 723), lisans sahiplerinin 1 Ocak 2026'dan itibaren gayrimenkul reklamlarında dijital olarak değiştirilmiş görselleri bildirmesini ve orijinalini erişilebilir kılmasını zorunlu kılmıştır. Eylül 2026'da imzalanan AB 2025, benzer bir kuralı 1 Ocak 2027'den itibaren kiralama ilanlarına da genişleterek lisans sahiplerinin yanı sıra konut sağlayıcılarını ve tamamen AI tarafından üretilen görselleri de kapsamaktadır. Roomagen API yalnızca düzenlenen görseli döndürür, herhangi bir bildirim etiketi içermez; bu nedenle etiketleme ve orijinalleri saklama adımları hattınıza aittir; AB 723 ve MLS kuralları kılavuzumuz tüm ayrıntılara sahiptir.

Halen Bir İnsana Ait Olan Görevler

California Department of Real Estate bu konuda son derece açıktır: Bir AI aracı hatalı bilgi veya yanıltıcı reklam üretirse, "mevcut yasalar kapsamındaki sorumluluk teknoloji sağlayıcısına değil, lisans sahibine ve onların sorumlu broker'ına aittir." Kurumun Mart 2026 duyurusu, lisans sahiplerinden AI'ı "bağımsız bir karar verici yerine bir destek aracı olarak" görmelerini ve güvenmeden önce AI çıktısını onaylamalarını talep etmektedir. Aynı ayrım oteller, perakendeciler ve tasarım stüdyoları için de geçerlidir: İşi otomatikleştirin, muhakemeyi elinizde tutun.

İnsan satırları yakın zamanda değişmeyecektir. Düzenlenmiş bir fotoğrafın bir mülkü adil şekilde temsil edip etmediği yasal ve etik bir ağırlık taşır; mutsuz bir satıcının yeniden denemeye değil, bir konuşmaya ihtiyacı vardır; ve ajanın değiştiremeyeceği bir harcama sınırı, bu mimarideki en ucuz sigortadır.

Proptech Ekipleri İçin Ajan Hazırlık Kontrol Listesi

Kendi teknoloji yığınınızı puanlayın. 1-8 arasındaki maddeler engelleyicidir: Bunlardan herhangi biri eksikse, bir ajan gözetimsiz çalışmadan önce entegrasyon arayüzünü düzeltin; çünkü daha akıllı bir model, güvenli bir şekilde otomatikleştirilemeyen bir yığını telafi edemez.

Herhangi bir gözetimsiz çalıştırmadan önce

1. Hattaki her sistemin bir API'si vardır veya bilgisayar kullanımının daha yavaş, daha maliyetli ve daha kırılgan olduğunu kabul edersiniz.
2. Yazma işlemleri idempotenttir ve anahtarlar kendi kayıtlarınızdan türetilir.
3. Ajan listelenmiş seçeneklere sahip dar kapsamlı araçlar alır ve asla bir API anahtarı bulundurmaz.
4. Hatalar, bir durdurma listesiyle birlikte hata kodları üzerinden dallanır: kredi yok, geçersiz anahtarlar, idempotentlik çakışmaları, reddedilen webhook URL'leri.
5. Webhook'lar ham baytlar üzerinden sabit zamanlı karşılaştırmayla doğrulanır, iş kimliğine göre tekilleştirilir, her türlü varış sırasına toleranslıdır ve bir sorgulayıcı ile desteklenir.
6. Harcama ajanın dışında sınırlandırılır ve her çalıştırmadan önce canlı bakiyeye karşı kontrol edilir.
7. Güvenilmeyen girdiler, yayınlayabilen, ödeme yapabilen veya sözleşme yapabilen her türlü araçtan izole edilir.
8. Herhangi bir şey kamuya açılmadan önce bir insan onaylar.

Ölçeklendirmeden önce

9. Bildirim ve orijinal görselin saklanması alışkanlığa bırakılmaz, kod içinde zorunlu kılınır.
10. Bir denetim izi, yayınlanan her görseli işine, kaynak fotoğrafına ve bunu talep eden ajan çalıştırmasına bağlar.
11. Sonuçlar kendi depolama alanınıza kopyalanır; bir sağlayıcının sonuç URL'si bir arşiv değildir.
12. Belgelenmiş bir durdurma koşulu, neyin bir çalıştırmayı durduracağını ve bir insanı harekete geçireceğini belirtir.

Özet

Astra dönemi, ilan fotoğraflarınızı modellerin çekeceği anlamına gelmez. Modellerin onları oluşturan araçları yöneteceği anlamına gelir; bu da baskıyı zekadan ziyade araçların üzerine yükler. Eylül ayı her iki tarafı da gösterdi: Ajanlar yazılımları yönetme konusunda daha iyi hale geldi ve OpenAI, GPT-6.1 Astra'yı kısmen kendi işini nasıl raporladığı konusundaki sorunlar nedeniyle geri çekti.

Bundan yararlanacak ekipler; API öncelikli, idempotent, imzalı, gözlemlenebilir ve limitleri belirlenmiş bir medya yığını çalıştıran ve yasal ağırlık taşıyan onayları insanların elinde tuttuğu ekipler olacaktır. Bir ajanı görsel işleme hattına bağlıyorsanız, API hızlı başlangıç kılavuzu ilk istekte size yol gösterir; API genel bakış sayfası ise ilk anahtarınızdaki 50 ücretsiz görselden $125 karşılığında 500 görselden başlayan paketlere kadar fiyatlandırmayı kapsar.

Model yetenekleri, kıyaslama skorları ve fiyatlar 3 Ekim 2026 tarihinde aşağıdaki kaynaklara göre kontrol edilmiştir. API istek yapıları Roomagen API v1'i yansıtır; güncel teknik özellikler için belgelere bakın.