Ideal House
Pular para o conteúdo

Documentação da API Landscaping#

URL Base: https://api.ideal.house
Versão: v1
Atualizado: 2026-05-21


📖 Visão Geral#

A API Landscaping melhora ou redesenha áreas de paisagismo externo a partir de uma imagem fonte. Ela suporta orientação textual opcional, opções de estilo de jardim, elementos de paisagismo e modos de modelo.

O fluxo de trabalho é assíncrono:

  1. Criar uma tarefa — Envie imageUrl e parâmetros opcionais, então receba um taskId.
  2. Consultar resultados — Use taskId para recuperar o status da tarefa e a imagem gerada.

🔐 Autenticação#

CabeçalhoValor
APIKEYyour_api_key_here

💰 Dedução de Créditos#

[!WARNING] Os créditos são deduzidos quando uma tarefa é criada com sucesso. Se a tarefa finalmente falhar, os créditos deduzidos serão automaticamente reembolsados.
Créditos insuficientes retornarão o código de erro 9051. Consulte Referência de Dedução de Créditos.

Modelo (modelType)Créditos Deduzidos
Flash1 crédito
Base3 créditos
Pro10 créditos

Se modelType não for fornecido, Base é usado por padrão.


🎨 Opções de Estilo#

Esta API suporta parâmetros de estilo opcionais retornados pelo endpoint de Configuração de Estilo da API.

Uso:

Texto simples
GET /api/v1/style/landscaping/getStyles
Grupo de EstiloCampo na RequisiçãoDescrição
gardenStylesceneIdOpção de estilo de jardim ou paisagismo
elementssceneElementIdOpção de elemento de paisagismo. Suporta múltiplos IDs de opção separados por vírgula, por exemplo id1,id2

Cada opção contém name, id e url. Passe o id da opção no campo correspondente da requisição.


📌 Endpoints da API#

1. Criar Tarefa Landscaping#

Endpointo

Texto simples
POST /api/v1/landscaping/generate

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação da API
Content-Type✅ Simapplication/json

Corpo da Requisição

CampoTipoObrigatórioDescrição
imageUrlstring✅ SimURL da imagem de paisagismo fonte
promptstring❌ OpcionalOrientação textual para o resultado desejado
sceneIdstring❌ OpcionalID do estilo de jardim das opções de estilo gardenStyle
sceneElementIdstring❌ OpcionalID do elemento de paisagismo das opções de estilo elements. Suporta múltiplos IDs separados por vírgula, por exemplo id1,id2
modelTypestring❌ OpcionalEnum: Flash, Base, Pro. Padrão: Base

Somente imageUrl é obrigatório. Todos os demais campos são opcionais.

🖼️ Requisitos de imagem: Todas as imagens fonte e de referência devem usar JPG/JPEG, PNG ou WebP. Cada imagem deve ter no máximo 20 MB, com dimensões de 128 × 128 px até 6,000 × 6,000 px (inclusivo). Imagens que excedam as dimensões máximas em pixels serão redimensionadas proporcionalmente automaticamente para caber dentro de 6,000 × 6,000 px antes do processamento. Os URLs das imagens devem ser acessíveis diretamente pelo servidor da API.

📥 Exemplos de Requisição#

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();

📤 Resposta#

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

2. Obter Resultado da Tarefa#

Endpointo

Texto simples
GET /api/v1/landscaping/result

Cabeçalhos da Requisição

CabeçalhoObrigatórioDescrição
APIKEY✅ SimSua chave de autenticação da API

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
taskIdlong✅ SimID da tarefa retornado pelo endpoint de criação

📥 Exemplos de Requisição#

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);

📤 Exemplo de Resposta#

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
    }
  }
}

Resposta (Tarefa em Processamento / Em Fila)

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
  }
}

Resposta (Tarefa Falhou)

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
  }
}

📊 Status da Tarefa#

StatusDescrição
UnprocessedA tarefa foi criada e está aguardando na fila
ProcessingA tarefa está atualmente em execução
SuccessTarefa concluída com sucesso
FailedTarefa falhou e nenhuma saída foi produzida

Consulte a cada 3-5 segundos. Consulte Limite de Tarefas da API.


❌ Respostas de Erro#

CódigoNomeDescrição
1011PARAM_ERRORErro nos parâmetros da requisição
5002API_KEY_INVALIDChave de API inválida ou ausente
9010SCAN_TEXT_ERRORO prompt falhou na análise de conteúdo
9038PROHIBITED_CONTENTA imagem gerada contém conteúdo proibido
9051COINS_NOT_ENOUGHCréditos insuficientes

Para definições completas de erros comuns, consulte Referência de Códigos de Erro.