Stagify API

Inleiding

De API stelt één ding beschikbaar: de stagingpijplijn achter de webapp. Je stuurt een foto van een kamer, geeft een kamertype en een meubelstijl op, en krijgt de ingerichte afbeelding in dezelfde reactie terug. Er is geen taakwachtrij en op het normale pad valt niets te pollen.

Credits zijn hele afbeeldingen. Je koopt ze vooraf en elke geslaagde render verbruikt er één. Een mislukte render wordt automatisch terugbetaald, dus je betaalt alleen voor een foto die je hebt ontvangen. En omdat het saldo vooraf betaald is, kost een gestolen sleutel je hooguit wat er nog op staat. Geen rekening aan het eind van de maand.

Sleutels zijn bedoeld voor server-naar-servergebruik. De API stuurt geen CORS-headers, dus een browser kan haar niet rechtstreeks aanroepen; dat is bewust, en een sleutel die bereikbaar is vanuit browser-JavaScript is een gelekte sleutel. We tonen een sleutel één keer, bewaren alleen een hash en trekken hem direct in.

Snel starten

Maak een sleutel aan op je API-sleutelpagina, koop een creditpakket en stuur een foto. De reactie bevat de ingerichte afbeelding 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"

Een render duurt tot een paar minuten. Zet de leestime-out van je client op 300 seconden en probeer opnieuw met dezelfde Idempotency-Key. Dat is wat garandeert dat je nooit twee keer voor één foto betaalt.

Creditpakketten

Aanvraagparameters

POST /api/v1/renders, verstuurd als multipart/form-data. Elke toegestane waarde hieronder wordt ook als JSON geleverd door GET /api/v1/options, waarvoor geen API-sleutel nodig is, zodat een client zijn eigen keuzelijsten kan vullen in plaats van deze tabel hard te coderen.

Idempotentie

Een render houdt de verbinding minutenlang open, wat betekent dat de storing die je echt raakt een afgebroken socket is nadat het werk al klaar was: betaald en met lege handen. Stuur bij elke aanvraag een Idempotency-Key-header en probeer opnieuw met dezelfde waarde.

De header weglaten mag en betekent geen replaybeveiliging, wat de eerlijke standaard is. We leiden geen sleutel af uit je foto: twee werkelijk losstaande renders van dezelfde kamer zouden botsen en de tweede aanroeper zou de afbeelding van de eerste krijgen.

Vermelding van virtuele styling

Veel MLS- en NAR-regels eisen dat een virtueel ingerichte foto dat vermeldt. labelVirtuallyStaged brandt die vermelding in de pixels in plaats van haar mee te sturen als metadata die een volgend hulpmiddel kan verwijderen.

Kan de vermelding niet worden aangebracht, dan wordt de afbeelding ingehouden in plaats van ongelabeld geleverd, antwoordt de aanroep 500 DISCLOSURE_STAMP_FAILED en wordt je credit terugbetaald. Dat gedrag is niet uit te schakelen, en er is geen standaard per sleutel die het stilletjes uitzet.

Fouten

Elke fout antwoordt met { "error": "…", "code": "…" }. Vertak op code, nooit op de melding. Meldingen veranderen, codes niet.

Overige endpoints

• GET /api/v1/options: de toegestane waarden van elke opsomming hierboven. Geen API-sleutel nodig.
• GET /api/v1/me: werkt mijn sleutel? Geeft account en saldo terug.
• GET /api/v1/credits: saldo en totalen.
• GET /api/v1/renders/{id}: de status van één render.

Elke reactie bevat X-Stagify-Credits-Remaining, zodat je het saldo ziet dalen zonder ernaar te vragen.