Ideal House
Zum Hauptinhalt springen

Dokumentation zur API zur Planvisualisierung#

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


📖 Übersicht#

Die API zur Planvisualisierung wandelt ein Planbild in eine KI-generierte Visualisierung um. Sie unterstützt optionale Textanweisungen, Plantypen, visuellen Stil, Ansichtsoptionen 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
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/ai_plan_visualizer/getStyles
StilgruppeAnforderungsfeldBeschreibung
planTypeplanStyleIdOption für Plantyp
stylestyleIdOption für Visualisierungsstil
viewviewIdOption für Kamera/Ansicht

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


📌 API Endpunkte#

1. Erstellen einer Aufgabe zur Planvisualisierung#

Endpunkt

Klartext
POST /api/v1/planVisualizer/generate

Anforderungsheader

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

Anforderungskörper

FeldTypErforderlichBeschreibung
imageUrlstring✅ JaURL des Ausgangsplanbilds
promptstring❌ OptionalTextanweisung für die gewünschte Visualisierung
planStyleIdstring❌ OptionalPlantyp-ID aus den planType-Stiloptionen
styleIdstring❌ OptionalVisualisierungsstil-ID aus den style-Stiloptionen
viewIdstring❌ OptionalAnsicht-ID aus den view-Stiloptionen
modelTypestring❌ OptionalEnum: Base, Pro. Standardwert ist 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 verkleinert, 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/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();

📤 Antwort#

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

2. Aufgabenergebnis abrufen#

Endpunkt

Klartext
GET /api/v1/planVisualizer/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/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);

📤 Antwortbeispiel#

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

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/floor-plan.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/floor-plan.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.