Stagify API

Introducción

La API expone una sola cosa: el motor de escenificación que hay detrás de la aplicación web. Envías la foto de una habitación, indicas un tipo de estancia y un estilo de mobiliario, y recibes la imagen escenificada en la misma respuesta. No hay cola de trabajos ni nada que consultar en el camino normal.

Los créditos son imágenes enteras. Los compras por adelantado y cada renderizado correcto gasta uno. Un renderizado fallido se reembolsa automáticamente, así que solo pagas por una foto que has recibido. Y como el saldo es prepago, una clave robada te cuesta como mucho lo que quede en ella. No hay factura a fin de mes.

Las claves están pensadas para uso servidor a servidor. La API no envía cabeceras CORS, por lo que un navegador no puede llamarla directamente; es deliberado, y una clave accesible desde JavaScript de navegador es una clave filtrada. Mostramos la clave una sola vez, guardamos únicamente un hash y la revocamos de inmediato.

Inicio rápido

Crea una clave en tu página de claves de API, compra un paquete de créditos y envía una foto. La respuesta lleva la imagen escenificada como 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 renderizado puede tardar un par de minutos. Ajusta el tiempo de espera de lectura de tu cliente a 300 segundos y reintenta con la misma Idempotency-Key. Eso es lo que garantiza que nunca se te cobre dos veces por una foto.

Paquetes de créditos

Parámetros de la petición

POST /api/v1/renders, enviado como multipart/form-data. Todos los valores admitidos que aparecen abajo también se sirven en JSON desde GET /api/v1/options, que no requiere clave de API, para que un cliente pueda rellenar sus propios desplegables en lugar de fijar esta tabla en el código.

Idempotencia

Un renderizado mantiene la conexión abierta durante minutos, lo que significa que el fallo que de verdad te afectará es un socket caído después de que el trabajo se completó: cobrado y sin nada en la mano. Envía una cabecera Idempotency-Key en cada petición y reintenta con el mismo valor.

Omitir la cabecera está permitido y significa que no hay protección frente a reintentos, que es el comportamiento honesto por defecto. No derivamos una clave a partir de tu foto: dos renderizados realmente distintos de la misma habitación colisionarían y quien llamase en segundo lugar recibiría la imagen del primero.

Avisos de escenificación

Muchas normas de MLS y NAR exigen que una foto escenificada lo indique. labelVirtuallyStaged graba ese aviso en los píxeles en lugar de añadirlo como metadatos que una herramienta posterior pueda eliminar.

Si el aviso no se puede aplicar, la imagen se retiene en vez de entregarse sin etiquetar, la llamada responde 500 DISCLOSURE_STAMP_FAILED y tu crédito se reembolsa. No hay forma de desactivar ese comportamiento, ni un valor por defecto por clave que lo anule sin avisar.

Errores

Todo fallo responde { "error": "…", "code": "…" }. Ramífica según code, nunca según el mensaje. Los mensajes cambian; los códigos no.

Otros endpoints

• GET /api/v1/options: los valores admitidos de cada enumeración anterior. No requiere clave de API.
• GET /api/v1/me: ¿funciona mi clave? Devuelve la cuenta y el saldo.
• GET /api/v1/credits: saldo y totales acumulados.
• GET /api/v1/renders/{id}: el estado de un renderizado.

Cada respuesta lleva X-Stagify-Credits-Remaining, para que puedas ver bajar el saldo sin tener que consultarlo.