Stagify API

Einführung

Die API stellt genau eine Sache bereit: die Staging-Pipeline hinter der Web-App. Sie senden ein Foto eines Raums, nennen einen Raumtyp und einen Möbelstil und erhalten das möblierte Bild in derselben Antwort. Es gibt keine Job-Warteschlange und auf dem normalen Weg nichts abzufragen.

Guthaben sind ganze Bilder. Sie kaufen sie im Voraus, und jedes erfolgreiche Rendering verbraucht eines. Ein fehlgeschlagenes Rendering wird automatisch erstattet, Sie zahlen also nur für ein Foto, das Sie erhalten haben. Und da das Guthaben vorausbezahlt ist, kostet ein gestohlener Schlüssel Sie höchstens das, was noch darauf ist. Keine Rechnung am Monatsende.

Schlüssel sind für die Server-zu-Server-Nutzung gedacht. Die API sendet keine CORS-Header, ein Browser kann sie also nicht direkt aufrufen; das ist Absicht, und ein aus Browser-JavaScript erreichbarer Schlüssel ist ein geleakter Schlüssel. Wir zeigen einen Schlüssel einmal, speichern nur einen Hash und widerrufen sofort.

Schnellstart

Erstellen Sie einen Schlüssel auf Ihrer API-Schlüssel-Seite, kaufen Sie ein Guthabenpaket und senden Sie ein Foto. Die Antwort enthält das möblierte Bild als Data-URL.

curl https://stagify.ai/api/v1/renders \
  -H "Authorization: Bearer $STAGIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@living-room.jpg" \
  -F "roomType=Living room" \
  -F "furnitureStyle=modern" \
  -F "labelVirtuallyStaged=true"

Ein Rendering dauert bis zu ein paar Minuten. Stellen Sie das Lese-Timeout Ihres Clients auf 300 Sekunden und wiederholen Sie mit demselben Idempotency-Key. Genau das garantiert, dass Ihnen ein Foto nie zweimal berechnet wird.

Guthabenpakete

Anfrageparameter

POST /api/v1/renders, gesendet als multipart/form-data. Alle unten aufgeführten zulässigen Werte werden auch als JSON von GET /api/v1/options ausgeliefert, das keinen API-Schlüssel benötigt, ein Client kann damit eigene Auswahllisten füllen, statt diese Tabelle fest zu verdrahten.

Idempotenz

Ein Rendering hält die Verbindung minutenlang offen. Der Fehler, der Sie wirklich trifft, ist deshalb ein abgebrochener Socket, nachdem die Arbeit fertig war: bezahlt und ohne Ergebnis. Senden Sie bei jeder Anfrage einen Idempotency-Key-Header und wiederholen Sie mit demselben Wert.

Den Header wegzulassen ist erlaubt und bedeutet keinen Wiederholungsschutz, das ist der ehrliche Standard. Wir leiten keinen Schlüssel aus Ihrem Foto ab: zwei wirklich getrennte Renderings desselben Raums würden kollidieren, und der zweite Aufrufer bekäme das Bild des ersten.

Kennzeichnungshinweise

Viele MLS- und NAR-Regeln verlangen, dass ein virtuell möbliertes Foto dies auch angibt. labelVirtuallyStaged brennt diesen Hinweis in die Pixel, statt ihn als Metadatum anzuhängen, das ein nachgelagertes Werkzeug entfernen kann.

Kann der Hinweis nicht angebracht werden, wird das Bild zurückgehalten statt unmarkiert ausgeliefert, der Aufruf antwortet 500 DISCLOSURE_STAMP_FAILED und Ihr Guthaben wird erstattet. Dieses Verhalten lässt sich nicht abschalten, und es gibt keinen Standard pro Schlüssel, der es still deaktiviert.

Fehler

Jeder Fehlschlag antwortet mit { "error": "…", "code": "…" }. Verzweigen Sie über code, nie über die Meldung. Meldungen ändern sich, Codes nicht.

Weitere Endpunkte

• GET /api/v1/options: die zulässigen Werte jeder Aufzählung oben. Kein API-Schlüssel nötig.
• GET /api/v1/me: funktioniert mein Schlüssel? Liefert Konto und Guthaben.
• GET /api/v1/credits: Guthaben und Gesamtsummen.
• GET /api/v1/renders/{id}: der Status eines Renderings.

Jede Antwort trägt X-Stagify-Credits-Remaining, sodass Sie das Guthaben sinken sehen, ohne es abzufragen.