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

Bir uygulamaya sanal sahneleme eklemek temelde tek bir döngüye dayanır: arka ucunuz bir sanal sahneleme API'sine iş olarak bir oda fotoğrafı gönderir, sağlayıcı bunu arka planda işler ve uygulamanız sonucu alıp orijinalin yanında saklar ve hedef platformun gerektirdiği bildirimle birlikte gösterir. Bu eğitim, cURL, Node.js ve Python kodlarıyla Roomagen API'si üzerinde bu döngüyü kurar ve tasarımı diğer sağlayıcılara taşınabilir halde tutar.

Entegrasyona genel bakış

1. Her fotoğrafı sunucunuzdan bir iş olarak gönderin: bir Idempotency-Key ile POST /v1/jobs.
2. Başka bir şey yapmadan önce dönen job_id değerini saklayın.
3. Tamamlanan işi imzalı bir webhook üzerinden alın ve kaçırılanları GET /v1/jobs/{id} ile mutabakat yaparak eşitleyin.
4. Sonucu kendi sunucunuzda yeniden barındırın, orijinali yanında saklayın ve bildirim verilerini her dışa aktarıma taşıyın.

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

Bu eğitimin sonunda uygulamanız, Roomagen'in belgelerine göre bir oda fotoğrafı kabul edip genellikle 20 ila 60 saniye sonra aynı odanın döşenmiş bir versiyonunu gösterecektir. Buradaki diğer her şey, bu döngüyü üretim hacminde güvenilir kılmak için vardır. Aynı döngü; ilan portallarına, fotoğraf teslim platformlarına, boş birimleri pazarlayan mülk yönetimi yazılımlarına, müşterinin kendi odası üzerinde konsept sunan iç tasarım uygulamalarına ve seçilen bir tarzda döşenmiş odayı gösteren mobilya perakendecilerine hizmet eder.

Görsel işleme onlarca saniye sürer; bu da bir HTTP isteğini açık tutmak için çok uzun bir süredir, bu nedenle tasarım asenkrondur: işi gönderin, hemen bir iş kimliği alın, sonucu daha sonra toplayın. Sahneleme çok adımlı bir işlem hattı çalıştırır (sahne analizi, ardından prompt, ardından üretim), bu nedenle gündüzden alacakaranlığa dönüştürme gibi araçlardan daha yavaştır: Roomagen'in 1 Ekim 2026'ya kadarki 30 günlük üretim verilerinde, medyan API sahneleme işi yaklaşık 45 saniye sürerken, gündüzden alacakaranlığa dönüştürme ve kat planından 3D'ye dönüştürme için bu süre yaklaşık 25 saniyeydi.

Roomagen, web uygulamasında 40'tan fazla araç bulunan bir AI fotoğraf düzenleme ve sanal sahneleme platformudur; API, kabul ettiği her aracı (Ekim 2026 itibarıyla 65 adet) tek bir iş uç noktasının arkasında belgeler. Görüntü araçları Google'ın Gemini görüntü modelleri üzerinde çalışır ve API; sahneleme işlem hattını, iş yönetimini, başarısız işlemler için otomatik para iadelerini ve imzalı webhook'ları ekler.

Başlamadan Önce: Anahtarlar, Ortamlar ve Görüntü Gereksinimleri

Anahtar alma. Roomagen'in API'si 30 Ağustos 2026'daki herkese açık lansmanından bu yana self-servistir; bekleme listesi yoktur. Geliştirici portalında bir Roomagen hesabıyla oturum açın, e-postanızı doğrulayın ve API hızlı başlangıç kılavuzunda açıklandığı gibi bir anahtar oluşturun. İlk anahtarınız, hesap başına bir defaya mahsus olmak üzere 50 ücretsiz görsel ekler; bu da bu kılavuzdaki her şeyi inşa etmek ve test etmek için yeterlidir. Hesap bir paket satın alana kadar her işlem çıktısı bir Roomagen filigranı taşır, bu nedenle bunları yayınlamak için değil, derleme ve test için kullanın.

Anahtarlar, X-Api-Key başlığında gönderilen rmg_live_ ve ardından gelen 64 onaltılık (hexadecimal) karakterden oluşur ve portal her anahtarı yalnızca bir kez gösterir. Bunu sunucu tarafındaki güvenli bir kasada saklayın; herkesin ayıklayıp bakiyenizi harcayabileceği tarayıcı JavaScript'ine veya bir mobil uygulamaya kesinlikle dahil etmeyin.

Ortamlar. Bir hesap en fazla 10 etkin anahtar tutabilir, bu nedenle her ortam için bir tane oluşturun ve diğerine dokunmadan birini iptal edin. Test modu yoktur: her anahtar canlıdır ve bir hesabın anahtarları tek bir görsel bakiyesini, tek bir portal webhook'unu ve tek bir imzalama gizli anahtarını paylaşır; bu nedenle geliştirme işlerine iş başına özel webhook_url verin. Tasarım gereği bir döndürme (rotate) butonu yoktur: yeni anahtarı oluşturun, dağıtın (deploy edin), ardından eskisini iptal edin.

Görüntü girdileri.

image_url tercih edin: istekler küçük kalır, base64'ün getirdiği %33'lük ek yükten kurtulursunuz ve getirme işlemi POST isteğiniz sırasında gerçekleştiğinden, imzalı bir URL'nin yalnızca bu istek süresince geçerli olması yeterlidir. Tam boyutlu dışa aktarımı, kare başına bir oda olacak şekilde, düz açıyla çekilmiş ve makul düzeyde aydınlatılmış olarak gönderin; model yalnızca görebildiği ayrıntıları koruyabilir.

Bakiyeyi kod ile kontrol etme. GET /v1/account, bakiyenizin halen işleyebileceği görseller olan image_credits değerini döndürür. Düşük bakiye uyarısını hemen buna bağlayın: bakiye bir işi karşılayamadığında POST /v1/jobs, 402 insufficient_credits yanıtını verir ve hiçbir iş oluşturulmaz.

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

Tek bir POST işi oluşturur: araç, görsel, seçenekler ve isteğe bağlı olarak iş başına bir webhook_url (bu olmadan Roomagen, portalda kayıtlı hesap webhook'unu kullanır veya yoklama yaparsınız).

curl -X POST https://api.roomagen.com/api/v1/jobs \
  -H "X-Api-Key: $ROOMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: photo-4821-3-stage" \
  -d '{
    "tool": "virtual-staging",
    "image_url": "https://cdn.example.com/rooms/4821-3.jpg",
    "options": { "style": "scandinavian", "roomType": "living-room", "mode": "empty-room" },
    "webhook_url": "https://app.example.com/hooks/roomagen"
  }'

Yanıt, görsel işleme tamamlanmadan önce 201 durumuyla gelir:

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

Node.js 18+ arka ucundan aynı çağrı:

async function submitStagingJob(photo) {
  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",
      "Idempotency-Key": `photo-${photo.id}-stage`, // derived from your record, never random
    },
    body: JSON.stringify({
      tool: "virtual-staging",
      image_url: photo.signedUrl,
      options: { style: photo.style, roomType: photo.roomType, mode: "empty-room" },
      webhook_url: "https://app.example.com/hooks/roomagen",
    }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  await db.query(
    "INSERT INTO staging_jobs (photo_id, job_id, status, images_charged) VALUES ($1, $2, 'processing', $3)",
    [photo.id, body.job_id, body.images_charged],
  );
  return body.job_id;
}

Sahneleme diğer araçlara göre daha katıdır. style zorunludur, seçenekler camelCase biçimindedir ve aşağıdaki listenin dışındaki herhangi bir anahtar (room_type, resolution, tier ve customPrompt dahil) invalid_request ile reddedilir. Sahneleme her zaman 2K olarak işlenir ve bir görsel tutarındadır.

Bu üç mod, Roomagen'in web uygulamasındaki sahneleme modlarına karşılık gelir; böylece ürün ekibiniz kod yazmadan önce bunları deneyebilir: boş odalar için AI sanal sahneleme, restyle için döşeli odaları yeniden tasarlayın ve recreate için Oda Amacını Değiştirme.

Her şeyden önce kalıcı olarak kaydedin. Kendi kaydınızın karşısına job_id ve images_charged değerlerini kaydedin. Idempotency-Key başlığı (128 karaktere kadar, API anahtarınıza özel kapsamlı), yeniden denemeleri güvenli hale getirir: aynı gövdeye sahip aynı anahtar, ikinci bir ücretlendirme olmadan orijinal işi döndürür. Çökme sonrasında yeniden oluşturabilmek için anahtarları kayıtlarınızdan türetin ve tamamen aynı gövdeyi yeniden gönderin: yeniden imzalanmış bir image_url de dahil olmak üzere farklı bir gövdeye sahip aynı anahtar 409 idempotency_conflict döndürür.

2. Adım: Tamamlanmayı Yönetme — Webhook'lar ve Yoklama (Polling)

Bir işin bittiğini öğrenmenin iki yolu vardır ve üretim entegrasyonları her ikisini de kullanır.

Öncelikle webhook'ları, güvenlik ağı olarak da yoklamayı kullanın. Roomagen'in belgeleri webhook'ları "kayıt sistemi değil, bir optimizasyon" olarak adlandırır; çünkü yeniden deneme penceresi sona erdiğinde teslimat terk edilir. Yalnızca yoklama yapmak da tek başına ölçeklenemez: 3 saniyelik bir aralıkta her bir iş dakikada 20 isteğe mal olur, bu nedenle GET /v1/jobs/{id} üzerindeki dakikada 300 istek sınırı, aynı anda yoklama yapan yaklaşık 15 işi karşılar.

Uç noktayı kurun. Yönlendirmeler izlenmediğinden nihai URL'yi kullanarak portalın Webhook kartına bir https uç noktası kaydedin. whsec_ imzalama gizli anahtarını bir şifre gibi saklayın ve doğrulama mantığını doğru kurarken Send test event (Test etkinliği gönder) ile bir job.test teslimatı tetikleyin. İş başına özel bir webhook_url de aynı gizli anahtarı kullanır.

const crypto = require("crypto");
const express = require("express");
const app = express();

// Raw body on this route, mounted before any global express.json()
app.post("/hooks/roomagen", express.raw({ type: "application/json" }), async (req, res) => {
  const ts = req.get("X-Roomagen-Timestamp");
  const sig = req.get("X-Roomagen-Signature");
  if (!ts || !sig) return res.sendStatus(401);

  const expected = "v1=" + crypto
    .createHmac("sha256", process.env.ROOMAGEN_WEBHOOK_SECRET) // whsec_...
    .update(`${ts}.`)
    .update(req.body) // the raw bytes, never re-serialized JSON
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (sig.length !== expected.length || !fresh ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const job = JSON.parse(req.body);
  if (job.event === "job.test") return res.sendStatus(200);

  // Idempotent: only the first delivery (or poll) moves the row out of "processing"
  const { rowCount } = await db.query(
    "UPDATE staging_jobs SET status = $1, result_urls = $2, error = $3 WHERE job_id = $4 AND status = 'processing'",
    [job.status, job.result_urls, job.error, job.job_id],
  );
  if (rowCount === 1 && job.status === "completed") {
    await queue.add("store-results", { jobId: job.job_id }); // download off the request path
  }
  res.sendStatus(200);
});

Dört ayrıntı önemlidir:

1. Ham baytlar üzerinden doğrulayın. Başlık, v1= ile {X-Roomagen-Timestamp}.{raw body}nin hex HMAC-SHA256 çıktısıdır; yeniden serileştirilmiş JSON eşleşmeyecektir.
2. Sabit zamanda karşılaştırın, ardından tazeliği kontrol edin. Node'un timingSafeEqual fonksiyonu eşit olmayan uzunluklarda hata fırlatır, bu nedenle önce uzunlukları karşılaştırın. Yaklaşık beş dakikadan eski zaman damgalarını reddetmek, yeniden oynatma (replay) saldırılarını engeller; bu, Stripe'ın webhook belgelerinde açıklanan savunmanın aynısıdır; sunucu saatlerini senkronize tutun.
3. Hızlı yanıt verin. Roomagen, 2xx yanıtı için 10 saniye bekler; zaman aşımı da dahil olmak üzere bunun dışındaki her şey başarısız bir denemedir ve tekrar denenir.
4. Idempotent olun. Teslimat en az bir kezdir ve sırasızdır; ayrıca yoklama mekanizmanız işi zaten tamamlamış olabilir, bu nedenle job_id üzerinden tekilleştirme yapın.

Yoklama için, geliştirme sırasında veya bir mutabakat aracı olarak Python sürümü oldukça kısadır:

import os, time, requests

API = "https://api.roomagen.com/api/v1"
HEADERS = {"X-Api-Key": os.environ["ROOMAGEN_API_KEY"]}

def wait_for_job(job_id, interval=3, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        job = r.json()
        if job["status"] != "processing":
            return job  # "completed" or "failed"; both are final
        time.sleep(interval)
    return None  # still processing: leave it to the reconciler

Bir iş, result_urls ile birlikte completed olarak veya error içinde bir neden ve otomatik para iadesiyle birlikte failed olarak sonlanır; gecikmeyi izlemek için processing_ms değerini günlüğe kaydedin (loglayın). Birkaç dakika sonra hâlâ processing durumunda olan işler için her bir veya iki dakikada bir mutabakat aracı çalıştırın. Yalnızca bir zamanlayıcı süresi doldu diye yavaş bir işi başarısız olarak işaretlemeyin: iş hâlâ tamamlanabilir ve oluşturulduğunda ücreti tahsil edilmiştir.

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

Tamamlanan bir iş, işlenmiş JPEG görsellerinden oluşan bir dizi olan result_urls döndürür. Bunları doğrudan hotlink ile sunmayın.

Sonuçları yeniden barındırın. Roomagen, sonuçları hesabın saklama süresine tabi olarak kendi depolama alanından sunar; bu nedenle bir arka plan işi, iş tamamlanır tamamlanmaz her görseli indirmeli, kendi depolama alanınıza (S3, R2, GCS veya benzeri) yazmalı ve CDN'iniz üzerinden sunmalıdır. Böylece görselleriniz asla bir sağlayıcının saklama politikasına bağımlı kalmaz.

Orijinali çıktının yanında saklayın. Kaynak fotoğrafı ve sahnelenmiş görseli bağlantılı bir çift olarak saklayın. Bu ikili bir öncesi/sonrası kaydırıcısını besler, kullanıcıların geri almasına olanak tanır ve ilan bildirim kurallarının talep ettiği şeydir (4. Adım).

Değişkenliği hesaba katın. Üretken modellerin çıktıları değişiklik gösterir ve bazen koltuk yanlış çıkabilir. Yeniden çalıştırma, başka bir görsele mal olan yeni bir iştir; çünkü Roomagen bir kullanıcının beğenmediği sonuçları değil, yalnızca teknik olarak başarısız olan işlemleri iade eder. Her yeniden çalıştırmaya photo-4821-stage-2 gibi kendi Idempotency-Key değerini verin: ilk anahtarı yeniden kullanmak orijinal işi döndürür veya gövde değiştiyse bir 409 hatası verir. Bir "Tekrar dene" butonu sunun ve bu maliyetin kullanıcılara yansıtılıp yansıtılmayacağına veya fiyatlandırmanıza dahil edilip edilmeyeceğine karar verin.

Bekleme ve hata durumlarını tasarlayın. Sahneleme genellikle bir dakika içinde tamamlanır; bu, arayüz açısından uzun bir süredir. Lansmandan önce ilerleme durumunu, hata durumunu ("görsel işleme başarısız oldu ve ücret iade edildi") ve yeniden deneme eylemini tasarlayın.

4. Adım: Bildirimi Veri Modelinize Dahil Edin

Kullanıcılarınız sahnelenmiş fotoğrafları emlak ilanlarına koyuyorsa, bildirim yapmak onların yasal görevidir ve veri modeliniz bunun kolay olup olmayacağını belirler. Roomagen'in API'si herhangi bir bildirim etiketi veya orijinal-düzenlenmiş eşleştirmesi eklemez ve Roomagen'in şartları bildirimi kullanıcının sorumluluğuna bırakır; bu nedenle entegrasyonunuzun bunu taşıması gerekir.

• 1 Ocak 2026'dan beri yürürlükte olan California AB 723. Bir taşınmaz satışına yönelik bir ilanda dijital olarak değiştirilmiş bir görsel kullanan bir broker veya satış temsilcisi ya da onlar adına hareket eden biri, görselin üzerinde veya hemen yanında değiştirildiğini belirtmeli ve orijinal, değiştirilmemiş görseli gösteren herkese açık bir siteye yönlendiren bir bağlantı, URL veya QR kod eklemelidir. California'nın gayrimenkul düzenleyicisi, bir AI aracı yanıltıcı reklam ürettiğinde sorumluluğun "teknoloji sağlayıcısına değil, lisans sahibine ve onun sorumlu broker'ına" ait olduğunu ekler.
• 1 Ocak 2027'den itibaren California kiralama ilanları. AB 2025, benzer bildirimi kiralama reklamlarını da kapsayacak şekilde genişleterek yalnızca lisans sahiplerini değil, konut sağlayıcılarını ve diğerlerini de kapsar hale getirir.
• MLS kuralları etiket yerleşimi konusunda farklılık gösterir. Canopy MLS, etiketin yalnızca altyazılarda değil doğrudan görselin üzerinde olmasını zorunlu kılarken, NWMLS üzerine bindirilmiş grafik veya metin içeren fotoğrafları kabul etmez.
• AB pazarına yönelik ürünler. 2 Ağustos 2026'dan bu yana, AB AI Yasası'nın 50. Maddesi, "deep fake" görseller (mevcut yerlere veya nesnelere benzeyen ve yanıltıcı bir şekilde gerçekmiş gibi görünebilecek içerikler) üreten veya bunları değiştiren AI sistemlerinin uygulayıcılarının bunu bildirmesini gerektirmektedir; gerçek bir taşınmazın AI ile düzenlenmiş fotoğrafları bu tanımı makul bir şekilde karşılayabilir (ayrıntılar için AB AI Yasası Madde 50 rehberimize bakın).

Bu nedenle bildirimi pikseller olarak değil, veri olarak saklayın: orijinal fotoğraf için herkese açık bir URL, kullanılan araç ve seçenekleri içeren bir altered bayrağı ile her hedef platform için bir bildirim metni ve etiket yerleşimi. Etiketi saklarken değil, dışa aktarırken görselin üzerine ekleyin.

Bu, inşa edenler için bir özettir, hukuki tavsiye değildir; AB 723 kılavuzumuz ve MLS fotoğraf gereksinimleri kılavuzumuz konuyu daha derinlemesine ele alır.

Üretim Konuları: Hız Sınırları, Yeniden Denemeler ve Kredi Bütçelemesi

Hız sınırları. Kayan bir 60 saniyelik pencerede anahtar başına: POST /v1/jobs için dakikada 60 istek, GET /v1/jobs/{id} için 300 istek ve GET /v1/tools ile GET /v1/account için 120 istek; ayrıca tek bir NAT adresi arkasındaki tüm sunucular tarafından paylaşılan, istemci IP'si başına dakikada 600 istek. Başarılı yanıtlar X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını taşır; bir 429 rate_limited yanıtı saniye cinsinden Retry-After başlığı taşır, bu nedenle kendi bekleme sürenizi uydurmak yerine buna uyun. Toplu işler için gönderimleri kuyruğa alın: dakikada 60 iş hızında, 500 fotoğrafın gönderilmesi sekiz dakikadan biraz fazla sürer.

Yeniden denemeler ve hata kodları. Her hata { "error": { "code", "message", "doc_url" } } yapısındadır. Asla message üzerinden değil, her zaman code üzerinden koşullandırma yapın:

Başarısızlık ekonomisi. Görsel üretimi sırasında başarısız olan bir işin ücreti otomatik olarak iade edilir, ancak iş üzerindeki images_charged değeri yeniden yazılmaz; bu nedenle bakiyeniz için tek doğru kaynak olarak GET /v1/account uç noktasını kabul edin. Sağlayıcıları karşılaştırırken fiyatın yanında hata politikalarını da kontrol edin.

Kredi bütçelemesi. Roomagen, API'yi geliştirici portalından önceden paketler halinde satın alınan görseller üzerinden faturalandırır:

Paketlerin süresi asla dolmaz ve birbirine eklenir. Belgelenen her araç, 2K çözünürlükte işleme başına bir görsele mal olur; bunu kabul eden araçlarda resolution: "4K" bu maliyeti ikiye katlar ve sahneleme her zaman bir görseldir. Bütçe oluştururken yeniden çalıştırmaları da dahil edin: ayda 1.200 fotoğraf sahneleyen ve her on fotoğraftan birinin yeniden çalıştırılmasını bekleyen bir platformun yaklaşık 1.320 görsele ihtiyacı vardır, dolayısıyla bir Growth paketi neredeyse iki ay yeterli olur.

Yayınlanan fiyatlar büyük farklılıklar göstermektedir (Ekim 2026'da kontrol edilmiştir): ModelsLab iç mekan render'ı başına 0,02 $, Decor8 tüm API işlemleri için görsel başına 0,20 $ ve AI HomeDesign yıllık faturalandırmayla fotoğraf başına 0,24 $ veya aylık faturalandırmayla yaklaşık 0,49 $ listelemektedir. Birim fiyatın yanı sıra araç kapsamını, webhook'ları, hata politikasını ve çıktı kalitesini de karşılaştırın; sanal sahneleme API'si fiyatlandırma kılavuzumuz ve sahneleme API'leri karşılaştırmamız sağlayıcıları tek tek incelemektedir.

Olgunluk konusunda dürüst bir uyarı. Roomagen'in API'si yenidir: 1. sürüm 30 Ağustos 2026'da tek bir iş uç noktasıyla kullanıma sunuldu ve belgeleri kabul ettiği her aracı ancak 3 Ekim 2026'dan bu yana kapsamaktadır; bu nedenle güncel standartlara sahiptir ancak yıllara dayanan bir geçmişe sahip değildir. Kırıcı değişiklikler (breaking changes), kullanıma sunulmadan önce etkin anahtara sahip hesaplara e-posta ile duyurulur; geriye dönük uyumlu eklemeler ise herhangi bir zamanda gelebilir, bu nedenle tanımadığınız yanıt alanlarını yok sayın.

Entegrasyonu Genişletme: Diğer Belgelenmiş Araçlar

Döngü sahneleme için çalıştığında, bir "alacakaranlık versiyonu" veya "dağınıklığı kaldır" butonu yalnızca tool ve options alanlarını değiştirir:

Bu araçlar ayrıca resolution (2K veya 4K), tier (auto, guided veya custom) ve customPrompt (500 karaktere kadar) seçeneklerini de kabul eder. Sahnelemenin aksine, bilinmeyen anahtarları yok sayarak her birini yanıtın warnings listesinde belirtirler ancak aralık dışı değerleri yine de reddederler. Pencereleri olmayan odalar için gündüzden alacakaranlığa aracına hasWindows: false gönderin; böylece prompt pencere ve manzara talimatlarını devre dışı bırakır.

GET /v1/tools, anahtarınızın çağırabileceği her slug'ı görsel maliyetiyle birlikte döndürür ve döndürdüğü her slug belgelenmiştir. Bu listeyi sabit kodlamak (hardcode) yerine dinamik olarak okuyun ve roomagen.com'daki araç adlarının API slug'ları olmadığını unutmayın.

API'nin Yapmadığı Şeyler

• Toplu iş uç noktası yoktur. Bir iş, tek bir araç üzerinden tek bir görsel anlamına gelir; web uygulamasının toplu işlem özelliği API'nin bir parçası değildir, bu nedenle işleri hız sınırları dahilinde kuyruğa alın.
• Bildirim etiketleri yoktur. Çıktılar bildirim etiketi veya öncesi/sonrası eşleştirmesi taşımaz. İşlenen görseller, hesap bir paket satın alana kadar filigranlıdır ve bundan sonra herhangi bir Roomagen markalaması taşımaz.
• Ücretsiz yeniden üretim yoktur. Yeniden çalıştırma yeni bir iştir ve o şekilde ücretlendirilir.
• Ölçümler veya CAD dosyaları yoktur. Çıktılar boyutlar, vektörler veya DWG dosyaları değil, JPEG görselleridir. Fotoğraflardan oda ölçülerine ihtiyacınız varsa, üretken görsel API'si yanlış araçtır.
• Garanti edilen çıktı yoktur. Üretken modeller yapay hatalar veya tutarsızlıklar üretebilir, bu nedenle bir ilana girmeden önce çıktıyı inceleyin.
• Yalnızca uygulamaya özel özellikler sunulmaz. Düzenle, Kitaplık ve Tasarım Asistanı sohbeti Roomagen'in web uygulamasında yer alır.

Sahneleme API Entegrasyonlarında Yaygın Hatalar

1. İstek iş parçacığını (thread) bloke etmek. Bir iş işlenirken kullanıcının isteğini açık tutmak, yük dengeleyici zaman aşımlarına yol açar. Kendi API'nizden 202 Accepted döndürün ve güncellemeleri istemciye push ile iletin.
2. Yanlış seçenek adları. Bir sahneleme işinde room_type veya resolution göndermek invalid_request hatası döndürür; sahneleme kendi listesinden camelCase anahtarlar ve her zaman style ister.
3. Yalnızca webhook'lara güvenmek. Yaklaşık 36 dakikalık yeniden denemelerden sonra Roomagen denemeyi bırakır. Bir mutabakat aracı olmadan bu iş sonsuza kadar "processing" durumunda kalır.
4. İmzayı yanlış doğrulamak. Ayrıştırılmış JSON'ın karmasını almak, zaman damgası önekini atlamak, === ile karşılaştırmak veya tazelik kontrolünü atlamak doğrulamayı zayıflatır.
5. Yönlendirme yapan bir webhook URL'si. Düz http ve özel ana bilgisayarlar en başta webhook_url_rejected ile reddedilir ve yönlendirmeler izlenmez; bu nedenle sonda taksim işareti veya www yönlendirmesi her teslimatı başarısız kılar.
6. Rastgele idempotency anahtarları veya yeniden imzalanmış URL'ler. Saklamadığınız bir anahtar yeniden oynatılamaz, bu nedenle yeniden deneme tekrar ücretlendirilir; aynı anahtar altında yeniden imzalanmış bir image_url ise 409 hatası döndürür.
7. Sonuç URL'lerine doğrudan hotlink vermek. Sonuçlar sağlayıcının saklama süresine tabidir. Tamamlandığında bunları kendi sunucunuzda yeniden barındırın.
8. Her hedef için tek bir filigran kullanmak. Görselin üzerine işlenmiş bir "Virtually Staged" (Sanal Olarak Sahnelenmiştir) etiketi, MLS'in üzerine bindirilmiş metinlere karşı kurallarını çiğneyebilir ve orijinaline bir bağlantı olmadan tek başına AB 723'ü karşılamaz.

Lansman Öncesi Kontrol Listesi

• API anahtarı, ortam başına bir tane olmak üzere yalnızca sunucularınızda barındırılır.
• Sahneleme istekleri her zaman style gönderir ve sahneleme seçenekleri listesi dışındaki hiçbir şeyi içermez.
• Her işin kayıtlarınızdan türetilmiş bir Idempotency-Key değeri vardır ve yeniden denemeler orijinal gövdeyi yeniden gönderir.
• Webhook uç noktası nihai https URL'sidir, ham gövde üzerindeki v1= imzalarını doğrular, eski zaman damgalarını reddeder ve 10 saniye içinde yanıt verir.
• Portaldan yapılan bir job.test teslimatı doğrulamadan geçer.
• Bir mutabakat aracı, birkaç dakika sonra hâlâ işlenmekte olan işleri kontrol eder.
• Sonuçlar, her biri orijinali yanında olacak şekilde yeniden barındırılır.
• Bildirim verileri (orijinal URL'si, değiştirildi bayrağı, hedefe özel etiket) her dışa aktarma yoluna ulaşır.
• Düşük bakiye uyarısı image_credits değerini okur ve her hata kodu kullanıcılarınız için anlaşılır bir mesajla eşleştirilir.

Özet: Döngüyü Yayına Alın, Ardından Genişletin

Bir uygulamaya sanal sahneleme eklemek küçük bir entegrasyondur: bir idempotency anahtarıyla yapılan bir POST, bir mutabakat aracıyla desteklenen doğrulanmış bir webhook işleyicisi ve orijinali sonucun yanında tutan bir depolama adımı. Sorunsuz ilerleyen senaryo (happy path) birkaç düzine satırdan ibarettir; işin çoğu üretim ortamı için sağlamlaştırma ve bildirim verilerinden oluşur. Bunların hiçbiri tek bir sağlayıcıya bağlı değildir: asenkron gönderim, push ve pull ile tamamlanma, yeniden barındırılan sonuçlar ve orijinal/çıktı ikilisi tüm sahneleme API'lerine uygundur.

İşlenen örnek üzerinden geliştirme yapmak için bir Roomagen API anahtarı alın: ilk anahtar 50 ücretsiz görsel içerir; ayrıca hızlı başlangıç kılavuzu, webhook kılavuzu ve hata referansı ayrıntıları ele alır. Böylece aynı iş döngüsü, tek bir entegrasyonun arkasında sanal sahneleme, gündüzden alacakaranlığa fotoğraf düzenleme & dönüştürme, fotoğraflardan AI nesne ve öğe kaldırma, fotoğraf geliştirme, sanal tadilat ve yenileme ve kat planından 3D'ye araçlarını da çalıştırır.