Dokumentacja API generowania rzutów pomieszczeń#

Podstawowy URL: https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-08-09

📖 Przegląd#

API generowania rzutów pomieszczeń tworzy jeden wygenerowany przez AI, czarno-biały, widok z góry, koncepcyjny rzut mieszkania w stylu CAD na podstawie ustrukturyzowanych wymagań dotyczących pomieszczeń oraz opcjonalnego niestandardowego polecenia lub obrazu referencyjnego.

Wynik służy do wstępnego opracowania układu. Nie jest to rysunek budowlany, a wygenerowane wymiary, geometria, rozmieszczenie wyposażenia oraz zgodność z przepisami muszą zostać zweryfikowane przez wykwalifikowanego specjalistę.

Praca jest asynchroniczna:

1. Utwórz zadanie — Prześlij parametry planu pomieszczeń i otrzymaj taskId.
2. Sprawdzaj wyniki — Wykonuj cykliczne sprawdzanie stanu w punkcie końcowym wyników za pomocą taskId, aż zadanie osiągnie status końcowy.

🔐 Uwierzytelnianie#

Wszystkie publiczne żądania API muszą zawierać klucz API.

[!WARNING] Zachowaj swój klucz API w poufności. Nie ujawniaj go w kodzie po stronie klienta ani w publicznych repozytoriach.

💰 Odejmowanie kredytów#

Kredyty są odejmowane po pomyślnym utworzeniu zadania generowania. Jeśli zadanie ostatecznie się nie powiedzie, odejęte kredyty zostaną automatycznie zwrócone. Niewystarczające kredyty zwracają kod błędu 9051.

Wariant Flash nie jest obsługiwany przez API generowania rzutów pomieszczeń.

Zobacz Referencja odejmowania kredytów w celu zapoznania się z powszechnym zachowaniem rozliczeniowym.

📌 Punkty końcowe API#

1. Utworzenie zadania planu pomieszczeń#

Tworzy zadanie generowania planu pomieszczeń i zwraca unikalny identyfikator zadania.

Punkt końcowy

POST /api/v1/floorPlan/generate

Nagłówki żądania

Ciało żądania#

[!IMPORTANT] Publiczne API aktualnie waliduje bedrooms jako 0–5 oraz bathrooms jako 0.5–4. Wartości dostępne w innym interfejsie klienta nie rozszerzają tych ograniczeń po stronie serwera.

Zasady ogólne żądania#

• Wszystkie wartości wyliczeń są wrażliwe na wielkość liter i muszą używać wartości angielskich pokazanych w tym dokumencie.
• totalArea to docelowa powierzchnia całkowita używana do określania skali i proporcji; nie jest traktowana jako dokładny wymiar budowlany.
• Skuteczne niestandardowe polecenie jest ograniczone do pierwszych 800 znaków podczas składania ustrukturyzowanego polecenia obrazowego.
• Pola ustrukturyzowane mają pierwszeństwo przed sprzecznymi instrukcjami w prompt.
• Pomyślne zadanie generuje dokładnie jeden obraz.

📐 Łączny obszar#

totalArea zawiera jedną dodatnią wartość numeryczną połączoną z jednostką obszaru.

Zaleca się spacje przed jednostką. Wartości dziesiętne są akceptowane, jeśli są dodatnie.

Poprawne przykłady:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ Zakresy obszarów sypialni#

bedroomAreaRanges określa względne wielkości sypialni. Nie stanowi żądania umieszczenia liczbowych oznaczeń powierzchni na wygenerowanym obrazie.

Każdy element ma następującą strukturę:

Przykład wprost z zakresu

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

Zasady, gdy dostarczono niepusty tablicę:

• Jego długość musi być równa bedrooms.
• Każdy dostarczony minArea i maxArea musi być dodatnim ciągiem numerycznym.
• Gdy dostarczono obie wartości, minArea <= maxArea.
• unit, gdy dostarczony, musi być m² lub ft².
• Nazwy są zachowywane. Puste lub null elementy nie dostarczają wytycznych dotyczących rozmiaru.

Automatyczne zakresy, gdy pominięte#

Pole może zostać pominięte lub wysłane jako pusta tablica. Gdy żaden element nie zawiera skutecznego minArea lub maxArea, ścieżka ustrukturyzowanego generowania wyprowadza wewnętrzne zakresy sypialni z totalArea i bedrooms:

• Budżet obszaru sypialni zaczyna się od 20% łącznego obszaru dla jednej sypialni.
• Budżet zwiększa się o 7.5 punktów procentowych dla każdej dodatkowej sypialni, z limitem 50%.
• Pierwsza sypialnia otrzymuje wagę rozmiaru 1.3; każda inna sypialnia otrzymuje wagę 1.0.
• Każdy cel staje się przybliżonym zakresem ±10%, zaokrąglonym do całkowitych jednostek obszaru.
• Jednostka jest dziedziczona z totalArea.
• Istniejące niepuste nazwy pomieszczeń są zachowywane; w przeciwnym razie serwer używa Room 1, Room 2 itd.

Dla 200 m² i 4 sypialni, bieżące wyprowadzone wytyczne wynoszą przybliżenie:

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

Wartości te są wewnętrznymi wytycznymi proporcjonalnymi, a nie gwarantowanymi końcowymi obszarami pomieszczeń. Wprost podane poprawne zakresy zawsze mają pierwszeństwo przed zakresami automatycznymi.

Gdy bedrooms wynosi 0, pomiń bedroomAreaRanges lub wyślij [].

🛁 Szczegóły łazienek#

bathrooms reprezentuje łączną liczbę łazienek:

• Jego część całkowita to liczba pełnych łazienek.
• Ułamek .5 dodaje jedną półłazienkę.
• Każda pełna łazienka jest projektowana tak, aby zawierała toaletę, umywalkę/zlew oraz prysznic lub strefę mokry.
• Półłazienka to pomieszczenie zawierające tylko sedes i szafkę z umywalką lub umywalkę, bez prysznica ani wanny.

bathroomDetails konfiguruje wyłącznie pełne łazienki:

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

Zasady:

• fullBathroomOptions.length nie może przekraczać floor(bathrooms).
• Tablica może zawierać wyłącznie pełne łazienki, dla których wybrano preferencje.
• Wartość null oznacza brak określenia.
• Wymagana wanna jest dodatkowa do standardowego wyposażenia pełnej łazienki; nie zastępuje toalety ani prysznica.
• Separacja mokra/sucha to wewnętrzna przegroda wewnątrz liczonej łazienki, a nie dodatkowa łazienka.

🍳 Szczegóły kuchni#

Wszystkie pola podrzędne kitchenDetails są opcjonalne. Pomiń cały obiekt, gdy nie wybrano preferencji dotyczących kuchni.

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

Częściowa konfiguracja jest poprawna. Na przykład:

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

🚪 Kluczowe pomieszczenia#

keyRooms akceptuje tablicę tych dokładnych wartości:

Dziedziczna wartość Web balcon jest również akceptowana i normalizowana do balcony.

Zasady:

• Puste wartości są ignorowane, a wartości duplikowane są usuwane.
• Wybrane kluczowe pomieszczenia są wymagane raz.
• Niewybrane opcjonalne przestrzenie są wykluczone z wygenerowanego programu pomieszczeń.
• Jeśli pantry pojawia się zarówno w kitchenDetails.features, jak i w keyRooms, wymagana jest tylko jedna spiżarnia.

Przykład:

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

🖼️ Obraz referencyjny#

refImageUrl jest opcjonalny i musi być bezpośrednio dostępny dla serwera API.

Wymagania:

• Format: JPG/JPEG, PNG lub WebP.
• Maksymalny rozmiar pliku: 20 MB.
• Minimalne wymiary: 128 × 128 px.
• Maksymalne wymiary: 6,000 × 6,000 px. Większe obrazy są skalowane proporcjonalnie przed przetwarzaniem.

Obraz referencyjny wytycza układ, sąsiedztwo, proporcje lub styl wizualny. Nie nadpisuje ustrukturyzowanych liczb pomieszczeń ani innych sztywnych ograniczeń.

🤖 Typy modeli#

Obsługiwane są wyłącznie Base i Pro.

Pola poza publiczną specyfikacją#

Następujących pól nie należy używać w publicznych klientach API:

Usunięte przestarzałe pola, których nie należy wysyłać:

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

📥 Przykłady tworzenia zadania#

Minimalne żądanie z automatycznymi zakresami sypialni#

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

Pełne żądanie#

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

Odpowiedź o pomyślnym utworzeniu zadania#

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

2. Pobranie wyniku zadania#

Zwraca postęp zadania i wygenerowany obraz, gdy jest dostępny.

Punkt końcowy

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

Nagłówki żądania

Parametry zapytania

Przykłady żądań wyników#

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

Odpowiedź dla zakończonego zadania#

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

Odpowiedź podczas przetwarzania#

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

Odpowiedź dla niepowiedzonego zadania#

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

Pola wyników#

📊 Status zadania#

Wykonuj cykliczne sprawdzanie co 3–5 sekund. Zobacz Limit zadań API.

❌ Odpowiedzi błędów#

Wszystkie odpowiedzi błędów używają wspólnej struktury odpowiedzi:

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

Zobacz Referencja kodów błędów w celu zapoznania się z pełną listą powszechnych błędów.

🔄 Uwagi dotyczące integracji Web#

Uwierzytelniona aplikacja Web i publiczne API używają różnych punktów końcowych i metod uwierzytelniania:

Struktury pól biznesowych są spójne, ale publiczni klienci API powinni przestrzegać ograniczeń po stronie serwera i publicznego kontraktu w tym dokumencie. W szczególności:

• Klienci Web mogą zawierać wewnętrzne imageNumbers i extData; publiczni klienci ich nie potrzebują.
• Publiczne API określa metadane wywołania API z punktu końcowego i danych uwierzytelniających. Pola żądania, takie jak isApiCall i genByMember, są niepotrzebne.
• balcon jest akceptowane ze względów kompatybilności i normalizowane do balcony; nowe integracje powinny wysyłać balcony.
• Bieżące publiczne ograniczenia serwera pozostają na poziomie 0–5 sypialni i 0.5–4 łazienek, nawet jeśli inny interfejs tymczasowo prezentuje szersze selektory.