Ideal House
Saltar al contenido

Documentación de la API de prueba virtual de muebles#

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


📖 Descripción general#

La API de prueba virtual de muebles te permite colocar virtualmente artículos de mobiliario en una escena de habitación utilizando IA. Proporcionas una imagen de la habitación y una lista de artículos de mobiliario (cada uno con una imagen y un ID de producto), y la IA compone perfectamente el mobiliario en la escena. El flujo de trabajo es asíncrono y consta de dos pasos:

  1. Crear una tarea: envía la imagen de tu habitación y la lista de mobiliario, luego recibe un taskId.
  2. Consultar los resultados — Utiliza el taskId para consultar el estado de la tarea y obtener la imagen generada.

📌 Nota: Actualmente, solo se admite el modo creative.


🔐 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] 🪙 Los créditos se descuentan según el modelType seleccionado tras la creación exitosa de la tarea. Si la tarea finalmente falla, los créditos descontados se reembolsarán automáticamente a tu cuenta.
Los créditos insuficientes devolverán el código de error 9051. 📄 Consulta la Referencia de Deducción de Créditos.

Modelo (modelType)Créditos Descontados
Base3 créditos
Pro10 créditos

📌 Endpoints de la API#


1. Crear tarea de Prueba de Mobiliario#

Crea una nueva tarea de prueba de mobiliario con IA y devuelve un taskId único para realizar sondeos.

Endpoint

Texto plano
POST /api/v1/furnitureTryOn/generate

Encabezados de la solicitud

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

Cuerpo de la solicitud

CampoTipoObligatorioDescripción
imageUrlstring✅ ObligatorioURL de la imagen de la escena de la habitación en la que se colocará el mobiliario
furnitureListarray✅ ObligatorioLista de artículos de mobiliario para colocar en la escena. Máximo 6 elementos. Ver Objeto de Artículo de Mobiliario
promptstring❌ OpcionalIndicación de texto personalizado para guiar adicionalmente la colocación y el estilo
modelTypestring❌ OpcionalTipo de calidad del modelo. Enumeración: Base, Pro. Valor predeterminado: Base

🛋️ Objeto de Artículo de Mobiliario#

Cada elemento en furnitureList debe ser un objeto con los siguientes campos:

CampoTipoObligatorioDescripción
imageUrlstring✅ ObligatorioURL de la imagen del producto de mobiliario (se recomienda fondo transparente o limpio)

⚠️ furnitureList puede contener como máximo 6 elementos.

🖼️ Requisitos de imagen: La imagen de la habitación y cada imagen de mobiliario deben usar JPG/JPEG, PNG o WebP. Cada imagen no debe superar 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 escalarán proporcionalmente para ajustarse a 6,000 × 6,000 px antes del procesamiento. Los URLs de imagen deben ser directamente accesibles por el servidor de la API.

Ejemplo

json
"furnitureList": [
  {
    "imageUrl": "https://example.com/sofa.png"
  },
  {
    "imageUrl": "https://example.com/table.png"
  }
]

Tipos de Modelo

ValorDescripción
BasePredeterminado. Equilibrio entre velocidad y calidad
ProSalida de mayor calidad, procesamiento más lento

📥 Ejemplos de solicitud#

cURL
bash
# Basic request (Base model)
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      },
      {
        "imageUrl": "https://example.com/coffee-table.png"
      }
    ],
    "prompt": "modern minimalist style"
  }'

# Pro model
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      }
    ],
    "prompt": "Scandinavian interior with warm lighting",
    "modelType": "Pro"
  }'
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;

public class FurnitureTryOnApiExample {

    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/living-room.jpg",
                "furnitureList": [
                    {
                        "imageUrl": "https://example.com/sofa.png"
                    },
                    {
                        "imageUrl": "https://example.com/coffee-table.png"
                    }
                ],
                "prompt": "modern minimalist style",
                "modelType": "Base"
            }
            """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/furnitureTryOn/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/living-room.jpg",
    "furnitureList": [
        {
            "imageUrl": "https://example.com/sofa.png"
        },
        {
            "imageUrl": "https://example.com/coffee-table.png"
        }
    ],
    "prompt": "modern minimalist style",
    "modelType": "Base"
}

# Pro model example:
# payload = {
#     "imageUrl": "https://example.com/living-room.jpg",
#     "furnitureList": [
#         {
#             "imageUrl": "https://example.com/sofa.png"
#         }
#     ],
#     "prompt": "Scandinavian interior with warm lighting",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/furnitureTryOn/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 createFurnitureTryOnTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/furnitureTryOn/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        furnitureList: [
          {
            imageUrl: 'https://example.com/sofa.png'
          },
          {
            imageUrl: 'https://example.com/coffee-table.png'
          }
        ],
        prompt: 'modern minimalist style',
        modelType: 'Base'

        // Pro model:
        // modelType: 'Pro'
      },
      {
        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);
  }
}

createFurnitureTryOnTask();

📤 Respuesta#

Respuesta de Éxito

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

2. Obtener resultado de la tarea#

Obtén el estado y la salida actual de una tarea de prueba de mobiliario creada previamente.

Endpoint

Texto plano
GET /api/v1/furnitureTryOn/result

Encabezados de la solicitud

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

Parámetros de consulta

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

📥 Ejemplos de solicitud#

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

public class FurnitureTryOnResultExample {

    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/furnitureTryOn/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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/furnitureTryOn/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)  # Poll every 3 seconds

if status == "Success":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Matched Items:", output.get("items", []))
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/furnitureTryOn/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('Matched Items:', result.output.items);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    // Wait 3 seconds before next poll
    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/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        },
        {
          "imageUrl": "https://example.com/coffee-table.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/furniture_try_on_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Respuesta (tarea en procesamiento / en cola)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": null
  }
}

Respuesta (tarea fallida)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "modelType": "Base"
    },
    "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 que se está procesando en este momento)
percentageintegerPorcentaje de finalización de la tarea (0–100)
inputobjectLos parámetros de entrada originales de la tarea
input.imageUrlstringURL de la imagen de la escena de la habitación
input.furnitureListarrayLista de artículos de mobiliario enviados (máx. 6 elementos)
input.furnitureList[].imageUrlstringURL de la imagen del producto de mobiliario
input.promptstringIndicación de texto personalizado (si se proporcionó)
input.modelTypestringTipo de modelo utilizado
outputobjectResultado de la generación (solo disponible cuando status es Success)
output.resultUrlstringURL a la imagen generada de la habitación con el mobiliario colocado
output.widthintegerAncho de salida en píxeles
output.heightintegerAlto de salida en píxeles

📊 Estado de la tarea#

EstadoDescripción
UnprocessedLa tarea se ha creado pero aún no se ha iniciado
ProcessingLa tarea se está procesando actualmente
SuccessLa tarea se completó correctamente; la salida está disponible
FailedLa tarea falló debido a un error

Consulta cada 3-5 segundos. Consulta 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
1001FAILEDError genérico en la solicitudComprueba el campo message para ver los detalles específicos del error
1003INTERNAL_ERRORError interno del servidorReintentar después de un breve retraso; contactar soporte si persiste
1011PARAM_ERRORError en los parámetros de la solicitud — falta por ejemplo, imageUrl o furnitureList, o furnitureList supera 6 elementosAsegúrate de que tanto imageUrl como furnitureList se proporcionen, que no estén vacíos y que contengan no más de 6 elementos
5002API_KEY_INVALIDClave API inválida o ausenteAsegúrate de que el encabezado APIKEY está presente y que el valor es correcto
9010SCAN_TEXT_ERROREl prompt de texto no pasó la revisión de contenidoModifica el prompt para eliminar cualquier contenido sensible o prohibido
9038PROHIBITED_CONTENTLa imagen de salida generada contiene contenido prohibidoAjusta la sugerencia/estilo/entradas y reintenta
9051COINS_NOT_ENOUGHMonedas / créditos insuficientesRecarga los créditos de tu cuenta y vuelve a intentarlo

📄 Para la lista completa de códigos de error comunes de la API, consulta la Referencia de códigos de error.