Documentatie voor de API voor plattegronden#

Basis-URL: https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-08-09

📖 Overzicht#

De API voor plattegronden maakt met AI één zwart-witte conceptplattegrond van een woning in CAD-stijl, van bovenaf gezien, op basis van gestructureerde ruimtevereisten en een optionele eigen tekstinstructie of referentieafbeelding.

De uitvoer is bedoeld om in een vroege fase indelingen te verkennen. Het is geen bouwtekening. Gegenereerde afmetingen, geometrie, plaatsing van voorzieningen en naleving van bouwvoorschriften moeten door een gekwalificeerde professional worden beoordeeld.

De werkstroom is asynchroon:

1. Een taak aanmaken — Dien de plattegrondparameters in en ontvang een taskId.
2. Resultaten regelmatig opvragen — Vraag het resultaateindpunt op met de taskId totdat de taak een eindstatus bereikt.

🔐 Authenticatie#

Alle openbare API-verzoeken moeten een API-sleutel bevatten.

[!WARNING] Bewaar je API-sleutel veilig. Stel deze niet bloot in code aan de clientzijde of openbare repositories.

💰 Creditafschrijving#

Credits worden afgeschreven nadat een generatietaak succesvol is aangemaakt. Als de taak uiteindelijk mislukt, worden de afgeschreven credits automatisch terugbetaald. Onvoldoende credits leveren foutcode 9051 op.

Flash wordt niet ondersteund door de API voor plattegronden.

Zie Referentie voor creditafschrijving voor het algemene factureringsgedrag.

📌 API-endpoints#

1. Een plattegrondtaak aanmaken#

Maakt een taak voor het genereren van een plattegrond aan en retourneert een unieke taak-ID.

Eindpunt

POST /api/v1/floorPlan/generate

Verzoekheaders

Verzoekinhoud#

[!IMPORTANT] De openbare API valideert bedrooms momenteel als 0–5 en bathrooms als 0.5–4. Waarden die in een andere clientinterface beschikbaar zijn, verruimen deze serverlimieten niet.

Algemene verzoekregels#

• Alle opsommingswaarden zijn hoofdlettergevoelig en moeten de Engelse waarden uit dit document gebruiken.
• totalArea is een gewenste totale oppervlakte die de schaal en verhoudingen stuurt; deze wordt niet behandeld als een exacte bouwmaat.
• Bij het samenstellen van de gestructureerde afbeeldingsinstructie wordt de effectieve eigen tekstinstructie beperkt tot de eerste 800 tekens.
• Gestructureerde velden hebben voorrang op tegenstrijdige instructies in prompt.
• Een geslaagde taak genereert precies één afbeelding.

📐 Totale oppervlakte#

totalArea bevat één positieve numerieke waarde gevolgd door een oppervlakte-eenheid.

Een spatie vóór de eenheid wordt aanbevolen. Positieve decimale waarden worden geaccepteerd.

Geldige voorbeelden:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ Oppervlaktebereiken voor slaapkamers#

bedroomAreaRanges geeft richtlijnen voor de relatieve grootte van slaapkamers. Het vraagt niet om numerieke oppervlaktelabels in de gegenereerde afbeelding.

Elk element heeft de volgende structuur:

Voorbeeld met expliciet bereik

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

Regels wanneer een niet-lege array wordt opgegeven:

• De lengte moet gelijk zijn aan bedrooms.
• Elke opgegeven minArea en maxArea moet een positieve numerieke tekenreeks zijn.
• Wanneer beide waarden zijn opgegeven, geldt minArea <= maxArea.
• Indien opgegeven, moet unit gelijk zijn aan m² of ft².
• Namen blijven behouden. Lege elementen of null-elementen geven geen richtlijn voor de grootte.

Automatische bereiken bij weglaten#

Het veld mag worden weggelaten of als lege array worden verstuurd. Als geen enkel element een effectieve minArea of maxArea bevat, leidt het gestructureerde generatiepad interne slaapkamerbereiken af van totalArea en bedrooms:

• Het oppervlaktebudget voor slaapkamers begint bij 20% van de totale oppervlakte voor één slaapkamer.
• Het budget neemt met 7.5 procentpunten toe per extra slaapkamer, tot maximaal 50%.
• De eerste slaapkamer krijgt wegingsfactor 1.3 voor de grootte; elke andere slaapkamer krijgt wegingsfactor 1.0.
• Elke streefwaarde wordt omgezet in een benaderend bereik van ±10%, afgerond op hele oppervlakte-eenheden.
• De eenheid wordt overgenomen van totalArea.
• Bestaande niet-lege kamernamen blijven behouden; anders gebruikt de server Room 1, Room 2 enzovoort.

Voor 200 m² en 4 slaapkamers is de huidige afgeleide richtlijn ongeveer:

[
  { "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²" }
]

Deze waarden zijn interne richtlijnen voor de verhoudingen en garanderen geen definitieve kameroppervlakten. Expliciete geldige bereiken hebben altijd voorrang op automatische bereiken.

Wanneer bedrooms gelijk is aan 0, laat je bedroomAreaRanges weg of stuur je [].

🛁 Badkamerdetails#

bathrooms geeft het totale aantal badkamers aan:

• Het gehele deel is het aantal volledige badkamers.
• Een fractie van .5 voegt één toiletruimte toe.
• Voor elke volledige badkamer wordt een toilet, wastafel(meubel) en douche of natte zone gevraagd.
• Een toiletruimte bevat alleen een toilet en wastafel(meubel), zonder douche of badkuip.

bathroomDetails configureert uitsluitend volledige badkamers:

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

Regels:

• fullBathroomOptions.length mag niet groter zijn dan floor(bathrooms).
• De array mag uitsluitend de volledige badkamers bevatten waarvoor voorkeuren zijn geselecteerd.
• Een waarde van null betekent niet opgegeven.
• Een verplichte badkuip komt bovenop de standaardvoorzieningen van een volledige badkamer; deze vervangt het toilet of de douche niet.
• Een scheiding tussen nat en droog is een interne scheidingswand binnen een meegetelde badkamer, geen extra badkamer.

🍳 Keukendetails#

Alle onderliggende velden van kitchenDetails zijn optioneel. Laat het hele object weg wanneer geen keukenvoorkeur is geselecteerd.

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

Een gedeeltelijke configuratie is geldig. Bijvoorbeeld:

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

🚪 Bijzondere kamers#

keyRooms accepteert een array met deze exacte waarden:

De oude webwaarde balcon wordt ook geaccepteerd en genormaliseerd naar balcony.

Regels:

• Lege waarden worden genegeerd en dubbele waarden verwijderd.
• Geselecteerde bijzondere kamers worden eenmaal aangevraagd.
• Niet-geselecteerde optionele ruimten worden uitgesloten van het gegenereerde ruimteprogramma.
• Als pantry zowel in kitchenDetails.features als in keyRooms voorkomt, wordt slechts één voorraadkast aangevraagd.

Voorbeeld:

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

🖼️ Referentieafbeelding#

refImageUrl is optioneel en moet rechtstreeks toegankelijk zijn voor de API-server.

Vereisten:

• Bestandsformaat: JPG/JPEG, PNG of WebP.
• Maximale bestandsgrootte: 20 MB.
• Minimale afmetingen: 128 × 128 px.
• Maximale afmetingen: 6,000 × 6,000 px. Grotere afbeeldingen worden vóór verwerking proportioneel verkleind.

De referentieafbeelding stuurt de indeling, onderlinge ligging, verhoudingen of visuele stijl. Deze overschrijft geen gestructureerde aantallen kamers of andere harde beperkingen.

🤖 Modeltypen#

Alleen Base en Pro worden ondersteund.

Velden buiten de openbare functionele interface#

Openbare API-clients mogen niet afhankelijk zijn van de volgende velden:

Verwijderde oude velden die niet mogen worden verstuurd:

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

📥 Voorbeelden voor het aanmaken van een taak#

Minimaal verzoek met automatische slaapkamerbereiken#

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

Volledig verzoek#

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

Antwoord bij succesvol aanmaken van een taak#

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

2. Taakresultaat ophalen#

Retourneert de taakvoortgang en de gegenereerde afbeelding zodra deze beschikbaar is.

Eindpunt

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

Verzoekheaders

Queryparameters

Voorbeelden van resultaatverzoeken#

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

Antwoord voor een voltooide taak#

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

Antwoord tijdens verwerking#

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

Antwoord voor een mislukte taak#

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

Resultaatvelden#

📊 Taakstatus#

Vraag de status elke 3–5 seconden op. Zie Taaklimiet voor de API.

❌ Foutantwoorden#

Alle foutantwoorden gebruiken de algemene antwoordstructuur:

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

Zie Foutcodereferentie voor de volledige lijst met algemene fouten.

🔄 Opmerkingen over webintegratie#

De geauthenticeerde webapplicatie en de openbare API gebruiken verschillende eindpunten en authenticatiemethoden:

De structuren van de functionele velden komen overeen, maar openbare API-clients moeten de serverlimieten en openbare interface uit dit document volgen. In het bijzonder:

• Webclients kunnen interne imageNumbers en extData bevatten; openbare clients hebben deze niet nodig.
• De openbare API bepaalt metadata voor de API-aanroep op basis van het eindpunt en de aanmeldgegevens. Verzoekvelden zoals isApiCall en genByMember zijn overbodig.
• balcon wordt voor compatibiliteit geaccepteerd en genormaliseerd naar balcony; nieuwe integraties moeten balcony versturen.
• De huidige openbare serverlimieten blijven 0–5 slaapkamers en 0.5–4 badkamers, zelfs als een andere interface tijdelijk ruimere keuzemogelijkheden toont.