Documentación de la API de paisajismo#

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

📖 Descripción general#

La API de paisajismo mejora o rediseña áreas de paisaje exterior a partir de una imagen de origen. Admite guía textual opcional, opciones de estilo de jardín, elementos del paisaje y modos de modelo.

El flujo de trabajo es asíncrono:

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

🔐 Autenticación#

Encabezado	Valor
`APIKEY`	`your_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
`Flash`	1 crédito
`Base`	3 créditos
`Pro`	10 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/landscaping/getStyles

Grupo de estilo	Campo de la solicitud	Descripción
`gardenStyle`	`sceneId`	Opción de estilo de jardín o paisaje
`elements`	`sceneElementId`	Opción de elemento del paisaje. 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.

📌 Endpoints de la API#

1. Crear tarea de Paisajismo#

Endpoint

Texto plano

POST /api/v1/landscaping/generate

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`APIKEY`	✅ Sí	Tu clave de autenticación API
`Content-Type`	✅ Sí	`application/json`

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`imageUrl`	`string`	✅ Sí	URL de la imagen de paisaje de origen
`prompt`	`string`	❌ Opcional	Guía textual para el resultado deseado
`sceneId`	`string`	❌ Opcional	ID del estilo del jardín procedente de las opciones de estilo `gardenStyle`
`sceneElementId`	`string`	❌ Opcional	ID del elemento del paisaje procedente de las opciones de estilo `elements`. Permite varios IDs unidos por comas, por ejemplo `id1,id2`
`modelType`	`string`	❌ Opcional	Enum: `Flash`, `Base`, `Pro`. 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/landscaping/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
  }'

Java (OkHttp)

java

import okhttp3.*;

import java.io.IOException;

public class LandscapingApiExample {

    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/backyard.jpg",
                    "prompt": "lush modern garden with clean stone paths",
                    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
                    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/landscaping/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/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/landscaping/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 createLandscapingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/landscaping/generate`,
      {
        imageUrl: 'https://example.com/backyard.jpg',
        prompt: 'lush modern garden with clean stone paths',
        sceneId: 'Landscape Design_Landscape Style_Mid-Century Modern Pool',
        sceneElementId: 'Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover',
        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);
  }
}

createLandscapingTask();

📤 Respuesta#

json

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

2. Obtener resultado de la tarea#

Endpoint

Texto plano

GET /api/v1/landscaping/result

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`APIKEY`	✅ Sí	Tu clave de autenticación API

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`taskId`	`long`	✅ 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/landscaping/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

java

import okhttp3.*;

import java.io.IOException;

public class LandscapingResultExample {

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

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

pollLandscapingResult(1234567890123456789n);

📤 Ejemplo de respuesta#

json

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/backyard.jpg",
      "prompt": "lush modern garden with clean stone paths",
      "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
      "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/landscaping_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/backyard.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/backyard.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

📊 Estado de la tarea#

Estado	Descripción
`Unprocessed`	La tarea se ha creado y está esperando en la cola
`Processing`	La tarea se está ejecutando actualmente
`Success`	La tarea se completó correctamente
`Failed`	La tarea falló y no se produjo salida

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

❌ Respuestas de error#

Código	Nombre	Descripción
`1011`	`PARAM_ERROR`	Error en los parámetros de la solicitud
`5002`	`API_KEY_INVALID`	Clave API inválida o ausente
`9010`	`SCAN_TEXT_ERROR`	El prompt no pasó la revisión de contenido
`9038`	`PROHIBITED_CONTENT`	La imagen generada contiene contenido prohibido
`9051`	`COINS_NOT_ENOUGH`	Créditos insuficientes

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