Ideal House
Saltar al contenido

Documentación de la API de ambientación virtual#

URL base: https://api.ideal.house
Versión: v1
Actualizado: 2026-04-13


📖 Descripción general#

La API de ambientación virtual te permite rediseñar una habitación vacía o parcialmente amueblada utilizando inteligencia artificial.
Envías la imagen de una habitación URL y un texto opcional, y luego obtienes el resultado generado de forma asincrónica.

  1. Crear una tarea — Envía imageUrl y, opcionalmente, prompt, luego recibe un taskId.
  2. Consultar resultados — Usa taskId para consultar el estado de la tarea y obtener la imagen de salida.

🔐 Autenticación#

Todas las solicitudes a la API deben autenticarse mediante una Clave de API.

Incluye tu Clave de API en el encabezado de la solicitud:

EncabezadoValor
APIKEYyour_api_key_here

⚠️ Mantén tu Clave de API segura. No la expongas en código del lado del cliente ni en repositorios públicos.


💰 Deducción de créditos#

[!WARNING] 🪙 Se descuenta 1 crédito cuando se crea una tarea exitosamente.
Si la tarea finalmente falla, el crédito descontado se reembolsará automáticamente.
Los créditos insuficientes devolverán el código de error 9051. 📄 Consulta la Referencia de Deducción de Créditos.

OperaciónCréditos Descontados
Tarea de Ambientación Virtual1 crédito

📌 Endpoints de la API#


1. Crear Tarea de Ambientación Virtual#

Crea una nueva tarea de ambientación virtual y devuelve un taskId único para consultas.

Endpoint

Texto plano
POST /api/v1/virtualStaging/generate

Cabeceras de solicitud

EncabezadoRequeridoDescripción
APIKEY✅ SíTu clave de autenticación de API
Content-Type✅ Síapplication/json

Cuerpo de la solicitud

CampoTipoRequeridoDescripción
imageUrlstring✅ SíURL de la imagen de la habitación de origen
promptstring❌ NoSugerencia opcional para guiar el estilo y el amueblamiento
indoorTypeIdstring❌ NoPreset opcional de tipo de habitación. Consulta Opciones de tipo de habitación
indoorStyleIdstring❌ NoPreset opcional de estilo interior. Consulta Opciones de estilo interior
indoorElemIdstring❌ NoPreset opcional de elemento de habitación. Soporta múltiples IDs unidos por comas, por ejemplo id1,id2

🖼️ Requisitos de imagen: Use JPG/JPEG, PNG o WebP. Cada imagen no debe superar los 20 MB, con dimensiones desde 128 × 128 px hasta 6,000 × 6,000 px (inclusive). Las imágenes que excedan las dimensiones máximas en píxeles se reducirán automáticamente de forma proporcional para ajustarse a 6,000 × 6,000 px antes del procesamiento. La imagen URL debe ser accesible directamente por el servidor API.


🎨 Opciones de estilo#

indoorTypeId, indoorStyleId e indoorElemId se pueden seleccionar desde el endpoint Configuración de Estilos de la API.

Uso:

Texto plano
GET /api/v1/style/virtual_staging/getStyles
Grupo de estilosCampo de solicitudDescripción
roomTypeindoorTypeIdOpción de tipo de habitación
styleindoorStyleIdOpción de estilo de interior
elementsindoorElemIdOpción de elemento de habitación. Admite varios ID de opción separados por comas, por ejemplo id1,id2

Cada opción contiene name, id y url. Pase el id de la opción en el campo de solicitud correspondiente.


📥 Ejemplos de solicitud#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/empty-living-room.jpg",
    "prompt": "Warm and modern living room styling",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingApiExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        String requestBody = """
                {
                    "imageUrl": "https://example.com/empty-bedroom.jpg",
                    "prompt": "Cozy contemporary bedroom",
                    "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
                    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/generate")
                .addHeader("APIKEY", API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}
Python (requests)
python
import requests

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "imageUrl": "https://example.com/empty-home-office.jpg",
    "prompt": "Minimal modern home office",
    "indoorTypeId": "Interior Design_Interior Scene_Home Office",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/virtualStaging/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")
Node.js (axios)
javascript
const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createVirtualStagingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/virtualStaging/generate`,
      {
        imageUrl: 'https://example.com/empty-dining-room.jpg',
        prompt: 'Modern luxury dining room',
        indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
        indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
      },
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const taskId = response.data.data;
    console.log('Task ID:', taskId);
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createVirtualStagingTask();

📤 Respuesta#

Respuesta de Éxito

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
CampoTipoDescripción
codeinteger0 indica éxito
messagestringMensaje de respuesta
datalongEl ID único de la tarea para consultar resultados

2. Obtener resultado de la tarea#

Obtiene el estado actual y la salida de una tarea de ambientación virtual creada previamente.

Endpoint

Texto plano
GET /api/v1/virtualStaging/result

Cabeceras de solicitud

EncabezadoRequeridoDescripción
APIKEY✅ SíTu clave de autenticación de API

Parámetros de consulta

ParámetroTipoRequeridoDescription
taskIdlong✅ SíEl ID de tarea devuelto por el endpoint de creación de tareas

📥 Ejemplos de solicitud#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/virtualStaging/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingResultExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/result?taskId=" + taskId)
                .addHeader("APIKEY", API_KEY)
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}
Python (requests)
python
import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/virtualStaging/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(3)

if status == "Success":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Size:", output["width"], "x", output["height"])
else:
    print("Task ended with status:", status)
Node.js (axios)
javascript
const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/virtualStaging/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Result URL:', result.output.resultUrl);
        console.log('Size:', result.output.width, 'x', result.output.height);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Respuesta#

Respuesta de Éxito (Tarea Completada)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "modern country living room with warm neutral materials",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/virtual_staging_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Respuesta (tarea en proceso / en cola)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 46,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "coastal bedroom with soft light and natural textures",
      "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
    },
    "output": null
  }
}

Respuesta (tarea fallida)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "..."
    },
    "output": null
  }
}

Campos de Respuesta

CampoTipoDescripción
idlongIdentificador único de la tarea
statusstringEstado actual de la tarea (ver Estado de Tarea)
waitNumberintegerNúmero de tareas por delante de la tarea actual en la cola (0 significa procesamiento en curso)
percentageintegerPorcentaje de finalización de la tarea (0-100)
errorReasonstringMotivo del fallo cuando status es Failed
inputobjectParámetros de entrada originales enviados para esta tarea
input.imageUrlstringImagen de habitación de origen URL
input.promptstringSugerencia del usuario (si se proporcionó)
input.indoorTypeIdstringPreset de tipo de habitación utilizado (si se proporcionó)
input.indoorStyleIdstringPreset de estilo interior utilizado (si se proporcionó)
input.indoorElemIdstringPreset de elemento de habitación utilizado (si se proporcionó). Puede contener múltiples IDs unidos por comas
outputobjectResultado de la generación (disponible solo cuando status es Success)
output.resultUrlstringURL de la imagen de resultado de ambientación virtual generada
output.widthintegerAncho de la imagen de salida en píxeles
output.heightintegerAlto de la imagen de salida en píxeles

📊 Estado de la tarea#

EstadoSignificado
UnprocessedLa tarea ha sido creada y está esperando en la cola
ProcessingLa tarea se está ejecutando actualmente
SuccessLa tarea se completó exitosamente
FailedLa tarea falló y no se produjo ninguna salida

Consulte cada 3-5 segundos. Consulte Límite de tareas de la API.


❌ Respuestas de error#

Todas las respuestas de error comparten la misma estructura JSON:

json
{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Referencia de Códigos de Error#

CódigoNombreDescripciónAcción Sugerida
1001FAILEDFallo en la solicitud (error genérico)Verifica el campo message para detalles específicos
1003INTERNAL_ERRORError interno del servidorReintentar después de un breve retraso; contactar soporte si persiste
1011PARAM_ERRORError en los parámetros de la solicitud (por ejemplo, falta imageUrl)Asegúrate de que imageUrl esté proporcionado y sea un URL válido
5002API_KEY_INVALIDClave de API inválida o faltanteAsegúrate de que el encabezado APIKEY esté presente y sea correcto
9010SCAN_TEXT_ERRORLa sugerencia falló la moderación de contenidoRevisa la sugerencia para eliminar contenido sensible o prohibido
9038PROHIBITED_CONTENTLa imagen de salida generada contiene contenido prohibidoAjusta la sugerencia/estilo/entradas y reintenta
9051COINS_NOT_ENOUGHCréditos insuficientesRecarga créditos y reintenta

📄 Para definiciones completas de errores comunes, consulta la Referencia de Códigos de Error.