Virtuelles Staging zu Ihrer App hinzufügen: Ein API-Tutorial für Entwickler

Das Hinzufügen von virtuellem Staging zu einer App läuft auf eine Schleife hinaus: Ihr Backend sendet ein Raumfoto als Job an eine API für virtuelles Staging, der Anbieter rendert es im Hintergrund, und Ihre App holt das Ergebnis ab, speichert es neben dem Original und zeigt es mit der vom Zielort geforderten Offenlegung an. Dieses Tutorial baut diese Schleife für die Roomagen-API mit Code in cURL, Node.js und Python auf und hält das Design portabel für andere Anbieter.

Die Integration auf einen Blick

1. Senden Sie jedes Foto von Ihrem Server als Job: POST /v1/jobs mit einem Idempotency-Key.
2. Speichern Sie die zurückgegebene job_id, bevor Sie etwas anderes tun.
3. Empfangen Sie den fertigen Job über einen signierten Webhook und gleichen Sie Ausfälle mit GET /v1/jobs/{id} ab.
4. Hosten Sie das Ergebnis neu, behalten Sie das Original daneben und übertragen Sie die Offenlegungsdaten an jeden Export.

Was Sie bauen: Architektur einer Staging-Funktion

Am Ende dieses Tutorials wird Ihre App ein Raumfoto annehmen und typischerweise 20 bis 60 Sekunden später, gemäß der Dokumentation von Roomagen, eine möblierte Version desselben Raums anzeigen. Alles andere hier dient dazu, diese Schleife bei Produktionsvolumen zuverlässig zu machen. Dieselbe Schleife bedient Immobilienportale, Plattformen zur Fotolieferung, Hausverwaltungssoftware zur Bewerbung leerstehender Einheiten, Innenarchitektur-Apps, die ein Konzept im Raum des Kunden präsentieren, und Möbelhändler, die einen Raum in einem ausgewählten Stil präsentieren.

Ein Render-Vorgang dauert mehrere zehn Sekunden – viel zu lang, um eine HTTP-Anfrage offen zu halten. Daher ist der Aufbau asynchron: Senden Sie den Job ab, erhalten Sie sofort eine Job-ID und rufen Sie das Ergebnis später ab. Staging durchläuft eine mehrstufige Pipeline (Szenenanalyse, dann Prompt, dann Generierung), weshalb es langsamer ist als Werkzeuge wie Tag zu Dämmerung Fotobearbeitung & Umwandlung: In den Produktionsdaten von Roomagen für die 30 Tage bis zum 1. Oktober 2026 dauerte der mediane API-Staging-Job etwa 45 Sekunden, verglichen mit etwa 25 Sekunden für Tag zu Dämmerung Fotobearbeitung & Umwandlung und für Grundriss zu 3D.

Roomagen ist eine Plattform für KI-Fotobearbeitung und virtuelles Staging mit über 40 Werkzeugen in ihrer Web-App; die API dokumentiert jedes unterstützte Werkzeug (65 mit Stand Oktober 2026) hinter einem einzigen Job-Endpunkt. Die Bildwerkzeuge laufen auf den Gemini-Bildmodellen von Google, und die API ergänzt die Staging-Pipeline, die Job-Abwicklung, automatische Erstattungen für fehlgeschlagene Render-Vorgänge und signierte Webhooks.

Bevor Sie beginnen: Schlüssel, Umgebungen und Bildanforderungen

Einen Schlüssel erhalten. Die API von Roomagen ist seit ihrem öffentlichen Start am 30. August 2026 per Self-Service zugänglich; es gibt keine Warteliste. Melden Sie sich im Entwicklerportal mit einem Roomagen-Konto an, bestätigen Sie Ihre E-Mail-Adresse und erstellen Sie einen Schlüssel, wie im API-Quickstart beschrieben. Ihr erster Schlüssel fügt einmalig pro Konto 50 kostenlose Bilder hinzu, was ausreicht, um alles in diesem Leitfaden zu entwickeln und zu testen. Bis das Konto ein Paket kauft, ist jedes Rendering mit einem Roomagen-Wasserzeichen versehen; nutzen Sie diese also zum Entwickeln und Testen, nicht zur Veröffentlichung.

Schlüssel bestehen aus rmg_live_ plus 64 Hexadezimalzeichen, werden in einem X-Api-Key-Header gesendet, und das Portal zeigt jeden Schlüssel nur ein einziges Mal an. Bewahren Sie ihn in einem serverseitigen Secret-Speicher auf; binden Sie ihn niemals in Browser-JavaScript oder eine mobile App ein, wo ihn jeder auslesen und Ihr Guthaben aufbrauchen kann.

Umgebungen. Ein Konto kann bis zu 10 aktive Schlüssel halten. Erstellen Sie daher einen pro Umgebung und widerrufen Sie den einen, ohne den anderen zu beeinflussen. Es gibt keinen Testmodus: Jeder Schlüssel ist live, und die Schlüssel eines Kontos teilen sich ein Bildguthaben, einen Portal-Webhook und ein Signatur-Secret. Geben Sie Entwicklungsjobs daher eine eigene jobbezogene webhook_url. Es gibt bewusst keine Schaltfläche zur Schlüsselrotation: Erstellen Sie den neuen Schlüssel, führen Sie das Deployment durch und widerrufen Sie danach den alten.

Bildeingaben.

Bevorzugen Sie image_url: Anfragen bleiben klein, Sie vermeiden den 33%igen Overhead von Base64, und da der Abruf während Ihres POSTs stattfindet, muss eine signierte URL nur für diese Anfrage gültig sein. Senden Sie den Export in voller Größe, einen Raum pro Aufnahme, gerade ausgerichtet und angemessen beleuchtet; das Modell kann nur Details beibehalten, die es auch sehen kann.

Guthaben im Code prüfen. GET /v1/account gibt image_credits zurück, also die Bilder, die Ihr Guthaben noch rendern kann. Richten Sie jetzt eine Benachrichtigung bei niedrigem Guthaben ein: Wenn das Guthaben einen Job nicht mehr decken kann, antwortet POST /v1/jobs mit 402 insufficient_credits, und es wird kein Job erstellt.

Schritt 1: Einen Staging-Job absenden

Ein einziger POST erstellt den Job: das Werkzeug, das Bild, Optionen und optional eine jobbezogene webhook_url (ohne diese verwendet Roomagen den im Portal gespeicherten Konto-Webhook, oder Sie nutzen Polling).

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"
  }'

Die Antwort trifft mit dem Status 201 ein, bevor der Render-Vorgang abgeschlossen ist:

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

Derselbe Aufruf von einem Node.js-18+-Backend:

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;
}

Staging ist strenger als die anderen Werkzeuge. style ist erforderlich, Optionen stehen in camelCase, und jeder Schlüssel außerhalb der folgenden Liste, einschließlich room_type, resolution, tier und customPrompt, wird mit invalid_request abgelehnt. Staging rendert immer in 2K und kostet ein Bild.

Die drei Modi entsprechen den Staging-Modi in der Web-App von Roomagen, sodass Ihr Produktteam sie ausprobieren kann, bevor Sie Code schreiben: virtuelles Staging mit KI für leere Räume, Möblierte Zimmer mit KI neu gestalten für restyle und Raum umfunktionieren für recreate.

Zuerst persistieren. Speichern Sie job_id und images_charged zu Ihrem eigenen Datensatz. Der Header Idempotency-Key (bis zu 128 Zeichen, an Ihren API-Schlüssel gebunden) macht Wiederholungen sicher: Derselbe Schlüssel mit demselben Body gibt den ursprünglichen Job ohne erneute Abbuchung zurück. Leiten Sie Schlüssel aus Ihren Datensätzen ab, damit Sie sie nach einem Absturz wiederherstellen können, und senden Sie exakt denselben Body erneut: Derselbe Schlüssel mit einem abweichenden Body, einschließlich einer neu signierten image_url, gibt 409 idempotency_conflict zurück.

Schritt 2: Fertigstellung verarbeiten — Webhooks vs. Polling

Es gibt zwei Möglichkeiten zu erfahren, dass ein Job abgeschlossen wurde, und produktive Integrationen nutzen beide.

Verwenden Sie primär Webhooks und Polling als Sicherheitsnetz. Die Dokumentation von Roomagen bezeichnet Webhooks als „eine Optimierung, kein System of Record“, da eine Zustellung nach Ablauf des Wiederholungszeitfensters abgebrochen wird. Polling allein skaliert ebenfalls nicht: Bei einem Intervall von 3 Sekunden kostet jeder Job 20 Anfragen pro Minute, sodass das Limit von 300 Anfragen pro Minute für GET /v1/jobs/{id} etwa 15 gleichzeitig abfragende Jobs abdeckt.

Richten Sie den Endpunkt ein. Speichern Sie einen https-Endpunkt in der Webhook-Karte des Portals. Verwenden Sie die endgültige URL, da Weiterleitungen nicht verfolgt werden. Behandeln Sie das whsec_-Signatur-Secret wie ein Passwort und lösen Sie mit Send test event eine job.test-Zustellung aus, während Sie die Überprüfung einrichten. Eine jobbezogene webhook_url verwendet dasselbe Secret.

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);
});

Vier Details sind entscheidend:

1. Über die Rohdaten (Raw Bytes) verifizieren. Der Header besteht aus v1= plus einem hexadezimalen HMAC-SHA256 aus {X-Roomagen-Timestamp}.{raw body}; neu serialisiertes JSON stimmt nicht überein.
2. In konstanter Zeit vergleichen, dann die Aktualität prüfen. Nodes timingSafeEqual wirft bei ungleichen Längen einen Fehler aus, vergleichen Sie daher zuerst die Längen. Das Ablehnen von Zeitstempeln, die älter als etwa fünf Minuten sind, blockiert Replay-Angriffe – genau der Schutz, den die Webhook-Dokumentation von Stripe beschreibt. Halten Sie die Serveruhren synchronisiert.
3. Schnell antworten. Roomagen wartet 10 Sekunden auf ein 2xx; alles andere, einschließlich eines Timeouts, gilt als fehlgeschlagener Versuch und wird wiederholt.
4. Idempotent sein. Die Zustellung erfolgt At-least-once und ohne garantierte Reihenfolge, und Ihr Poller hat den Job möglicherweise bereits abgeschlossen. Deduplizieren Sie daher anhand von job_id.

Für das Polling, während der Entwicklung oder zum Datenabgleich, ist die Python-Version kurz:

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

Ein Job endet als completed mit result_urls oder als failed mit einem Grund in error und einer automatischen Erstattung; protokollieren Sie processing_ms, um die Latenz zu überwachen. Führen Sie alle ein bis zwei Minuten einen Abgleich für Jobs aus, die nach einigen Minuten immer noch auf processing stehen. Markieren Sie einen langsamen Job nicht als fehlgeschlagen, nur weil ein Timer abgelaufen ist: Er kann noch abgeschlossen werden und wurde bei der Erstellung bereits berechnet.

Schritt 3: Ergebnisse an Ihre Benutzer ausliefern

Ein abgeschlossener Job gibt result_urls zurück, ein Array gerenderter JPEG-Bilder. Verlinken Sie diese nicht direkt per Hotlink.

Hosten Sie die Ergebnisse neu. Roomagen liefert Ergebnisse aus eigenem Speicher aus, vorbehaltlich der Aufbewahrungsfristen des Kontos. Daher sollte ein Hintergrund-Job jedes Bild herunterladen, sobald der Job abgeschlossen ist, es in Ihr eigenes Bucket schreiben (S3, R2, GCS oder ähnlich) und über Ihr CDN ausliefern. Ihre Bilder hängen dann niemals von der Aufbewahrungsrichtlinie eines Anbieters ab.

Behalten Sie das Original neben der Ausgabe. Speichern Sie das Ausgangsfoto und das gestagte Bild als verknüpftes Paar. Dieses Paar treibt einen Vorher-Nachher-Schieberegler an, ermöglicht Benutzern das Zurücksetzen und entspricht den Offenlegungsregeln für Immobilienanzeigen (Schritt 4).

Planen Sie Abweichungen ein. Generative Ergebnisse variieren, und manchmal passt das Sofa nicht. Ein erneuter Durchlauf ist ein neuer Job, der ein weiteres Bild kostet, da Roomagen Render-Vorgänge erstattet, die fehlschlagen, nicht aber Ergebnisse, die einem Benutzer nicht gefallen. Geben Sie jedem erneuten Durchlauf einen eigenen Idempotency-Key, wie z. B. photo-4821-stage-2: Die Wiederverwendung des ersten Schlüssels gibt den ursprünglichen Job zurück oder einen 409-Fehler, falls der Body geändert wurde. Bieten Sie eine Schaltfläche „Erneut versuchen“ an und entscheiden Sie, ob diese Kosten für Benutzer sichtbar sind oder in Ihre Preisgestaltung einfließen.

Gestalten Sie Warte- und Fehlerzustände. Staging dauert normalerweise bis zu einer Minute, was in Bezug auf die Benutzeroberfläche eine lange Zeit ist. Gestalten Sie vor dem Launch den Fortschrittsstatus, den Fehlerstatus („Das Rendering ist fehlgeschlagen und wurde erstattet“) und die Wiederholungsaktion.

Schritt 4: Offenlegung in Ihr Datenmodell einbauen

Wenn Ihre Benutzer virtuell gestagte Fotos in Immobilienanzeigen verwenden, ist die Offenlegung ihre gesetzliche Pflicht, und Ihr Datenmodell entscheidet darüber, wie einfach dies ist. Die API von Roomagen fügt weder ein Offenlegungslabel noch eine Verknüpfung von Original und bearbeitetem Bild hinzu, und die Geschäftsbedingungen von Roomagen übertragen die Verantwortung für die Offenlegung dem Benutzer. Daher muss Ihre Integration diese Daten führen.

• Kalifornien AB 723, in Kraft seit dem 1. Januar 2026. Ein Broker oder Immobilienmakler (oder jemand, der in deren Auftrag handelt), der ein digital verändertes Bild in einer Anzeige für einen Immobilienverkauf verwendet, muss auf oder neben dem Bild angeben, dass es verändert wurde, und einen Link, eine URL oder einen QR-Code zu einer öffentlichen Website hinzufügen, die das originale, unveränderte Bild zeigt. Die kalifornische Immobilienaufsichtsbehörde stellt klar, dass, wenn ein KI-Werkzeug irreführende Werbung erzeugt, die Verantwortung „beim Lizenzinhaber und seinem verantwortlichen Broker liegt, nicht beim Technologieanbieter“.
• Mietanzeigen in Kalifornien ab 1. Januar 2027. AB 2025 weitet eine ähnliche Offenlegungspflicht auf Mietwerbung aus und deckt damit Wohnungsanbieter und andere ab, nicht nur Lizenzinhaber.
• MLS-Regeln weichen bei der Platzierung voneinander ab. Canopy MLS verlangt die Kennzeichnung auf dem Bild selbst, nicht nur in Bildunterschriften, während NWMLS keine Fotos mit überlagerten Grafiken oder Texten akzeptiert.
• Produkte für den EU-Markt. Seit dem 2. August 2026 verpflichtet Artikel 50 des EU AI Act Betreiber von KI-Systemen, die Deep-Fake-Bilder (Inhalte, die bestehenden Orten oder Gegenständen ähneln und fälschlicherweise als echt erscheinen würden) erzeugen oder manipulieren, dies offenzulegen – eine Definition, die KI-bearbeitete Fotos, die die Immobilie selbst darstellen, plausibel erfüllen können (siehe unseren Leitfaden zu Artikel 50 des EU AI Act).

Speichern Sie die Offenlegung daher als Daten, nicht als Pixel: eine öffentliche URL für das Originalfoto, ein altered-Flag mit dem verwendeten Werkzeug und den Optionen sowie einen Offenlegungstext und eine Kennzeichnungsplatzierung für jedes Ziel. Rendern Sie die Kennzeichnung erst beim Exportieren, nicht beim Speichern.

Dies ist eine Zusammenfassung für Entwickler, keine Rechtsberatung; unser AB-723-Leitfaden und der Leitfaden zu MLS-Fotoanforderungen behandeln das Thema ausführlicher.

Produktionsaspekte: Rate-Limits, Wiederholungen und Credit-Planung

Rate-Limits. Pro Schlüssel, in einem gleitenden 60-Sekunden-Fenster: 60 Anfragen pro Minute für POST /v1/jobs, 300 für GET /v1/jobs/{id} und 120 für GET /v1/tools und GET /v1/account, plus 600 pro Minute pro Client-IP, geteilt von allen Servern hinter einer NAT-Adresse. Erfolgreiche Antworten enthalten X-RateLimit-Limit und X-RateLimit-Remaining; ein 429 rate_limited enthält Retry-After in Sekunden – beachten Sie dies, anstatt ein eigenes Backoff-Verfahren zu erfinden. Bei Massenverarbeitungen reihen Sie Anfragen in eine Warteschlange ein: Bei 60 Jobs pro Minute dauert das Absenden von 500 Fotos etwas mehr als acht Minuten.

Wiederholungen und Fehlercodes. Jeder Fehler hat die Struktur { "error": { "code", "message", "doc_url" } }. Verzweigen Sie im Code anhand von code, niemals anhand von message:

Wirtschaftlichkeit von Fehlern. Ein Job, der während der Generierung fehlschlägt, wird automatisch erstattet, aber images_charged am Job wird nicht umgeschrieben. Betrachten Sie daher GET /v1/account als verlässliche Quelle für Ihren Kontostand. Prüfen Sie beim Vergleich von Anbietern die Erstattungsrichtlinien neben dem Preis.

Credit-Planung. Roomagen rechnet die API in Bildern ab, die im Voraus in Paketen über das Entwicklerportal erworben werden:

Pakete verfallen nie und lassen sich kombinieren. Jedes dokumentierte Werkzeug kostet ein Bild pro Rendering in 2K; resolution: "4K" verdoppelt dies bei Werkzeugen, die dies unterstützen, und Staging kostet immer ein Bild. Beziehen Sie Wiederholungen in Ihr Budget ein: Eine Plattform, die 1.200 Fotos pro Monat virtuell stagt und damit rechnet, dass jedes zehnte wiederholt werden muss, benötigt etwa 1.320 Bilder, sodass ein Growth-Paket fast zwei Monate lang reicht.

Veröffentlichte Preise variieren stark (geprüft im Oktober 2026): ModelsLab listet 0,02 $ pro Interieur-Rendering, Decor8 0,20 $ pro Bild für alle API-Operationen und AI HomeDesign 0,24 $ pro Foto bei jährlicher Abrechnung bzw. etwa 0,49 $ bei monatlicher Abrechnung. Vergleichen Sie den Funktionsumfang der Werkzeuge, Webhooks, Fehlerrichtlinien und Ausgabequalität ebenso wie den Stückpreis; unser Preisvergleich für Virtual-Staging-APIs und der Vergleich von Staging-APIs betrachten die Anbieter im Detail.

Ein ehrlicher Hinweis zum Reifegrad. Die API von Roomagen ist jung: Version 1 startete am 30. August 2026 mit einem einzigen Job-Endpunkt, und ihre Dokumentation deckt erst seit dem 3. Oktober 2026 jedes unterstützte Werkzeug ab. Sie nutzt daher moderne Konventionen, verfügt aber nicht über eine jahrelange öffentliche Historie. Breaking Changes werden Konten mit einem aktiven Schlüssel vor der Einführung per E-Mail angekündigt; abwärtskompatible Erweiterungen können jederzeit eingeführt werden, ignorieren Sie daher nicht erkannte Antwortfelder einfach.

Erweiterung der Integration: Weitere dokumentierte Werkzeuge

Sobald die Schleife für das Staging funktioniert, ändert eine Schaltfläche wie „Dämmerungsversion“ oder „Gegenstände entfernen“ lediglich tool und options:

Diese Werkzeuge akzeptieren auch resolution (2K oder 4K), tier (auto, guided oder custom) und customPrompt (bis zu 500 Zeichen). Im Gegensatz zum Staging ignorieren sie unbekannte Schlüssel und führen jeden davon in der warnings-Liste der Antwort auf, weisen jedoch Werte außerhalb der zulässigen Bereiche zurück. Senden Sie bei fensterlosen Räumen hasWindows: false an Tag zu Dämmerung Fotobearbeitung & Umwandlung, damit der Prompt Anweisungen zu Fenstern und Aussichten weglässt.

GET /v1/tools gibt jeden Slug zurück, den Ihr Schlüssel aufrufen kann, samt seinen Kosten in Bildern, und jeder zurückgegebene Slug ist dokumentiert. Lesen Sie die Liste aus, anstatt sie fest im Code zu hinterlegen, und beachten Sie, dass Werkzeugnamen auf roomagen.com keine API-Slugs sind.

Was die API nicht leistet

• Kein Batch-Endpunkt. Ein Job ist ein Bild durch ein Werkzeug; die Stapelverarbeitung der Web-App ist nicht Teil der API. Reihen Sie Jobs daher innerhalb der Rate-Limits in Warteschlangen ein.
• Keine Offenlegungsbeschriftungen. Ausgaben enthalten weder ein Offenlegungslabel noch Vorher-Nachher-Paare. Renderings sind mit einem Wasserzeichen versehen, bis das Konto ein Paket kauft, und tragen danach kein Roomagen-Branding mehr.
• Keine kostenlose Neugenerierung. Ein erneuter Durchlauf ist ein neuer Job und wird wie ein solcher berechnet.
• Keine Abmessungen oder CAD-Dateien. Ausgaben sind JPEG-Bilder, keine Maße, Vektoren oder DWG-Dateien. Wenn Sie Raummaße aus Fotos benötigen, ist eine generative Bild-API das falsche Werkzeug.
• Keine Ergebnisgarantie. Generative Modelle können Artefakte oder Ungenauigkeiten erzeugen. Überprüfen Sie die Ausgabe daher, bevor sie in ein Inserat gelangt.
• Keine Funktionen, die nur in der App verfügbar sind. Nachbessern, die Bibliothek und der Design-Begleiter-Chat existieren nur in der Web-App von Roomagen.

Häufige Fehler bei Staging-API-Integrationen

1. Den Request-Thread blockieren. Das Offenhalten einer Benutzeranfrage, während ein Job gerendert wird, führt zu Timeouts bei Load-Balancern. Geben Sie von Ihrer eigenen API 202 Accepted zurück und übermitteln Sie Updates per Push an den Client.
2. Falsche Optionsnamen. room_type oder resolution bei einem Staging-Job gibt invalid_request zurück; Staging erwartet camelCase-Schlüssel aus der eigenen Liste und immer style.
3. Ausschließlich auf Webhooks vertrauen. Nach etwa 36 Minuten voller Wiederholungsversuche bricht Roomagen die Versuche ab. Ohne einen Abgleich verharrt dieser Job für immer im Status „processing“.
4. Fehlerhafte Signaturüberprüfung. Das Hashen von geparstem JSON, das Weglassen des Zeitstempel-Präfixes, Vergleiche mit === oder das Überspringen der Aktualitätsprüfung schwächen die Verifizierung.
5. Eine Webhook-URL, die weiterleitet. Reines HTTP und private Hosts werden direkt mit webhook_url_rejected abgelehnt, und Weiterleitungen wird nicht gefolgt. Ein abschließender Schrägstrich oder eine www-Weiterleitung führt daher bei jeder Zustellung zu einem Fehler.
6. Zufällige Idempotency-Keys oder neu signierte URLs. Ein Schlüssel, den Sie nicht gespeichert haben, kann nicht wiederholt werden, sodass der Neuversuch erneut abgerechnet wird; eine neu signierte image_url unter demselben Schlüssel gibt 409 zurück.
7. Ergebnis-URLs per Hotlink einbinden. Die Ergebnisse unterliegen den Aufbewahrungsfristen des Anbieters. Hosten Sie diese nach Fertigstellung selbst.
8. Ein einziges Wasserzeichen für jeden Zielort. Eine fest eingebrannte Kennzeichnung wie „Virtually Staged“ („Virtuell gestagt“) kann gegen MLS-Regeln bezüglich überlagerter Texte verstoßen und erfüllt ohne einen Link zum Original für sich genommen nicht die Anforderungen von AB 723.

Checkliste vor dem Launch

• Der API-Schlüssel liegt ausschließlich auf Ihren Servern, einer pro Umgebung.
• Staging-Anfragen senden immer style und keine Optionen außerhalb der Staging-Optionsliste.
• Jeder Job hat einen Idempotency-Key, der aus Ihren Datensätzen abgeleitet ist, und Wiederholungen senden den ursprünglichen Body erneut.
• Der Webhook-Endpunkt ist die endgültige https-URL, verifiziert v1=-Signaturen über den Rohdaten-Body, weist veraltete Zeitstempel ab und antwortet innerhalb von 10 Sekunden.
• Eine job.test-Zustellung aus dem Portal besteht die Verifizierung.
• Ein Abgleichmechanismus prüft Jobs, die nach einigen Minuten immer noch in Bearbeitung sind.
• Die Ergebnisse werden neu gehostet, jeweils mit dem Original daneben.
• Offenlegungsdaten (Original-URL, Altered-Flag, zielabhängige Kennzeichnung) werden an jeden Exportpfad übergeben.
• Eine Benachrichtigung bei niedrigem Guthaben liest image_credits aus, und jeder Fehlercode ist einer klaren Nachricht für Ihre Benutzer zugeordnet.

Fazit: Die Schleife bereitstellen, dann erweitern

Das Hinzufügen von virtuellem Staging zu einer App ist eine überschaubare Integration: ein POST mit einem Idempotenz-Schlüssel, ein verifizierter Webhook-Handler mit Unterstützung durch einen Abgleich und ein Speicherschritt, der das Original neben dem Ergebnis aufbewahrt. Der Regelfall umfasst nur wenige Dutzend Zeilen; der Großteil der Arbeit entfällt auf die Absicherung für den Produktivbetrieb und die Offenlegungsdaten. Nichts davon ist an einen einzelnen Anbieter gebunden: Asynchrone Übermittlung, Fertigstellung per Push und Pull, neu gehostete Ergebnisse und ein Paar aus Original und Ausgabe passen zu jeder Staging-API.

Um die Umsetzung anhand dieses Beispiels zu starten, holen Sie sich einen Roomagen-API-Schlüssel: Der erste Schlüssel enthält 50 kostenlose Bilder, und der Quickstart, der Webhook-Leitfaden sowie die Fehler-Referenz behandeln die Details. Dieselbe Job-Schleife führt dann virtuelles Staging, Tag zu Dämmerung Fotobearbeitung & Umwandlung, Objekt- & Gegenstandsentfernung aus Fotos, Bildverbesserung, Virtuelle Renovierung & Umgestaltung und Grundriss zu 3D hinter einer einzigen Integration aus.