Documentazione API di generazione di planimetrie#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-08-09

📖 Panoramica#

API di generazione di planimetrie crea una planimetria concettuale residenziale generata dall'intelligenza artificiale, in bianco e nero, vista dall'alto e in stile CAD, a partire da requisiti strutturati delle stanze e, facoltativamente, da un prompt personalizzato o un'immagine di riferimento.

L'output è destinato all'esplorazione preliminare della disposizione degli spazi. Non è un disegno esecutivo e le dimensioni, la geometria, il posizionamento degli impianti e la conformità normativa generati devono essere esaminati da un professionista qualificato.

Il flusso di lavoro è asincrono:

1. Crea un'attività — Invia i parametri della planimetria e ricevi un taskId.
2. Interroga periodicamente i risultati — Interroga l'endpoint dei risultati con il taskId finché l'attività non raggiunge uno stato finale.

🔐 Autenticazione#

Tutte le richieste API pubbliche devono includere una chiave API.

[!WARNING] Conserva la chiave API in sicurezza. Non esporla nel codice lato client o in repository pubblici.

💰 Detrazione dei crediti#

I crediti vengono detratti dopo la creazione riuscita di un'attività di generazione. Se alla fine l'attività non riesce, i crediti detratti vengono rimborsati automaticamente. Un saldo insufficiente restituisce il codice di errore 9051.

Flash non è supportato da API di generazione di planimetrie.

Consulta il Riferimento delle detrazioni dei crediti per il comportamento comune della fatturazione.

📌 Endpoint API#

1. Crea un'attività di generazione di una planimetria#

Crea un'attività di generazione di una planimetria e restituisce un identificatore univoco dell'attività.

Endpoint

POST /api/v1/floorPlan/generate

Intestazioni della richiesta

Corpo della richiesta#

[!IMPORTANT] API pubblica attualmente convalida bedrooms nell'intervallo 0–5 e bathrooms nell'intervallo 0.5–4. I valori disponibili nell'interfaccia di un altro client non ampliano questi limiti del server.

Regole generali delle richieste#

• Tutti i valori delle enumerazioni distinguono maiuscole e minuscole e devono usare i valori inglesi mostrati in questo documento.
• totalArea è una superficie totale desiderata usata per orientare scala e proporzioni; non viene trattata come una dimensione esecutiva esatta.
• Il prompt personalizzato effettivo è limitato ai primi 800 caratteri durante l'assemblaggio del prompt strutturato per l'immagine.
• I campi strutturati hanno la precedenza sulle istruzioni contrastanti in prompt.
• Un'attività riuscita genera esattamente un'immagine.

📐 Superficie totale#

totalArea contiene un solo valore numerico positivo seguito da un'unità di superficie.

Si consiglia uno spazio prima dell'unità. Sono accettati valori decimali purché positivi.

Esempi validi:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ Intervalli di superficie delle camere da letto#

bedroomAreaRanges fornisce indicazioni relative sulle dimensioni delle camere da letto. Non richiede etichette numeriche delle superfici nell'immagine generata.

Ogni elemento ha la seguente struttura:

Esempio di intervallo esplicito

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

Regole quando viene fornito un array non vuoto:

• La sua lunghezza deve essere uguale a bedrooms.
• Ogni minArea e maxArea fornito deve essere una stringa numerica positiva.
• Quando vengono forniti entrambi i valori, minArea <= maxArea.
• unit, quando fornito, deve essere m² o ft².
• I nomi vengono conservati. Gli elementi vuoti o nulli non forniscono indicazioni sulle dimensioni.

Intervalli automatici quando omessi#

Il campo può essere omesso o inviato come array vuoto. Quando nessun elemento contiene un minArea o maxArea effettivo, la procedura di generazione strutturata ricava intervalli interni per le camere da letto da totalArea e bedrooms:

• La quota di superficie per le camere da letto parte dal 20% della superficie totale per una camera.
• La quota aumenta di 7.5 punti percentuali per ogni camera da letto aggiuntiva, fino a un massimo del 50%.
• La prima camera da letto riceve un peso dimensionale di 1.3; ogni altra camera riceve un peso di 1.0.
• Ogni valore desiderato diventa un intervallo approssimativo di ±10%, arrotondato a unità intere di superficie.
• L'unità viene ereditata da totalArea.
• I nomi esistenti delle stanze non vuoti vengono conservati; altrimenti il server usa Room 1, Room 2 e così via.

Per 200 m² e 4 camere da letto, le indicazioni attualmente ricavate sono approssimativamente:

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

Questi valori sono indicazioni proporzionali interne, non superfici finali garantite delle stanze. Gli intervalli espliciti validi hanno sempre la precedenza su quelli automatici.

Quando bedrooms è 0, ometti bedroomAreaRanges oppure invia [].

🛁 Dettagli dei bagni#

bathrooms rappresenta il numero totale di bagni:

• La sua parte intera è il numero di bagni completi.
• Una frazione .5 aggiunge un bagno di servizio.
• Per ogni bagno completo viene richiesta la presenza di un WC, un mobile lavabo/lavandino e una doccia o zona umida.
• Un bagno di servizio contiene soltanto un WC e un mobile lavabo/lavandino, senza doccia né vasca.

bathroomDetails configura soltanto i bagni completi:

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

Regole:

• fullBathroomOptions.length non può superare floor(bathrooms).
• L'array può contenere soltanto i bagni completi per i quali sono state selezionate preferenze.
• Un valore null significa non specificato.
• Una vasca obbligatoria si aggiunge alla dotazione standard del bagno completo; non sostituisce il WC o la doccia.
• La separazione tra zona umida e asciutta è una partizione interna a un bagno già conteggiato, non un bagno aggiuntivo.

🍳 Dettagli della cucina#

Tutti i campi figli di kitchenDetails sono facoltativi. Ometti l'intero oggetto quando non viene selezionata alcuna preferenza per la cucina.

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

Una configurazione parziale è valida. Ad esempio:

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

🚪 Stanze principali#

keyRooms accetta un array di questi valori esatti:

Il valore Web precedente balcon viene accettato e normalizzato in balcony.

Regole:

• I valori vuoti vengono ignorati e quelli duplicati rimossi.
• Le stanze principali selezionate vengono richieste una sola volta.
• Gli spazi facoltativi non selezionati sono esclusi dall'insieme di ambienti previsto dalla generazione.
• Se pantry compare sia in kitchenDetails.features sia in keyRooms, viene richiesta una sola dispensa.

Esempio:

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

🖼️ Immagine di riferimento#

refImageUrl è facoltativo e deve essere direttamente accessibile dal server API.

Requisiti:

• Formato: JPG/JPEG, PNG o WebP.
• Dimensione massima del file: 20 MB.
• Dimensioni minime: 128 × 128 px.
• Dimensioni massime: 6,000 × 6,000 px. Le immagini più grandi vengono ridimensionate proporzionalmente prima dell'elaborazione.

L'immagine di riferimento orienta disposizione, adiacenze, proporzioni o stile visivo. Non prevale sui conteggi strutturati delle stanze né su altri vincoli obbligatori.

🤖 Tipi di modello#

Sono supportati soltanto Base e Pro.

Campi esclusi dal contratto funzionale pubblico#

I client API pubblici non devono fare affidamento sui seguenti campi:

Campi precedenti rimossi che non devono essere inviati:

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

📥 Esempi di creazione di attività#

Richiesta minima con intervalli automatici per le camere da letto#

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

Richiesta completa#

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

Risposta di creazione riuscita dell'attività#

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

2. Ottieni il risultato dell'attività#

Restituisce l'avanzamento dell'attività e l'immagine generata quando disponibile.

Endpoint

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

Intestazioni della richiesta

Parametri di interrogazione

Esempi di richiesta del risultato#

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

Risposta per attività completata#

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

Risposta durante l'elaborazione#

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

Risposta per attività non riuscita#

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

Campi del risultato#

📊 Stato dell'attività#

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

❌ Risposte di errore#

Tutte le risposte di errore usano la struttura comune delle risposte:

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

Consulta il Riferimento dei codici di errore per l'elenco completo degli errori comuni.

🔄 Note sull'integrazione Web#

L'applicazione Web autenticata e API pubblica usano endpoint e metodi di autenticazione differenti:

Le strutture dei campi funzionali sono allineate, ma i client API pubblici devono seguire i limiti del server e il contratto pubblico di questo documento. In particolare:

• I client Web possono includere imageNumbers ed extData interni; i client pubblici non ne hanno bisogno.
• API pubblica determina i metadati delle chiamate API dall'endpoint e dalle credenziali. Campi della richiesta come isApiCall e genByMember non sono necessari.
• balcon è accettato per compatibilità e normalizzato in balcony; le nuove integrazioni devono inviare balcony.
• I limiti attuali del server pubblico restano 0–5 camere da letto e 0.5–4 bagni, anche se un'altra interfaccia offre temporaneamente selettori più ampi.