Ideal House
Zum Hauptinhalt springen

API zur Gartengestaltung Dokumentation#

Basis-URL: https://api.ideal.house
Version: v1
Aktualisiert: 2026-05-21


📖 Übersicht#

Die API zur Gartengestaltung verbessert oder gestaltet Außenanlagen anhand eines Ausgangsbilds neu. Sie unterstützt optionale Textvorgaben, Gartenstile, Landschaftselemente und Modellmodi.

Der Arbeitsablauf ist asynchron:

  1. Aufgabe erstellen — Senden Sie imageUrl und optionale Parameter, dann erhalten Sie eine taskId.
  2. Ergebnisse regelmäßig abfragen — Verwenden Sie taskId, um Aufgabestatus und das generierte Bild abzurufen.

🔐 Authentifizierung#

KopfzeileWert
APIKEYyour_api_key_here

💰 Guthabenverbrauch#

[!WARNING] Guthabeneinheiten werden bei erfolgreicher Aufgabenerstellung abgezogen. Wenn die Aufgabe letztendlich fehlschlägt, werden abgezogene Guthabeneinheiten automatisch erstattet.
Unzureichende Guthabeneinheiten geben Fehlercode 9051 zurück. Siehe Referenz zum Guthabenverbrauch.

Modell (modelType)Abgezogene Guthabeneinheiten
Flash1 Guthabeneinheit
Base3 Guthabeneinheiten
Pro10 Guthabeneinheiten

Wenn modelType nicht angegeben wird, wird standardmäßig Base verwendet.


🎨 Stileinstellungen#

Diese API unterstützt optionale Stilkonfigurationen, die vom API-Stilkonfiguration-Endpunkt zurückgegeben werden.

Verwenden:

Klartext
GET /api/v1/style/landscaping/getStyles
StilgruppeAnforderungsfeldBeschreibung
gardenStylesceneIdGarten- oder Landschaftsstiloption
elementssceneElementIdLandschaftselementoption. Unterstützt mehrere durch Komma getrennte Options-IDs, z.B. id1,id2

Jede Option enthält name, id und url. Übergeben Sie die Option-id in das entsprechende Anforderungsfeld.


📌 API Endpunkte#

1. Aufgabe zur Gartengestaltung erstellen#

Endpunkt

Klartext
POST /api/v1/landscaping/generate

Anforderungsheader

KopfzeileErforderlichBeschreibung
APIKEY✅ JaIhr API Authentifizierungsschlüssel
Content-Type✅ Jaapplication/json

Anforderungskörper

FeldTypErforderlichBeschreibung
imageUrlstring✅ JaURL des Ausgangsbilds der Außenanlage
promptstring❌ OptionalTextanleitung für das gewünschte Ergebnis
sceneIdstring❌ OptionalGartengestaltungs-ID aus gardenStyle Stiloptionen
sceneElementIdstring❌ OptionalLandschaftselement-ID aus elements Stiloptionen. Unterstützt mehrere durch Komma getrennte IDs, z.B. id1,id2
modelTypestring❌ OptionalEnum: Flash, Base, Pro. Standardmäßig Base

Nur imageUrl ist erforderlich. Alle anderen Felder sind optional.

🖼️ Bildanforderungen: Alle Ausgangs- und Referenzbilder müssen JPG/JPEG, PNG oder WebP verwenden. Jedes Bild darf maximal 20 MB groß sein, mit Abmessungen von 128 × 128 px bis zu 6,000 × 6,000 px (inklusive). Bilder, die die maximalen Pixelabmessungen überschreiten, werden automatisch proportional herunter-skaliert, um innerhalb von 6,000 × 6,000 px vor der Verarbeitung zu passen. Bild-URLs müssen direkt vom API Server erreichbar sein.

📥 Anfragebeispiele#

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

📤 Antwort#

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

2. Aufgabenergebnis abrufen#

Endpunkt

Klartext
GET /api/v1/landscaping/result

Anforderungsheader

KopfzeileErforderlichBeschreibung
APIKEY✅ JaIhr API Authentifizierungsschlüssel

Abfrageparameter

ParameterTypErforderlichBeschreibung
taskIdlong✅ JaVom Erstellungsendpunkt zurückgegebene Aufgaben-ID

📥 Anfragebeispiele#

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

📤 Antwortbeispiel#

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

Antwort (Aufgabe in Bearbeitung / in Warteschlange)

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

Antwort (Aufgabe fehlgeschlagen)

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

📊 Aufgabenstatus#

StatusBeschreibung
UnprocessedAufgabe wurde erstellt und wartet in der Warteschlange
ProcessingAufgabe wird derzeit ausgeführt
SuccessAufgabe erfolgreich abgeschlossen
FailedAufgabe fehlgeschlagen und keine Ausgabe erzeugt

Alle 3-5 Sekunden abfragen. Siehe API Aufgabenlimit.


❌ Fehlerantworten#

CodeNameBeschreibung
1011PARAM_ERRORAnforderungsparameterfehler
5002API_KEY_INVALIDUngültiger oder fehlender API Schlüssel
9010SCAN_TEXT_ERRORPrompt bestand Inhaltsüberprüfung nicht
9038PROHIBITED_CONTENTGeneriertes Bild enthält verbotene Inhalte
9051COINS_NOT_ENOUGHUnzureichende Guthabeneinheiten

Für vollständige gemeinsame Fehlerdefinitionen siehe Fehlercode-Referenz.