Uygulamanıza Sanal Sahneleme Nasıl Eklenir: Geliştiriciler İçin API Eğitimi

Ne İnşa Ediyorsunuz: Bir Sahneleme Özelliğinin Mimarisi

Bu eğitimin sonunda uygulamanız, kullanıcıdan bir oda fotoğrafı alacak, onu bir sanal ev sahneleme (virtual staging) API'sine gönderecek ve 10–40 saniye sonra o odanın mobilyalanmış, fotogerçekçi bir sürümünü döndürecek. Özelliğin tamamı bu. Geri kalan her şey — webhook'lar, yeniden denemeler, kredi bütçeleme, bildirim etiketleri — bu döngüyü üretim ölçeğinde güvenilir kılmak için var.

Talep tarafı gayet oturmuş durumda. Küresel sanal sahneleme pazarı 2025'te 454 milyon dolara ulaştı ve ilanlar çevrimiçi ilgi için yarışırken sahneleme talebi tırmanmaya devam ediyor:

"Küresel sanal sahneleme çözümü pazarının 2025'teki 454 milyon dolardan 2035'e kadar 4,73 milyar dolara büyümesi öngörülüyor." — Business Research Insights

Bir ilan platformu, fotoğraf teslim aracı, mülk yönetimi paneli veya proptech CRM'i işletiyorsanız, sahneleme giderek kullanıcılarınızın ayrı bir serviste değil, sizin ürününüzün içinde beklediği bir özellik hâline geliyor.

Mimari olarak piyasadaki her sahneleme API'si — Roomagen, AI HomeDesign, Decor8 ve birkaç diğeri — aynı asenkron iş desenini izliyor. Üretim onlarca saniye sürer; bir HTTP isteğini açık tutmak için fazlasıyla uzun bir süre. Bu yüzden akış her zaman şöyledir: işi gönder, hemen bir iş kimliği (job ID) al, sonuçları daha sonra teslim al.

Aşama	Kim yönetiyor	Tipik gecikme
Fotoğrafı yükleme ve doğrulama	Uygulamanız	1 saniyeden az
Sahneleme işini gönderme	Backend'iniz → sahneleme API'si	1 saniyeden az
Yapay zekâ üretimi	Sahneleme sağlayıcısı	10–40 saniye
Tamamlanma bildirimi	Webhook (push) veya polling (pull)	0–10 saniye
Sonuçları depolama ve gösterme	Uygulamanız	1 saniyeden az

Bu eğitim, endpoint'leri jenerik desene temiz biçimde oturduğu için çalışılmış örnek olarak Roomagen API'sini kullanıyor; ancak buradaki her kavram — asenkron işler, webhook'a karşı polling, idempotency, başarısızlık ekonomisi — herhangi bir sağlayıcıya doğrudan taşınır. Roomagen'e özgü davranış önemli olduğunda, bu açıkça belirtiliyor.

Başlamadan Önce: Anahtarlar, Ortamlar ve Görsel Gereksinimleri

Entegrasyon kodu yazmadan önce üç şeye ihtiyacınız var: bir API anahtarı, ortamları ayırma planı ve sağlayıcının girdi gereksinimlerini karşılayan görseller.

Anahtar edinmek. Roomagen'in API'si erken erişimde: roomagen.com/api adresinden bekleme listesine katılın; ücretsiz geliştirici katmanı ayda 50 filigranlı çağrı içeriyor — hiçbir harcama yapmadan entegrasyonun tamamını kurup test etmeye yeter. Anahtarlar rmg_live_... biçimindedir ve bir X-Api-Key header'ında gönderilir. Hangi sağlayıcıyı seçerseniz seçin aynı iki kural geçerli: anahtarı sunucu tarafında bir ortam değişkeninde tutun ve asla istemci tarafı JavaScript'e ya da bir mobil binary'ye koymayın; oradan herkes anahtarı çıkarıp kredilerinizi tüketebilir.

Ortamlar. Sağlayıcı veriyorsa geliştirme ve üretim için ayrı anahtarlar kullanın. Geliştirme sırasında filigranlı çıktı aslında işe yarar — test görsellerinin yanlışlıkla canlı bir ilana ulaşmasını engeller.

Görsel girdileri. Sahneleme kalitesi büyük ölçüde girdi kalitesine bağlıdır. Aşağıdaki tablo, Roomagen'in gereksinimlerini somut örnek alarak bir sahneleme API'sinin tipik beklentilerini özetliyor.

Gereksinim	Öneri
Format	JPEG veya PNG
Teslimat	Herkese açık image_url (tercih edilen) veya image_base64
Çözünürlük	Uzun kenarda 1024px+; daha yüksek girdi daha kaliteli çıktı verir
İçerik	Tek bir oda, düz açıyla çekilmiş, makul aydınlatılmış; geniş açı uygundur
Oda durumu	Boş odalar en öngörülebilir şekilde sahnelenir; mobilyalı odalar yeniden tasarım araçlarına uygundur

Pratik bir not: önemsiz dosya boyutlarının üzerindeki her şey için URL geçirmek base64'ten iyidir. Backend'iniz yeniden kodlama yükünden kurtulur, istek gövdeleri küçük kalır ve sağlayıcı görseli doğrudan CDN'inizden veya imzalı depolama URL'nizden çeker.

Son olarak kredi bakiyenizi programatik olarak kontrol edin. Roomagen, image_credits döndüren GET /api/v1/account endpoint'ini sunuyor — yönetici panelinizden veya günlük bir cron'dan sorgulayın ki ay ortasında sürprizle karşılaşmayın. Kredi tabanlı çoğu sağlayıcının eşdeğer bir endpoint'i var; düşük bakiye uyarısını bağlamak şimdi on dakika, sonrası ise bir kesinti demek.

Adım 1: Sahneleme İşi Gönderin

Çekirdek çağrı tek bir POST. Hangi aracın çalışacağını, görseli, stil seçeneklerini ve isteğe bağlı olarak tamamlanma bildirimi için bir webhook URL'sini belirtirsiniz.

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: rmg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.yourapp.com/rooms/123.jpg",
    "options": { "room_type": "living_room", "style": "scandinavian" },
    "webhook_url": "https://yourapp.com/hooks/roomagen"
  }'

Yanıt hemen döner — üretim bitmeden önce:

{ "job_id": "job_8f3ka92m", "status": "processing", "images_charged": 1 }

Aynı çağrının Node.js backend'inden hâli:

const res = await fetch("https://api.roomagen.com/api/v1/jobs", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.ROOMAGEN_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    tool: "virtual-staging",
    image_url: imageUrl,
    options: { room_type: "living_room", style: "scandinavian" },
    webhook_url: "https://yourapp.com/hooks/roomagen"
  })
});
const { job_id } = await res.json();

Yanıt geldiği anda yapılacak iki şey var. Birincisi, başka bir şey yapmadan önce job_id değerini kendi kaydınızla — ilan, fotoğraf, kullanıcı — ilişkilendirerek kalıcılaştırın. O satır sizin idempotency çapanızdır: süreciniz çökerse, işi yeniden gönderip iki kez ödemek yerine kimliğiyle kurtarabilirsiniz. İkincisi, iç muhasebeniz sağlayıcınınkiyle örtüşsün diye images_charged değerini kaydedin.

tool alanının yalnızca bir slug olduğuna dikkat edin. Roomagen'in GET /api/v1/tools endpoint'i, tamamı bu birebir aynı iş desenini kullanan 40'tan fazla aracı listeliyor — aralarında boş odalar için sanal sahneleme, gündüzden alacakaranlığa (day-to-dusk) dönüşüm, dağınıklık gidermek için nesne kaldırma, pozlama ve renk düzeltme için görsel iyileştirme, eskizden kat planına dönüşüm ve sanal renovasyon var. Aşağıdaki iş döngüsü sahneleme için çalıştığında, uygulamanıza bir "alacakaranlık fotoğrafı" veya "dağınıklığı kaldır" düğmesi eklemek, tool alanında tek satırlık bir değişikliktir. Bu çoklu araç deseni, değerlendirdiğiniz her sağlayıcıda kontrol etmeye değer: tek araçlı API'ler, yol haritanız büyüdüğünde sıfırdan yeniden entegrasyon demektir.

Özellikle boş oda ilanları için virtual-staging asıl iş atıdır; mobilyalı odalar ise önce bir yeniden tasarım aracına veya bir mobilya kaldırma aracına yönlendirilmelidir — arayüzünüzün basit bir "oda boş mu?" anahtarıyla sunabileceği bir ayrım.

Adım 2: Tamamlanmayı Yönetin — Webhook vs Polling

İşiniz işleniyor. Şimdi ne zaman bittiğini bilmeniz gerekiyor. Tam olarak iki mekanizma var ve olgun entegrasyonlar ikisini de kullanır.

Boyut	Webhook (push)	Polling (pull)
Gecikme	Tamamlanınca neredeyse anında	Bir polling aralığına kadar (5–10 sn)
Altyapı	Herkese açık HTTPS endpoint gerekir	Bir zamanlayıcı dışında hiçbir şey
Güvenilirlik	Teslimat başarısız olabilir (sizin kesintiniz, ağ)	Sağlam — döngüyü siz kontrol edersiniz
Güvenlik işi	İmza doğrulaması gerekir	Yalnızca API anahtarı
Sunucu maliyeti	İş başına bir istek	İş başına N istek
En uygun olduğu yer	Hacimli üretim	Geliştirme, yedek kanal, düşük hacim

Önerilen desen: birincil kanal olarak webhook, yedek olarak polling. Her işte bir webhook_url kaydedin ve ayrıca — diyelim 60 saniye içinde webhook gelmezse devreye giren — her 5–10 saniyede bir GET /api/v1/jobs/{id} çağıran bir polling kontrolü zamanlayın. Polling'i katı bir zaman aşımıyla (2–3 dakika) sınırlayın; sonrasında iş arayüzünüzde başarısız olarak işaretlenir. Bu kombinasyon, anlamlı bir maliyet eklemeden her iki taraftaki webhook kesintilerinden sağ çıkar. Hem GitHub'ın hem Stripe'ın webhook rehberliği aynı ilkelerde birleşiyor: hızlı yanıt verin, imzaları doğrulayın, tekilleştirin ve polling ile mutabakat sağlayın.

İmza doğrulamalı minimal bir Express webhook handler'ı:

app.post("/hooks/roomagen", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.get("X-Roomagen-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.ROOMAGEN_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { job_id, status, result_urls } = JSON.parse(req.body);
  completeJob(job_id, status, result_urls); // must be idempotent
  res.sendStatus(200);
});

Burada üç ayrıntı önemli. Birincisi, imzayı JSON ayrıştırmadan önce, ham gövde üzerinde doğrulayın — Roomagen, yükleri HMAC-SHA256 ile imzalar (RFC 2104) ve özeti X-Roomagen-Signature header'ında gönderir; çoğu sağlayıcı eşdeğer bir şema kullanır. Doğrulamayı atlamak, endpoint URL'nizi keşfeden herkesin uygulamanıza sahte "completed" olayları enjekte edebilmesi demektir. İkincisi, === değil, zamanlama açısından güvenli (timing-safe) bir karşılaştırma kullanın. Üçüncüsü, tamamlanma handler'ını idempotent yapın: webhook sistemleri başarısızlıkta yeniden dener, dolayısıyla aynı olay iki kez gelebilir ve polling de işi zaten tamamlamış olabilir. Genellikle bir UPDATE ... WHERE status = 'processing' koruması yeterlidir.

Polling yaparken durum endpoint'i ihtiyacınız olan her şeyi döndürür: status (processing, completed veya failed), başarıda result_urls, başarısızlıkta error ve gecikme izleme için loglamaya değer processing_ms.

Adım 3: Sonuçları Kullanıcılarınıza Teslim Edin

Tamamlanan bir iş, üretilen görsellere işaret eden bir URL dizisi olan result_urls döndürür. Bunlara hotlink verme cazibesine direnin.

Sonuçları kendi depolamanızda yeniden barındırın. Her sonuç URL'sini indirin ve kendi S3, R2 veya GCS bucket'ınıza yazın, sonra kendi CDN'inizden sunun. Sağlayıcı sonuç URL'leri kalıcı altyapı değil, geçici teslimat mekanizması olarak görülmelidir: saklama politikaları değişkendir ve bir sağlayıcı eski işleri temizlediğinde ya da tedarikçi değiştirdiğinizde ürününüzün görselleri kırılmamalıdır. İndir-ve-depola adımı beş satır koddur ve gelecekteki koca bir olay kategorisini ortadan kaldırır.

Orijinali her zaman saklayın. Kaynak fotoğrafı ve sahnelenmiş fotoğrafı bağlantılı bir çift olarak depolayın. Bu üç nedenle önemli: arayüzünüz bir önce/sonra kaydırıcısı sunabilir (sahnelemeyi sunmanın istikrarlı biçimde en yüksek etkileşimli yolu), kullanıcılarınız geri dönebilir ve — ABD emlak bağlamlarında — düzenlemeler, düzenlenmemiş görselin erişilebilir kalmasını giderek daha fazla zorunlu kılıyor. Roomagen'in iş sonuçları tam da bu nedenle orijinal ve düzenlenmiş görselleri eşleştirmek üzere tasarlandı.

İlan bağlamlarında sahnelenmiş görselleri etiketleyin. Kullanıcılarınız MLS platformlarına yayın yapıyorsa, bildirim artık isteğe bağlı bir nezaket değil. California'nın AB 723 yasası, 1 Ocak 2026 itibarıyla yapay zekâyla değiştirilmiş ilan görsellerinin bildirilmesini gerektiriyor ve ABD genelindeki MLS kuralları görünür bir "Virtually Staged" etiketi bekliyor. Roomagen, işareti doğrudan çıktı görseline render eden isteğe bağlı bir bildirim etiketi parametresi sunuyor — alt akış yayıncılığını uyumlu tutmanın en az çabalı yolu. Hukuki ayrıntı başlı başına bir konu; entegrasyonunuz için kısa versiyon şu: sahnelenmiş/orijinal ayrımını veri modelinizde saklayın ve sahnelenmiş bir görselin ilana ulaşabileceği her yerde etiketi gösterin.

Yeniden üretimi kullanıcıya açın. Üretken çıktının varyansı vardır; bazen kanepe yanlış olur. Roomagen görsel başına 1 ücretsiz yeniden üretim içeriyor; dolayısıyla her sonucun yanındaki "Yeniden Üret" düğmesi ilk deneme için size hiçbir şeye mal olmaz ve destek taleplerini ciddi biçimde azaltır. Hangi sağlayıcıyı kullanırsanız kullanın, yeniden üretim politikasını kontrol edin ve kullanıcılara yazı tura için para ödetmek yerine bunu arayüzünüze yansıtın.

Aynı teslimat hattı, daha sonra ekleyeceğiniz diğer her araca da hizmet eder — eskizden üretilmiş bir kat planı, bir alacakaranlık dış cephesi, bir gökyüzü değiştirme veya bir mutfak renovasyonu önizlemesi, hepsi birebir aynı webhook üzerinden result_urls olarak döner.

Üretim Kaygıları: Hız Limitleri, Yeniden Denemeler ve Kredi Bütçeleme

Yukarıdaki entegrasyon çalışır. Şu dört pratik, yük altında da çalışmaya devam etmesini sağlar.

Yeniden denemeler ve backoff. İş gönderimindeki 429 ve 5xx yanıtlarını üstel backoff ile (1 sn, 2 sn, 4 sn, 30 sn'de sabitleyin) yeniden denenebilir kabul edin. Kritik nokta: yalnızca işin oluşturulmadığından emin olduğunuzda yeniden deneyin — istek gönderildikten sonra gönderim zaman aşımına uğradıysa, yeniden göndermeden önce sakladığınız kayıtları ve hesabın iş listesini kontrol edin; yoksa mükerrer üretimlere ödeme yaparsınız. Bu, Adım 1'deki idempotency çapasının kendini amorti ettiği yerdir.

Başarısızlık ekonomisi. Marjlarınızı modellemeden önce başarısızlıkların neye mal olduğunu anlayın. Roomagen'de altyapı hataları asla kredi tüketmez ve başarısız işler otomatik iade edilir; yani bir failed durumu bir maliyet değil, bir rahatsızlıktır. Her sağlayıcı böyle çalışmaz — bazıları deneme başına ücret alır — bu yüzden bu konu, görsel başına fiyatın yanında değerlendirme kontrol listenize aittir. Arayüzünüz "başarısız oldu, ücret alınmadı, tekrar deneyin" ile "tamamlandı ama beğenmediniz, ücretsiz yeniden üretiminizi kullanın" durumlarını ayırt etmelidir.

Kredi bütçeleme. Kredi paketli API'ler hacim taahhüdünü ödüllendirir. Roomagen'in güncel paketleri:

Aylık hacim	Paket fiyatı	Görsel başına efektif maliyet
500 görsel	$125	$0.25
2.500 görsel	$550	$0.22
10.000 görsel	$2,000	$0.20
50.000+ görsel	Özel	Pazarlıkla

Karşılaştırma için: AI HomeDesign'ın API'si yaklaşık görsel başına $0.24, Decor8 ise yaklaşık $0.20 civarında — güvenilir sağlayıcılar aynı bantta kümeleniyor; dolayısıyla sağlayıcı seçimi birkaç sentlik birim fiyattan çok araç genişliğine, webhook kalitesine ve uyumluluk özelliklerine bağlı olma eğiliminde. Bütçe yaparken, ücretsiz olanın ötesindeki yeniden üretimleri ve kullanıcı denemelerini karşılamak için beklenen hacmi kabaca 1,1× ile çarpın ve alıcı tarafındaki marj matematiğini unutmayın: emlakçılar insan eliyle sahneleme servislerine görsel başına rutin olarak $16–$69 ödüyor; size görsel başına $0.20–$0.25'e mal olan bir özellik, nasıl paketlerseniz paketleyin sağlıklı bir fiyatlandırmaya alan bırakır.

Olgunluk üzerine dürüst bir uyarı. Roomagen'in API'si, şu anda bekleme listesi arkasında erken erişimde olan bir 2026 girişi — modern ergonomi (HMAC webhook'lar, otomatik iadeler, tek endpoint'te 40+ araç) alırsınız ama on yıllık sınanmış bir çalışma süresi geçmişi veya büyük bir kamuya açık topluluk alamazsınız. Bugün anında self-servis kayıt gerekiyorsa, yukarıdaki alternatifler API erişimini daha uzun süredir satıyor. Bu eğitimdeki jenerik mimarinin bilinçli olarak sağlayıcıdan bağımsız olmasının nedeni tam da bu: iş tablonuz, webhook handler'ınız ve depolama hattınız bir tedarikçi değişiminden neredeyse hiç dokunulmadan sağ çıkar.

Sahneleme API Entegrasyonlarında Sık Yapılan Hatalar

Sahneleme entegrasyonlarında yedi hata kalıbı tekrar tekrar karşımıza çıkıyor. Hepsi önlenebilir.

1. İstek iş parçacığını bloke etmek. Kullanıcının HTTP isteğini 10–40 saniyelik üretim boyunca açık tutmak sunucu kaynaklarını bağlar ve çoğu yük dengeleyicide zaman aşımına uğrar. İşi gönderin, kendi iç kayıt kimliğinizle 202 Accepted döndürün ve istemcinin güncellemelere WebSocket, SSE veya kendi API'nizin basit polling'i üzerinden abone olmasına izin verin.

2. Yalnızca webhook'lara güvenmek. Deploy pencereniz, bir TLS yapılandırma hatası veya sağlayıcı tarafındaki bir teslimat aksaması eninde sonunda bir webhook'u yutacaktır. Polling yedeği olmadan o iş, arayüzünüzde sonsuza dek "processing" durumunda asılı kalır. Adım 2'deki çift kanallı desen neredeyse hiçbir şeye mal olmaz.

3. İmza doğrulamasını atlamak. Doğrulanmamış bir webhook endpoint'i, uygulama durumunuza açılmış bir yazma API'sidir. HMAC'i ham gövde üzerinde timing-safe karşılaştırmayla doğrulayın — yukarıda gösterildi, on satır.

4. Sonuç URL'lerine hotlink vermek. Sağlayıcı URL'leri geçicidir. Sonuçları tamamlanma anında kendi depolamanızda yeniden barındırın, her seferinde.

5. Idempotency kontrolü olmadan yeniden göndermek. Ağ zaman aşımları artı naif yeniden denemeler, çifte ücret demektir. job_id değerini gönderim anında kalıcılaştırın ve yeniden denemeleri kendi kayıtlarınıza bağlayın.

6. İlan pazarlarında bildirimi görmezden gelmek. Sahnelenmiş görseller ürününüz üzerinden bir MLS'e ulaşabiliyorsa, etiketsiz bir görsel artık California'da kullanıcılarınız için hukuki bir risk ve büyük portallarda bir politika ihlalidir. Sahnelenmiş bayrağını veri modelinizde taşıyın ve etiketi render edin.

7. Başarısızlık deneyimi olmadan yayınlamak. Arayüz açısından 10–40 saniye uzun bir süredir ve işlerin küçük bir yüzdesi başarısız olacaktır. İşleme durumunu (ilerleme göstergesi, iskelet görsel), başarısızlık durumunu (net yeniden deneme, "ücret alınmadı") ve yeniden üretim olanağını lansmandan önce tasarlayın, ilk destek talebinden sonra değil.

Sonuç: Önce Döngüyü Yayınlayın, Sonra Genişletin

Bir uygulamaya sanal sahneleme eklemek gerçekten küçük bir entegrasyondur: iş oluşturmak için bir POST, polling yedeği olan bir webhook handler ve sonuçlar için bir depolama adımı. Çalışan bir prototip bir öğleden sonraya sığar; üretim sertleştirmesi — idempotent tamamlama, imza doğrulama, yeniden deneme disiplini, bildirim etiketleri — bir gün daha alır. Hacim paketlerinde görsel başına $0.20–$0.25 ile, başarısız işlerin otomatik iade edildiği ve sonuçların 10–40 saniyede teslim edildiği bu ekonomi, bir fotoğrafçının teslimat portalından ulusal bir ilan platformuna kadar her şey için çalışır.

Mimari bilinçli olarak sağlayıcıdan bağımsız: asenkron iş gönderimi, çift kanallı tamamlanma yönetimi, yeniden barındırılan sonuçlar ve veri modelinizdeki sahnelenmiş/orijinal çifti, şimdi seçeceğiniz ya da sonra geçeceğiniz her sahneleme API'sine uyar.

Bu eğitimdeki çalışılmış örneğe karşı geliştirmek isterseniz, Roomagen API bekleme listesine katılın — ücretsiz geliştirici katmanı ayda 50 filigranlı çağrı içeriyor; bu, ücretli bir taahhüt olmadan bu rehberdeki entegrasyon ve test döngüsünün tamamını karşılar. Oradan itibaren aynı iş endpoint'i, tek bir entegrasyonun arkasında size sanal sahneleme, day-to-dusk, nesne kaldırma, görsel iyileştirme ve kat planı araçları verir.