Ideal House
Saltar al contenido

Documentación de la API de cambio de muebles#

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


📖 Descripción general#

La API de cambio de muebles rediseña o cambia los muebles en una imagen de interior. Envíe una imagen de origen y una orientación de estilo opcional, luego consulte el resultado de la tarea de forma asincrónica.

  1. Crear una tarea: envíe imageUrl y orientación opcional, luego reciba un taskId.
  2. Consultar resultados: utilice taskId para consultar el estado de la tarea y la imagen de salida.

🔐 Autenticación#

Todas las solicitudes de la API deben incluir una clave API en la cabecera de la solicitud.

CabeceraValor
APIKEYyour_api_key_here

💰 Deducción de créditos#

[!WARNING] 🪙 Se descuenta 1 crédito cuando se crea una tarea correctamente. 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. Consulte Referencia de deducción de créditos.

OperaciónCréditos descontados
Tarea de cambio de muebles1 crédito

🎨 Opciones de estilo#

Esta API admite parámetros de estilo opcionales devueltos por el endpoint Configuración de estilo de la API.

Uso:

Texto plano
GET /api/v1/style/change_furniture/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:

CampoDescripción
nameNombre de la opción multilingüe
idValor que se pasará en el campo de solicitud
urlImagen de vista previa de la opción

📌 Endpoints de la API#

1. Crear tarea de cambio de muebles#

Endpoint

Texto plano
POST /api/v1/changeFurniture/generate

Cabeceras de solicitud

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

Cuerpo de la solicitud

CampoTipoRequeridoDescripción
imageUrlstring✅ SíURL de la imagen de interior original
promptstring❌ OpcionalOrientación de texto para el resultado deseado
indoorTypeIdstring❌ OpcionalID de tipo de habitación de las opciones de estilo roomType
indoorStyleIdstring❌ OpcionalID de estilo de interior de las opciones de estilo style
indoorElemIdstring❌ OpcionalID de elemento de habitación de las opciones de estilo elements. Admite varios IDs separados por comas, por ejemplo id1,id2

Solo se requiere imageUrl. Todos los demás campos son opcionales.

🖼️ 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.

📥 Ejemplos de solicitud#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/changeFurniture/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "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 ChangeFurnitureApiExample {

    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",
                    "prompt": "replace the sofa with a modern warm neutral sofa",
                    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
                    "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/changeFurniture/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",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/changeFurniture/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 createChangeFurnitureTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/changeFurniture/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        prompt: 'replace the sofa with a modern warm neutral sofa',
        indoorTypeId: 'Interior Design_Interior Scene_Living Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Modern Country',
        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);
  }
}

createChangeFurnitureTask();

📤 Respuesta#

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

2. Obtener resultado de la tarea#

Endpoint

Texto plano
GET /api/v1/changeFurniture/result

Cabeceras de solicitud

CabeceraRequeridoDescripción
APIKEY✅ SíSu clave de autenticación de API

Parámetros de consulta

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

📥 Ejemplos de solicitud#

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

import java.io.IOException;

public class ChangeFurnitureResultExample {

    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/changeFurniture/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/changeFurniture/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":
    print("Result URL:", result["output"]["resultUrl"])
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 pollChangeFurnitureResult(taskId) {
  const headers = { APIKEY: API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/changeFurniture/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));
  }
}

pollChangeFurnitureResult(1234567890123456789n);

📤 Ejemplo de respuesta#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/change_furniture_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": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa"
    },
    "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"
    },
    "output": null
  }
}

📊 Estado de la tarea#

EstadoDescripción
UnprocessedLa tarea se ha creado y está esperando en la cola
ProcessingLa tarea se está ejecutando actualmente
SuccessLa tarea se completó correctamente
FailedLa tarea falló y no se produjo ningún resultado

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


❌ Respuestas de error#

CódigoNombreDescripción
1011PARAM_ERRORError en los parámetros de la solicitud
5002API_KEY_INVALIDAPI Key inválida o faltante
9010SCAN_TEXT_ERROREl prompt no superó la revisión de contenido
9038PROHIBITED_CONTENTLa imagen generada contiene contenido prohibido
9051COINS_NOT_ENOUGHCréditos insuficientes

Para definiciones completas de errores comunes, consulte Referencia de códigos de error.