Ideal House
Saltar al contenido

Documentación de la API de renovación exterior#

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


📖 Descripción general#

La API de renovación exterior te permite renovar o restylizar el exterior de un edificio a partir de una imagen de entrada. Proporcionas una imagen de origen y, opcionalmente, puedes añadir guía en texto, una imagen de referencia, el estilo del edificio o preferencias del entorno para orientar el resultado de la renovación.

El flujo de trabajo es asíncrono e implica dos pasos:

  1. Crear una tarea — Envía tu imagen del exterior y la guía opcional; recibirás un taskId.
  2. Consultar los resultados — Utiliza el taskId para consultar el estado de la tarea y obtener la imagen generada.

🔐 Autenticación#

Todas las solicitudes de la API deben autenticarse con una Clave API.

Incluye tu Clave API en el encabezado de la solicitud:

EncabezadoValor
APIKEYyour_api_key_here

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


💰 Deducción de créditos#

[!WARNING] 🪙 Se deduce 1 crédito tras crear la tarea correctamente. Si la tarea finalmente falla, el crédito deducido se reembolsará automáticamente a tu cuenta.
Un saldo insuficiente devolverá el código de error 9051. 📄 Consulta la Referencia de deducción de créditos.

OperaciónCréditos deducidos
Tarea de Renovación exterior1 crédito

Para las reglas detalladas sobre créditos, consulta la Referencia de deducción de créditos.


📌Endpoints de la API#


1. Crear tarea de Renovación exterior#

Crea una nueva tarea de renovación exterior y devuelve un taskId único para su consulta.

Endpoint

Texto plano
POST /api/v1/exteriorRenovator/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✅ SíURL de la imagen exterior de origen que se va a renovar
promptstring❌ OpcionalGuía textual opcional para el resultado de la renovación
referenceUrlstring❌ OpcionalImagen de referencia opcional URL para guiar el estilo visual
buildingStyleIdstring❌ OpcionalID opcional del estilo del edificio
environmentIdstring❌ OpcionalID opcional del estilo del entorno o escena. Permite varios IDs unidos por comas, por ejemplo id1,id2

⚠️ Solo imageUrl es obligatorio. Todos los demás campos del cuerpo de la solicitud son opcionales.

🖼️ Requisitos de imagen: Todas las imágenes de origen y de referencia deben estar en formato JPG/JPEG, PNG o WebP. Cada imagen no debe superar 20 MB, con dimensiones entre 128 × 128 px y 6,000 × 6,000 px (inclusive). Las imágenes que superen las dimensiones máximas en píxeles se reducirán proporcionalmente automáticamente para ajustarse a 6,000 × 6,000 px antes del procesamiento. Los URLs de las imágenes deben ser accesibles directamente por el servidor de la API.


🎨 Opciones de estilo#

buildingStyleId y environmentId se pueden seleccionar desde el endpoint Configuración de estilos de la API.

Uso:

Texto plano
GET /api/v1/style/exterior_renovator/getStyles
Grupo de estiloCampo de la solicitudDescripción
buildingStylebuildingStyleIdOpción de estilo del edificio
environmentenvironmentIdOpción de entorno o escena. Permite varios IDs de opción unidos por comas, por ejemplo id1,id2

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


📥 Ejemplos de solicitud#

cURL
bash
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg"
  }'

# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorApiExample {

    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/exterior.jpg",
                    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
                    "referenceUrl": "https://example.com/reference-house.jpg",
                    "buildingStyleId": "modern-farmhouse",
                    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}

response = requests.post(
    f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/exteriorRenovator/generate`,
      {
        imageUrl: 'https://example.com/exterior.jpg',
        prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
        referenceUrl: 'https://example.com/reference-house.jpg',
        buildingStyleId: 'modern-farmhouse',
        environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
      },
      {
        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);
  }
}

createExteriorRenovatorTask();

📤 Respuesta#

Respuesta correcta

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#

Obtiene el estado actual y la salida de una tarea de renovación exterior creada previamente.

Endpoint

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

import java.io.IOException;

public class ExteriorRenovatorResultExample {

    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/exteriorRenovator/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/exteriorRenovator/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 failed")
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/exteriorRenovator/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 failed');
      }
      break;
    }

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

pollResult(1234567890123456789);

📤 Respuesta#

Respuesta correcta (tarea completada)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg",
      "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
      "refImageUrl": "https://example.com/reference-house.jpg",
      "buildingStyleId": "modern-farmhouse",
      "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/exterior_renovator_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": 50,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg"
    },
    "output": null
  }
}

Respuesta (tarea fallida)

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

Campos de la respuesta

CampoTipoDescripción
idlongIdentificador único de la tarea
statusstringEstado actual de la tarea (consulta Estado de la 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 exterior de origen
input.promptstringGuía textual opcional, si se proporcionó
input.refImageUrlstringImagen de referencia opcional URL, si se proporcionó
input.buildingStyleIdstringID opcional del estilo del edificio, si se proporcionó
input.environmentIdstringID opcional del estilo del entorno o escena, si se proporcionó. Puede contener varios IDs unidos por comas
outputobjectResultado de la generación (solo disponible cuando status es Success)
output.resultUrlstringURL a la imagen de resultado de la renovación exterior
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 servidorInténtalo de nuevo tras un breve retraso; contacta con soporte si persiste
1011PARAM_ERRORError en los parámetros de la solicitudAsegúrate de que los parámetros de la solicitud están formateados correctamente
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 el prompt/estilo/entradas y reintenta
9051COINS_NOT_ENOUGHMonedas/créditos insuficientesRecarga los créditos de tu cuenta y reintenta. Consulta la Referencia de deducción de créditos

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