Stagify API

Introduction

L’API expose une seule chose : le moteur de mise en scène derrière l’application web. Vous envoyez la photo d’une pièce, indiquez un type de pièce et un style de mobilier, et recevez l’image meublée dans la même réponse. Il n’y a pas de file d’attente ni rien à interroger sur le chemin normal.

Les crédits sont des images entières. Vous les achetez d’avance et chaque rendu réussi en consomme un. Un rendu qui échoue est remboursé automatiquement : vous ne payez que pour une photo que vous avez reçue. Et comme le solde est prépayé, une clé volée vous coûte au plus ce qu’il en reste. Aucune facture en fin de mois.

Les clés sont prévues pour un usage serveur à serveur. L’API n’envoie aucun en-tête CORS, donc un navigateur ne peut pas l’appeler directement ; c’est délibéré, et une clé accessible depuis du JavaScript de navigateur est une clé divulguée. Nous affichons une clé une seule fois, n’en stockons qu’un hachage et la révoquons immédiatement.

Démarrage rapide

Créez une clé sur votre page de clés d’API, achetez un pack de crédits, puis envoyez une photo. La réponse contient l’image meublée sous forme de 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 rendu peut prendre quelques minutes. Réglez le délai de lecture de votre client sur 300 secondes et réessayez avec la même Idempotency-Key. C’est ce qui garantit que vous n’êtes jamais facturé deux fois pour une photo.

Packs de crédits

Paramètres de la requête

POST /api/v1/renders, envoyé en multipart/form-data. Toutes les valeurs acceptées ci-dessous sont également servies en JSON par GET /api/v1/options, qui ne demande aucune clé d’API : un client peut donc remplir ses propres listes déroulantes au lieu de figer ce tableau dans son code.

Idempotence

Un rendu garde la connexion ouverte plusieurs minutes, ce qui veut dire que la panne qui vous touchera vraiment est un socket coupé après la fin du travail : facturé, les mains vides. Envoyez un en-tête Idempotency-Key à chaque requête et réessayez avec la même valeur.

Omettre l’en-tête est autorisé et signifie aucune protection contre les rejeux, ce qui est le comportement honnête par défaut. Nous ne dérivons pas de clé à partir de votre photo : deux rendus réellement distincts de la même pièce entreraient en collision et le second appelant recevrait l’image du premier.

Mentions de mise en scène

De nombreuses règles MLS et NAR exigent qu’une photo meublée virtuellement le signale. labelVirtuallyStaged grave cette mention dans les pixels plutôt que de l’attacher en métadonnée qu’un outil en aval peut retirer.

Si la mention ne peut pas être appliquée, l’image est retenue plutôt que livrée sans étiquette, l’appel répond 500 DISCLOSURE_STAMP_FAILED et votre crédit est remboursé. Ce comportement ne peut pas être désactivé, et aucune valeur par défaut par clé ne le neutralise en silence.

Erreurs

Chaque échec répond { "error": "…", "code": "…" }. Branchez sur code, jamais sur le message. Les messages changent, pas les codes.

Autres points de terminaison

• GET /api/v1/options : les valeurs acceptées de chaque énumération ci-dessus. Aucune clé d’API requise.
• GET /api/v1/me : ma clé fonctionne-t-elle ? Renvoie le compte et le solde.
• GET /api/v1/credits : solde et totaux cumulés.
• GET /api/v1/renders/{id} : l’état d’un rendu.

Chaque réponse porte X-Stagify-Credits-Remaining, ce qui vous permet de voir le solde baisser sans l’interroger.