Ideal House
Saltar al contenido

Documentación de la API de decoración del hogar#

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


📖 Descripción general#

La API de decoración del hogar genera ideas de decoración para una imagen de interiores. Admite guía de texto opcional, una imagen de referencia, selecciones de estilo y modos de modelo.

El flujo de trabajo es asincrónico:

  1. Crear una tarea: envíe imageUrl y parámetros opcionales, luego reciba un taskId.
  2. Consultar resultados: utilice taskId para obtener el estado de la tarea y la imagen generada.

🔐 Autenticación#

CabeceraValor
APIKEYyour_api_key_here

💰 Deducción de créditos#

[!WARNING] Los créditos se descuentan cuando se crea una tarea exitosamente. Si la tarea finalmente falla, los créditos descontados se reembolsarán automáticamente.
Los créditos insuficientes devolverán el código de error 9051. Consulte Referencia de deducción de créditos.

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

Si modelType no se proporciona, se utiliza Base por defecto.


🎨 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/home_decor_ideas/getStyles
Grupo de estilosCampo de solicitudDescripción
spaceTypespaceStyleIdOpción de espacio o tipo de habitación
decorStylehomeDecorStyleIdOpción de estilo de decoración

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


📌 Endpoints de la API#

1. Crear Tarea de Decoración para el Hogar#

Endpoint

Texto plano
POST /api/v1/homeDecor/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
referenceUrlstring❌ OpcionalImagen de referencia URL para guiar el estilo de decoración
spaceStyleIdstring❌ OpcionalID de tipo de espacio de las opciones de estilo spaceType
homeDecorStyleIdstring❌ OpcionalID de estilo de decoración de las opciones de estilo decorStyle
promptstring❌ OpcionalOrientación de texto para el resultado deseado
modelTypestring❌ OpcionalEnum: Base, Pro. El valor predeterminado es Base

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

🖼️ Requisitos de imagen: Todas las imágenes de origen y referencia deben usar 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 proporcionalmente automáticamente para ajustarse a 6,000 × 6,000 px antes del procesamiento. Las URLs de las imágenes deben ser accesibles directamente por el servidor de la API.

📥 Ejemplos de solicitud#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/homeDecor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class HomeDecorApiExample {

    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/room.jpg",
                    "referenceUrl": "https://example.com/reference.jpg",
                    "spaceStyleId": "Indoor_Living Room",
                    "homeDecorStyleId": "Holidays_Cozy Christmas",
                    "prompt": "warm seasonal decor with natural textures",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/homeDecor/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/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/homeDecor/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 createHomeDecorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/homeDecor/generate`,
      {
        imageUrl: 'https://example.com/room.jpg',
        referenceUrl: 'https://example.com/reference.jpg',
        spaceStyleId: 'Indoor_Living Room',
        homeDecorStyleId: 'Holidays_Cozy Christmas',
        prompt: 'warm seasonal decor with natural textures',
        modelType: 'Base'
      },
      {
        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);
  }
}

createHomeDecorTask();

📤 Respuesta#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

2. Obtener resultado de la tarea#

Endpoint

Texto plano
GET /api/v1/homeDecor/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/homeDecor/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class HomeDecorResultExample {

    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/homeDecor/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/homeDecor/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 pollHomeDecorResult(taskId) {
  const headers = { APIKEY: API_KEY };

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

pollHomeDecorResult(1234567890123456789n);

📤 Ejemplo de respuesta#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "refImageUrl": "https://example.com/reference.jpg",
      "spaceStyleId": "Indoor_Living Room",
      "homeDecorStyleId": "Holidays_Cozy Christmas",
      "prompt": "warm seasonal decor with natural textures",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/home_decor_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/room.jpg",
      "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/room.jpg",
      "modelType": "Base"
    },
    "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.