Ideal House
Saltar al contenido

Documentación de la API de visualización de planos#

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


📖 Descripción general#

La API de visualización de planos convierte una imagen de plano en una visualización con IA. Admite orientación por texto, tipo de plano, estilo visual, opciones de vista y modos de modelo.

El flujo de trabajo es asíncrono:

  1. Crear una tarea — Envía imageUrl y parámetros opcionales; recibirás un taskId.
  2. Consultar los resultados — Utiliza taskId para obtener el estado de la tarea y la imagen generada.

🔐 Autenticación#

EncabezadoValor
APIKEYyour_api_key_here

💰 Deducción de créditos#

[!WARNING] Los créditos se deducen cuando una tarea se crea correctamente. Si la tarea finalmente falla, los créditos deducidos se reembolsarán automáticamente.
Un saldo insuficiente devolverá el código de error 9051. Consulta la Referencia de deducción de créditos.

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

Si no se proporciona modelType, se utiliza Base de forma predeterminada.


🎨 Opciones de estilo#

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

Uso:

Texto plano
GET /api/v1/style/ai_plan_visualizer/getStyles
Grupo de estiloCampo de la solicitudDescripción
planTypeplanStyleIdOpción de tipo de plano
stylestyleIdOpción de estilo de visualización
viewviewIdOpción de cámara/vista

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


📌 Endpoints de la API#

1. Crear tarea de visualización de plano#

Endpoint

Texto plano
POST /api/v1/planVisualizer/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 del plano fuente
promptstring❌ OpcionalOrientación por texto para la visualización deseada
planStyleIdstring❌ OpcionalID del tipo de plano de las opciones de estilo planType
styleIdstring❌ OpcionalID del estilo de visualización de las opciones de estilo style
viewIdstring❌ OpcionalID de la vista de las opciones de estilo view
modelTypestring❌ OpcionalEnum: Base, Pro. Valor predeterminado: Base

Solo imageUrl es obligatorio. Todos los demás campos 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.

📥 Ejemplos de solicitud#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/planVisualizer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/floor-plan.jpg",
    "prompt": "bright modern residential visualization",
    "planStyleId": "AI plan visualizer_Plan type_Master plan",
    "styleId": "AI plan visualizer_Style_Marker pen",
    "viewId": "AI plan visualizer_View_Top-Down View",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class PlanVisualizerApiExample {

    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/floor-plan.jpg",
                    "prompt": "bright modern residential visualization",
                    "planStyleId": "AI plan visualizer_Plan type_Master plan",
                    "styleId": "AI plan visualizer_Style_Marker pen",
                    "viewId": "AI plan visualizer_View_Top-Down View",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/planVisualizer/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/floor-plan.jpg",
    "prompt": "bright modern residential visualization",
    "planStyleId": "AI plan visualizer_Plan type_Master plan",
    "styleId": "AI plan visualizer_Style_Marker pen",
    "viewId": "AI plan visualizer_View_Top-Down View",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/planVisualizer/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 createPlanVisualizerTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/planVisualizer/generate`,
      {
        imageUrl: 'https://example.com/floor-plan.jpg',
        prompt: 'bright modern residential visualization',
        planStyleId: 'AI plan visualizer_Plan type_Master plan',
        styleId: 'AI plan visualizer_Style_Marker pen',
        viewId: 'AI plan visualizer_View_Top-Down View',
        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);
  }
}

createPlanVisualizerTask();

📤 Respuesta#

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

2. Obtener resultado de la tarea#

Endpoint

Texto plano
GET /api/v1/planVisualizer/result

Encabezados de la solicitud

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

Parámetros de consulta

ParámetroTipoObligatorioDescripción
taskIdlong✅ Sí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/planVisualizer/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class PlanVisualizerResultExample {

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

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

pollPlanVisualizerResult(1234567890123456789n);

📤 Ejemplo de respuesta#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/floor-plan.jpg",
      "prompt": "bright modern residential visualization",
      "planStyleId": "AI plan visualizer_Plan type_Master plan",
      "styleId": "AI plan visualizer_Style_Marker pen",
      "viewId": "AI plan visualizer_View_Top-Down View",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/plan_visualizer_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/floor-plan.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/floor-plan.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 salida

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


❌ Respuestas de error#

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

Para las definiciones completas de errores comunes, consulta la Referencia de códigos de error.