Grundrissgenerierung API Dokumentation#

Basis-URL:https://api.ideal.house
Version: v1
Aktualisiert: 2026-08-09

📖 Übersicht#

Die API zur Grundrissgenerierung erstellt aus strukturierten Raumvorgaben sowie einem optionalen benutzerdefinierten Prompt oder Referenzbild einen KI-generierten, schwarz-weißen Grundriss einer Wohnimmobilie in CAD-Optik aus der Draufsicht.

Die Ausgabe ist für frühe Layout-Explorationen gedacht. Sie ist keine Bauzeichnung und generierte Maße, Geometrie, Anordnung von Einrichtungen sowie die Einhaltung von Vorschriften müssen von einer qualifizierten Fachperson überprüft werden.

Der Arbeitsablauf ist asynchron:

1. Erstellen Sie eine Aufgabe — Übermitteln Sie die Grundrissparameter und erhalten Sie eine taskId.
2. Fragen Sie Ergebnisse regelmäßig ab — Fragen Sie den Ergebnisendpunkt mit der taskId ab, bis die Aufgabe einen Endstatus erreicht hat.

🔐 Authentifizierung#

Alle öffentlichen API-Anfragen müssen einen API-Schlüssel enthalten.

[!WARNING] Bewahren Sie Ihren API-Schlüssel sicher auf. Geben Sie ihn nicht in clientseitigem Code oder öffentlichen Repositories preis.

💰 Guthabenverbrauch#

Credits werden nach erfolgreicher Erstellung einer Generierungsaufgabe abgezogen. Wenn die Aufgabe letztendlich fehlschlägt, werden die abgezogenen Credits automatisch zurückerstattet. Bei unzureichenden Credits wird der Fehlercode 9051 zurückgegeben.

Flash wird vom API zur Grundrissgenerierung nicht unterstützt.

Siehe Referenz zum Guthabenverbrauch für allgemeines Abrechnungsverhalten.

📌 API Endpunkte#

1. Grundrissaufgabe erstellen#

Erstellt eine Grundriss-Generierungsaufgabe und gibt eine eindeutige Aufgaben-ID zurück.

Endpunkt

POST /api/v1/floorPlan/generate

Anfrage-Header

Anfragetext#

[!IMPORTANT] Die öffentliche API validiert derzeit bedrooms als 0–5 und bathrooms als 0.5–4. Werte, die in einer anderen Client-Benutzeroberfläche verfügbar sind, erweitern diese serverseitigen Grenzen nicht.

Allgemeine Anfrageregeln#

• Alle Enum-Werte sind abhängig von Groß- und Kleinschreibung und müssen die in diesem Dokument gezeigten englischen Werte verwenden.
• totalArea ist eine Zielgesamtfläche, der zur Steuerung von Maßstab und Proportionen dient; er wird nicht als exakte Bauabmessung behandelt.
• Der effektive benutzerdefinierte Prompt wird auf die ersten 800 Zeichen beschränkt, wenn der strukturierte Bildprompt zusammengesetzt wird.
• Strukturierte Felder haben Vorrang vor widersprüchlichen Anweisungen in prompt.
• Eine erfolgreiche Aufgabe generiert genau ein Bild.

📐 Gesamtfläche#

totalArea enthält einen positiven numerischen Wert gefolgt von einer Flächeneinheit.

Ein Leerzeichen vor der Einheit wird empfohlen. Dezimalwerte werden akzeptiert, wenn sie positiv sind.

Gültige Beispiele:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ Schlafzimmerflächenbereiche#

bedroomAreaRanges bietet relative Größenrichtlinien für Schlafzimmer. Es werden keine numerischen Flächenbeschriftungen im generierten Bild angefordert.

Jeder Eintrag hat die folgende Form:

Explizites Bereichsbeispiel

{
  "bedroomAreaRanges": [
    {
      "name": "Room 1 (Master)",
      "minArea": "30",
      "maxArea": "40",
      "unit": "m²"
    },
    {
      "name": "Room 2",
      "minArea": "20",
      "maxArea": "30",
      "unit": "m²"
    }
  ]
}

Regeln bei Lieferung eines nicht-leeren Arrays:

• Seine Länge muss gleich bedrooms sein.
• Jedes gelieferte minArea und maxArea muss ein positiver numerischer String sein.
• Wenn beide Werte geliefert werden, gilt minArea <= maxArea.
• unit muss, wenn geliefert, m² oder ft² sein.
• Namen bleiben erhalten. Leere oder null-Einträge liefern keine Größenrichtlinie.

Automatische Bereiche bei Weglassen#

Das Feld kann weggelassen oder als leeres Array gesendet werden. Wenn kein Eintrag einen wirksamen minArea oder maxArea enthält, leitet der strukturierte Generierungspfad interne Schlafzimmerbereiche aus totalArea und bedrooms ab:

• Das Schlafzimmerflächenbudget beginnt bei 20% des Gesamtfläche für ein Schlafzimmer.
• Das Budget erhöht sich um 7.5 Prozentpunkte pro zusätzlichem Schlafzimmer, gedeckelt bei 50%.
• Das erste Schlafzimmer erhält ein 1.3-Größengewicht; jedes weitere Schlafzimmer erhält ein 1.0-Gewicht.
• Jedes Ziel wird zu einem ungefähren ±10%-Bereich, gerundet auf ganzzahlige Flächeneinheiten.
• Die Einheit wird von totalArea geerbt.
• Vorhandene nicht-leere Raumnamen werden beibehalten; andernfalls verwendet der Server Room 1, Room 2 und so weiter.

Für 200 m² und 4 Schlafzimmer beträgt die aktuelle abgeleitete Richtlinie ungefähr:

[
  { "name": "Room 1", "minArea": "23", "maxArea": "28", "unit": "m²" },
  { "name": "Room 2", "minArea": "18", "maxArea": "22", "unit": "m²" },
  { "name": "Room 3", "minArea": "18", "maxArea": "22", "unit": "m²" },
  { "name": "Room 4", "minArea": "18", "maxArea": "22", "unit": "m²" }
]

Diese Werte sind interne proportionale Richtlinien, keine garantierten endgültigen Raumflächen. Explizite gültige Bereiche haben stets Vorrang vor automatischen Bereichen.

Wenn bedrooms 0 ist, lassen Sie bedroomAreaRanges weg oder senden Sie [].

🛁 Badezimmerdetails#

bathrooms repräsentiert die Gesamtanzahl der Badezimmer:

• Ihr ganzzahliger Anteil ist die Anzahl der Vollbadezimmer.
• Ein .5-Bruchteil fügt ein halbes Badezimmer hinzu.
• Jedes Vollbad wird mit der Anweisung generiert, eine Toilette, einen Waschtisch/Waschbecken und eine Dusche oder Nassbereich einzuschließen.
• Ein halbes Badezimmer enthält nur eine Toilette und einen Waschtisch/Waschbecken, ohne Dusche oder Badewanne.

bathroomDetails konfiguriert nur Vollbadezimmer:

{
  "bathroomDetails": {
    "fullBathroomOptions": [
      {
        "name": "Bathroom 1",
        "wetDrySeparation": "yes",
        "bathtub": "required"
      },
      {
        "name": "Bathroom 2",
        "wetDrySeparation": "no",
        "bathtub": "optional"
      }
    ]
  }
}

Regeln:

• fullBathroomOptions.length darf floor(bathrooms) nicht überschreiten.
• Das Array darf nur die Vollbadezimmer enthalten, für die Präferenzen ausgewählt wurden.
• Ein null-Wert bedeutet nicht spezifiziert.
• Eine erforderliche Badewanne ist zusätzlich zu den Standard-Vollbadezimmer-Ausstattungen; sie ersetzt nicht die Toilette oder Dusche.
• Nass/Trocken-Trennung ist eine interne Trennwand innerhalb eines gezählten Badezimmers, kein zusätzliches Badezimmer.

🍳 Küchendetails#

Alle kitchenDetails-Unterfelder sind optional. Lassen Sie das gesamte Objekt weg, wenn keine Küchenpräferenz ausgewählt ist.

{
  "kitchenDetails": {
    "type": "open",
    "size": "standard",
    "layout": "U",
    "islandType": "preparation",
    "storage": "maximum",
    "features": ["breakfast nook", "pantry"]
  }
}

Teilweise Konfiguration ist gültig. Zum Beispiel:

{
  "kitchenDetails": {
    "type": "semi-open"
  }
}

🚪 Wichtige Räume#

keyRooms akzeptiert ein Array dieser genauen Werte:

Der ältere Web-Wert balcon wird ebenfalls akzeptiert und zu balcony normalisiert.

Regeln:

• Leere Werte werden ignoriert und Duplikate werden entfernt.
• Ausgewählte wichtige Räume werden einmal angefordert.
• Nicht ausgewählte optionale Räume werden vom generierten Raumprogramm ausgeschlossen.
• Wenn pantry sowohl in kitchenDetails.features als auch in keyRooms erscheint, wird nur eine Speisekammer angefordert.

Beispiel:

{
  "keyRooms": [
    "garage",
    "home office",
    "combined living-dining"
  ]
}

🖼️ Referenzbild#

refImageUrl ist optional und muss direkt vom API-Server zugänglich sein.

Anforderungen:

• Format: JPG/JPEG, PNG oder WebP.
• Maximale Dateigröße: 20 MB.
• Minimale Abmessungen: 128 × 128 px.
• Maximale Abmessungen: 6,000 × 6,000 px. Größere Bilder werden vor der Verarbeitung proportional skaliert.

Das Referenzbild leitet Layout, räumliche Anordnung, Proportionen oder visuellen Stil. Es überschreibt nicht strukturierte Raumzählungen oder andere harte Beschränkungen.

🤖 Modelltypen#

Nur Base und Pro werden unterstützt.

Felder nicht im öffentlichen fachlichen API-Vertrag#

Die folgenden Felder dürfen von öffentlichen API-Clients nicht als verlässlich angesehen werden:

Entfernte Legacy-Felder, die nicht gesendet werden dürfen:

floorplanSetting
roomCounts
grossArea
totalAreaValue
totalAreaUnit
totalAreaType
fullBathrooms
halfBathrooms
halfBathroomRequirement
kitchenType
diningRooms
livingRooms
extras
referenceImage
hasDetailOptions

📥 Beispiele zum Erstellen von Aufgaben#

Minimale Anfrage mit automatischen Schlafzimmerflächenbereichen#

curl -X POST "https://api.ideal.house/api/v1/floorPlan/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bedrooms": 4,
    "bathrooms": 2,
    "totalArea": "200 m²",
    "modelType": "Pro",
    "prompt": "Upper floor of a two-story Saudi Arabian villa with a master bedroom, family living area, staircase landing, and balcony"
  }'

Vollständige Anfrage#

curl -X POST "https://api.ideal.house/api/v1/floorPlan/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bedrooms": 3,
    "bathrooms": 2.5,
    "totalArea": "220 m²",
    "bedroomAreaRanges": [
      {"name": "Room 1 (Master)", "minArea": "30", "maxArea": "40", "unit": "m²"},
      {"name": "Room 2", "minArea": "20", "maxArea": "30", "unit": "m²"},
      {"name": "Room 3", "minArea": "20", "maxArea": "30", "unit": "m²"}
    ],
    "bathroomDetails": {
      "fullBathroomOptions": [
        {"name": "Bathroom 1", "wetDrySeparation": "yes", "bathtub": "required"},
        {"name": "Bathroom 2", "wetDrySeparation": "no", "bathtub": "optional"}
      ]
    },
    "kitchenDetails": {
      "type": "open",
      "size": "standard",
      "layout": "U",
      "islandType": "preparation",
      "storage": "maximum",
      "features": ["breakfast nook", "pantry"]
    },
    "keyRooms": ["garage", "home office", "combined living-dining"],
    "prompt": "Bright modern home with good natural lighting",
    "refImageUrl": "https://example.com/reference-plan.png",
    "modelType": "Pro"
  }'

import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class FloorPlanApiExample {

    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 Exception {
        OkHttpClient client = new OkHttpClient();
        String json = """
                {
                  "bedrooms": 4,
                  "bathrooms": 2,
                  "totalArea": "200 m²",
                  "keyRooms": ["walk-in closet", "balcony"],
                  "prompt": "Upper floor with a master bedroom and family living area",
                  "modelType": "Pro"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/floorPlan/generate")
                .addHeader("APIKEY", API_KEY)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(json, MediaType.parse("application/json")))
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

import requests

BASE_URL = "https://api.ideal.house"
API_KEY = "your_api_key_here"

payload = {
    "bedrooms": 4,
    "bathrooms": 2,
    "totalArea": "200 m²",
    "keyRooms": ["walk-in closet", "balcony"],
    "prompt": "Upper floor with a master bedroom and family living area",
    "modelType": "Pro",
}

response = requests.post(
    f"{BASE_URL}/api/v1/floorPlan/generate",
    headers={"APIKEY": API_KEY, "Content-Type": "application/json"},
    json=payload,
)
response.raise_for_status()
print("Task ID:", response.json()["data"])

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY = 'your_api_key_here';

async function createFloorPlanTask() {
  const response = await axios.post(
    `${BASE_URL}/api/v1/floorPlan/generate`,
    {
      bedrooms: 4,
      bathrooms: 2,
      totalArea: '200 m²',
      keyRooms: ['walk-in closet', 'balcony'],
      prompt: 'Upper floor with a master bedroom and family living area',
      modelType: 'Pro'
    },
    {
      headers: {
        APIKEY: API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Task ID:', response.data.data);
  return response.data.data;
}

createFloorPlanTask();

Erfolgreiche Antwort beim Erstellen einer Aufgabe#

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

2. Aufgabenergebnis abrufen#

Gibt den Aufgabenfortschritt und das generierte Bild zurück, wenn verfügbar.

Endpunkt

GET /api/v1/floorPlan/result?taskId={taskId}

Anfrage-Header

Abfrageparameter

Beispiele für Ergebnisabfragen#

curl -X GET "https://api.ideal.house/api/v1/floorPlan/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

import time
import requests

BASE_URL = "https://api.ideal.house"
API_KEY = "your_api_key_here"
task_id = 1234567890123456789

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/floorPlan/result",
        headers={"APIKEY": API_KEY},
        params={"taskId": task_id},
    )
    response.raise_for_status()
    task = response.json()["data"]
    print(task["status"], task["percentage"], task["waitNumber"])

    if task["status"] in ("Success", "Failed", "Termination"):
        break

    time.sleep(3)

if task["status"] == "Success":
    print("Result URL:", task["output"]["resultUrl"])

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY = 'your_api_key_here';

async function pollFloorPlanResult(taskId) {
  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/floorPlan/result`,
      {
        headers: { APIKEY: API_KEY },
        params: { taskId }
      }
    );

    const task = response.data.data;
    console.log(task.status, task.percentage, task.waitNumber);

    if (['Success', 'Failed', 'Termination'].includes(task.status)) {
      if (task.status === 'Success') {
        console.log('Result URL:', task.output.resultUrl);
      }
      return task;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollFloorPlanResult('1234567890123456789');

Abgeschlossene Aufgabenantwort#

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "bedrooms": 4,
      "bathrooms": 2,
      "totalArea": "200 m²",
      "bedroomAreaRanges": [
        {"name": "Room 1", "minArea": "23", "maxArea": "28", "unit": "m²"},
        {"name": "Room 2", "minArea": "18", "maxArea": "22", "unit": "m²"},
        {"name": "Room 3", "minArea": "18", "maxArea": "22", "unit": "m²"},
        {"name": "Room 4", "minArea": "18", "maxArea": "22", "unit": "m²"}
      ],
      "keyRooms": ["walk-in closet", "balcony"],
      "prompt": "Upper floor with a master bedroom and family living area",
      "modelType": "Pro"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/floor-plan.jpg",
      "width": 2496,
      "height": 1664
    }
  }
}

Verarbeitungsantwort#

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "bedrooms": 4,
      "bathrooms": 2,
      "totalArea": "200 m²",
      "modelType": "Pro"
    },
    "output": null
  }
}

Fehlgeschlagene Aufgabenantwort#

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "bedrooms": 4,
      "bathrooms": 2,
      "totalArea": "200 m²",
      "modelType": "Pro"
    },
    "output": null
  }
}

Ergebnisfelder#

📊 Aufgabenstatus#

Fragen Sie alle 3–5 Sekunden den Status ab. Siehe API Aufgabenlimit.

❌ Fehlerantworten#

Alle Fehlerantworten verwenden die gemeinsame Antwortstruktur:

{
  "code": 1011,
  "message": "bedroomAreaRanges size must match bedrooms",
  "data": null
}

Siehe Referenz zu Fehlercodes für die vollständige Liste gängiger Fehler.

🔄 Web-Integration Hinweise#

Die authentifizierte Webanwendung und die öffentliche API verwenden unterschiedliche Endpunkte und Authentifizierungsmethoden:

Die Geschäfts-Feldstrukturen sind abgeglichen, aber öffentliche API-Clients sollten die serverseitigen Grenzen und den öffentlichen Vertrag in diesem Dokument befolgen. Insbesondere:

• Web-Clients können interne imageNumbers und extData enthalten; öffentliche Clients benötigen diese nicht.
• Die öffentliche API ermittelt API-Call-Metadaten aus dem Endpunkt und den Anmeldeinformationen. Anfragefelder wie isApiCall und genByMember sind unnötig.
• balcon wird zur Kompatibilität akzeptiert und zu balcony normalisiert; neue Integrationen sollten balcony senden.
• Die aktuellen öffentlichen Servergrenzen bleiben 0–5 Schlafzimmer und 0.5–4 Badezimmer, auch wenn eine andere Benutzeroberfläche vorübergehend breitere Auswahlfelder anzeigt.