Ideal House
Passa al contenuto

Documentazione API di progettazione del paesaggio#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-05-21


📖 Panoramica#

API di progettazione del paesaggio migliora o riprogetta aree paesaggistiche esterne a partire da un'immagine originale. Supporta indicazioni testuali facoltative, opzioni di stile del giardino, elementi paesaggistici e modalità del modello.

Il flusso di lavoro è asincrono:

  1. Crea un'attività — Invia imageUrl e i parametri facoltativi, quindi ricevi un taskId.
  2. Interroga periodicamente i risultati — Usa taskId per recuperare lo stato dell'attività e l'immagine generata.

🔐 Autenticazione#

IntestazioneValore
APIKEYyour_api_key_here

💰 Detrazione dei crediti#

[!WARNING] I crediti vengono detratti quando un'attività viene creata correttamente. Se alla fine l'attività non riesce, i crediti detratti vengono rimborsati automaticamente.
Un saldo di crediti insufficiente restituisce il codice di errore 9051. Consulta il Riferimento delle detrazioni dei crediti.

Modello (modelType)Crediti detratti
Flash1 credito
Base3 crediti
Pro10 crediti

Se modelType non viene fornito, viene usato Base per impostazione predefinita.


🎨 Opzioni di stile#

Questa API supporta parametri di stile facoltativi restituiti dall'endpoint Configurazione degli stili API.

Usa:

Testo semplice
GET /api/v1/style/landscaping/getStyles
Gruppo di stileCampo della richiestaDescrizione
gardenStylesceneIdOpzione dello stile del giardino o del paesaggio
elementssceneElementIdOpzione degli elementi paesaggistici. Supporta più identificatori di opzione uniti da virgole, ad esempio id1,id2

Ogni opzione contiene name, id e url. Passa l'id dell'opzione nel campo corrispondente della richiesta.


📌 Endpoint API#

1. Crea un'attività di progettazione del paesaggio#

Endpoint

Testo semplice
POST /api/v1/landscaping/generate

Intestazioni della richiesta

IntestazioneObbligatoriaDescrizione
APIKEY✅ SìLa tua chiave di autenticazione API
Content-Type✅ Sìapplication/json

Corpo della richiesta

CampoTipoObbligatorioDescrizione
imageUrlstring✅ SìURL dell'immagine originale del paesaggio
promptstring❌ FacoltativoIndicazioni testuali per il risultato desiderato
sceneIdstring❌ FacoltativoIdentificatore dello stile del giardino dalle opzioni di stile gardenStyle
sceneElementIdstring❌ FacoltativoIdentificatore degli elementi paesaggistici dalle opzioni di stile elements. Supporta più identificatori uniti da virgole, ad esempio id1,id2
modelTypestring❌ FacoltativoEnumerazione: Flash, Base, Pro. Valore predefinito: Base

Soltanto imageUrl è obbligatorio. Tutti gli altri campi sono facoltativi.

🖼️ Requisiti delle immagini: tutte le immagini originali e di riferimento devono usare JPG/JPEG, PNG o WebP. Ogni immagine non deve superare 20 MB, con dimensioni da 128 × 128 px fino a 6,000 × 6,000 px (estremi inclusi). Prima dell'elaborazione, le immagini che superano le dimensioni massime in pixel vengono ridotte automaticamente in modo proporzionale per rientrare in 6,000 × 6,000 px. Le URLs delle immagini devono essere direttamente accessibili dal server API.

📥 Esempi di richiesta#

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

📤 Risposta#

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

2. Ottieni il risultato dell'attività#

Endpoint

Testo semplice
GET /api/v1/landscaping/result

Intestazioni della richiesta

IntestazioneObbligatoriaDescrizione
APIKEY✅ SìLa tua chiave di autenticazione API

Parametri di interrogazione

ParametroTipoObbligatorioDescrizione
taskIdlong✅ SìIdentificatore dell'attività restituito dall'endpoint di creazione

📥 Esempi di richiesta#

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

📤 Esempio di risposta#

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

Risposta (attività in elaborazione / in coda)

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

Risposta (attività non riuscita)

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

📊 Stato dell'attività#

StatoDescrizione
UnprocessedL'attività è stata creata ed è in attesa in coda
ProcessingL'attività è attualmente in esecuzione
SuccessL'attività è stata completata correttamente
FailedL'attività non è riuscita e non è stato prodotto alcun output

Interroga lo stato ogni 3-5 secondi. Consulta i Limiti delle attività API.


❌ Risposte di errore#

CodiceNomeDescrizione
1011PARAM_ERRORErrore nei parametri della richiesta
5002API_KEY_INVALIDChiave API non valida o mancante
9010SCAN_TEXT_ERRORIl prompt non ha superato la verifica dei contenuti
9038PROHIBITED_CONTENTL'immagine generata contiene contenuti vietati
9051COINS_NOT_ENOUGHCrediti insufficienti

Per le definizioni complete degli errori comuni, consulta il Riferimento dei codici di errore.