Stagify API

Introduction

The API exposes one thing: the staging pipeline behind the web app. You post a photo of a room, name a room type and a furniture style, and get a staged image back in the same response. There is no job queue and nothing to poll on the happy path.

Credits are whole images. You buy them up front and each successful render spends one. A render that fails is refunded automatically, so you only ever pay for a photo you received. And because the balance is prepaid, a stolen key costs you at most what is left on it. There is no invoice at the end of the month.

Keys are meant for server-to-server use. The API sends no CORS headers, so a browser cannot call it directly; that is deliberate, and a key reachable from browser JavaScript is a leaked key. We show a key once, store only a hash, and revoke immediately.

Quickstart

Create a key on your API keys page, buy a credit pack, then post a photo. The response carries the staged image as a 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"

A render takes up to a couple of minutes. Set your client’s read timeout to 300 seconds and retry with the same Idempotency-Key. That is what guarantees you are never charged twice for one photo.

Credit packs

Request parameters

POST /api/v1/renders, sent as multipart/form-data. Every accepted value below is also served as JSON from GET /api/v1/options, which needs no API key, so a client can populate its own dropdowns instead of hard-coding this table.

Idempotency

A render holds the connection for minutes, which means the failure that will actually bite you is a dead socket after the work completed: charged, holding nothing. Send an Idempotency-Key header on every request and retry with the same value.

Omitting the header is allowed and means no replay protection, which is the honest default. We do not derive a key from your photo: two genuinely separate renders of the same room would collide and the second caller would be handed the first one’s image.

Disclosure labels

Many MLS and NAR rules require a staged photo to say that it is staged. labelVirtuallyStaged burns that label into the pixels rather than attaching it as metadata that a downstream tool can strip.

If the label cannot be applied, the image is withheld rather than delivered unlabelled, the call answers 500 DISCLOSURE_STAMP_FAILED, and your credit is refunded. There is no way to switch that behaviour off, and no per-key default that quietly disables it.

Errors

Every failure answers { "error": "…", "code": "…" }. Branch on code, never on the message. Messages change, codes do not.

Other endpoints

• GET /api/v1/options: the accepted values for every enum above. No API key required.
• GET /api/v1/me: is my key working? Returns the account and balance.
• GET /api/v1/credits: balance and lifetime totals.
• GET /api/v1/renders/{id}: the status of one render.

Every response carries X-Stagify-Credits-Remaining, so you can watch the balance fall without polling for it.