Stagify API

Introduzione

L’API espone una cosa sola: la pipeline di arredamento dietro l’app web. Invii la foto di una stanza, indichi un tipo di ambiente e uno stile di arredo e ricevi l’immagine arredata nella stessa risposta. Non c’è coda di lavori né nulla da interrogare sul percorso normale.

I crediti sono immagini intere. Li compri in anticipo e ogni render riuscito ne consuma uno. Un render fallito viene rimborsato automaticamente, quindi paghi solo per una foto che hai ricevuto. E poiché il saldo è prepagato, una chiave rubata ti costa al massimo quello che resta. Nessuna fattura a fine mese.

Le chiavi sono pensate per l’uso da server a server. L’API non invia header CORS, quindi un browser non può chiamarla direttamente; è voluto, e una chiave raggiungibile dal JavaScript del browser è una chiave compromessa. Mostriamo la chiave una sola volta, ne conserviamo solo un hash e la revochiamo subito.

Avvio rapido

Crea una chiave nella tua pagina delle chiavi API, acquista un pacchetto di crediti e invia una foto. La risposta contiene l’immagine arredata come 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"

Un render può richiedere un paio di minuti. Imposta il timeout di lettura del tuo client a 300 secondi e riprova con la stessa Idempotency-Key. È questo che garantisce che non ti venga mai addebitata due volte la stessa foto.

Pacchetti di crediti

Parametri della richiesta

POST /api/v1/renders, inviato come multipart/form-data. Tutti i valori accettati elencati sotto sono serviti anche in JSON da GET /api/v1/options, che non richiede una chiave API: un client può così popolare i propri menu a tendina invece di fissare questa tabella nel codice.

Idempotenza

Un render tiene aperta la connessione per minuti, quindi il guasto che ti colpirà davvero è un socket caduto dopo che il lavoro era già finito: addebitato e senza nulla in mano. Invia un header Idempotency-Key a ogni richiesta e riprova con lo stesso valore.

Omettere l’header è consentito e significa nessuna protezione dai replay, che è il comportamento predefinito più onesto. Non ricaviamo una chiave dalla tua foto: due render davvero distinti della stessa stanza collidereb­bero e il secondo chiamante riceverebbe l’immagine del primo.

Diciture di arredamento virtuale

Molte regole MLS e NAR richiedono che una foto arredata virtualmente lo dichiari. labelVirtuallyStaged imprime quella dicitura nei pixel invece di allegarla come metadato che uno strumento a valle può rimuovere.

Se la dicitura non può essere applicata, l’immagine viene trattenuta anziché consegnata senza etichetta, la chiamata risponde 500 DISCLOSURE_STAMP_FAILED e il tuo credito viene rimborsato. Non c’è modo di disattivare questo comportamento, né un valore predefinito per chiave che lo annulli in silenzio.

Errori

Ogni errore risponde { "error": "…", "code": "…" }. Ramifica su code, mai sul messaggio. I messaggi cambiano, i codici no.

Altri endpoint

• GET /api/v1/options: i valori accettati di ogni enumerazione qui sopra. Nessuna chiave API richiesta.
• GET /api/v1/me: la mia chiave funziona? Restituisce account e saldo.
• GET /api/v1/credits: saldo e totali complessivi.
• GET /api/v1/renders/{id}: lo stato di un render.

Ogni risposta porta X-Stagify-Credits-Remaining, così puoi vedere il saldo scendere senza interrogarlo.