Kat Planı Oluşturma API Belgeseli#

Temel URL: https://api.ideal.house
Sürüm: v1
Güncellendi: 2026-08-09

📖 Genel Bakış#

Kat Planı Oluşturma API, yapılandırılmış oda gereksinimleri ve isteğe bağlı özel bir istem veya referans görüntüsü kullanılarak tek bir yapay zekâ destekli, siyah-beyaz, üstten görünüm, CAD tarzı konut konsept kat planı oluşturur.

Çıktı, erken aşama yerleşim keşfi için tasarlanmıştır. Bu bir inşaat çizimi değildir ve üretilen ölçüler, geometri, donanım yerleşimi ve yönetmelik uyumluluğu yetkin bir uzman tarafından incelenmelidir.

İş akışı asenkrondur:

1. Görev oluştur — Kat planı parametrelerini gönderin ve bir taskId alın.
2. Sonuçları sorgula — Görev son durumuna ulaşana kadar taskId ile sonuç uç noktasını sorgulayın.

🔐 Kimlik Doğrulama#

Tüm herkese açık API istekleri bir API anahtarı içermelidir.

[!WARNING] API anahtarınızı güvende tutun. İstemci tarafı kodda veya herkese açık depolarda ifşa etmeyin.

💰 Kredi Kesintisi#

Krediler, bir oluşturma görevi başarıyla oluşturulduktan sonra kesilir. Görev nihayetinde başarısız olursa, kesilen krediler otomatik olarak iade edilir. Yetersiz kredi 9051 hata kodunu döndürür.

Flash, Kat Planı API tarafından desteklenmez.

Yaygın faturalama davranışı için Kredi Kesintisi Referansı bölümüne bakın.

📌 API Uç Noktaları#

1. Kat Planı Görevi Oluştur#

Bir kat planı oluşturma görevi oluşturur ve benzersiz bir görev kimliği döndürür.

Uç nokta

POST /api/v1/floorPlan/generate

İstek başlıkları

İstek gövdesi#

[!IMPORTANT] Herkese açık API şu anda bedrooms'ı 0–5 ve bathrooms'i 0.5–4 olarak doğrular. Başka bir istemci arayüzünde kullanılabilir değerler, bu sunucu tarafı sınırları genişletmez.

Genel istek kuralları#

• Tüm enum değerleri büyük/küçük harfe duyarlıdır ve bu belgede gösterilen İngilizce değerleri kullanmalıdır.
• totalArea, ölçeği ve oranları yönlendirmek için kullanılan hedef toplam alandır; kesin bir inşaat ölçüsü olarak ele alınmaz.
• Yapılandırılmış görüntü istemi derlenirken, etkin özel istem ilk 800 karakterle sınırlıdır.
• Yapılandırılmış alanlar, prompt içindeki çelişkili talimatlardan önceliklidir.
• Başarılı bir görev tam olarak bir görüntü oluşturur.

📐 Toplam Alan#

totalArea, bir alan birimiyle izlenen tek bir pozitif sayısal değer içerir.

Birimden önce boşluk bırakılması önerilir. Pozitif ondalık değerler kabul edilir.

Geçerli örnekler:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ Yatak Odası Alan Aralıkları#

bedroomAreaRanges, göreli yatak odası boyutlandırma yönlendirmesi sağlar. Üretilen görüntüde sayısal alan etiketleri talep etmez.

Her öğenin şu şekli vardır:

Açık aralık örneği

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

Boş olmayan bir dizi sağlandığında kurallar:

• Uzunluğu bedrooms'ye eşit olmalıdır.
• Sağlanan her minArea ve maxArea pozitif sayısal bir dize olmalıdır.
• Her iki değer de sağlandığında, minArea <= maxArea.
• Sağlandığında unit, m² veya ft² olmalıdır.
• İsimler korunur. Boş veya null öğeler boyutlandırma yönlendirmesi sağlamaz.

Atlanırken otomatik aralıklar#

Alan atlanabilir veya boş dizi olarak gönderilebilir. Hiçbir öğe etkin bir minArea veya maxArea içermediğinde, yapılandırılmış oluşturma yolu iç yatak odası aralıklarını totalArea ve bedrooms'den türetir:

• Yatak odası alan bütçesi, bir yatak odası için toplam alanın 20%'i olarak başlar.
• Bütçe, her ek yatak odası için 7.5 puan artar ve 50% ile sınırlıdır.
• İlk yatak odası 1.3 boyutlandırma ağırlığı alır; diğer her yatak odası 1.0 ağırlığı alır.
• Her hedef, tam alan birimlerine yuvarlanmış yaklaşık bir ±10% aralığına dönüşür.
• Birim, totalArea'dan devralınır.
• Mevcut boş olmayan oda adları korunur; aksi halde sunucu Room 1, Room 2 vb. kullanır.

200 m² ve 4 yatak odası için mevcut türetilmiş yönlendirme yaklaşık olarak şöyledir:

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

Bu değerler içsel oransal yönlendirmedir, garanti edilen nihai oda alanları değildir. Açıkça belirtilmiş geçerli aralıklar her zaman otomatik aralıklardan önceliklidir.

bedrooms 0 olduğunda, bedroomAreaRanges'ü atlayın veya [] gönderin.

🛁 Banyo Detayları#

bathrooms toplam banyo sayısını temsil eder:

• Tamam sayı kısmı, tam banyo sayısıdır.
• Bir .5 kesri, bir yarım banyo ekler.
• Her tam banyoya tuvalet, lavabo/tezgah ve duş veya ıslak alan içermesi talimatı verilir.
• Yarım banyo yalnızca tuvalet ve lavabo/tezgah içerir; duş veya küvet yoktur.

bathroomDetails yalnızca tam banyoları yapılandırır:

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

Kurallar:

• fullBathroomOptions.length, floor(bathrooms)'dan büyük olamaz.
• Dizi, yalnızca tercihleri seçilen tam banyoları içerebilir.
• Bir null değeri belirtilmemiş anlamına gelir.
• Zorunlu küvet, standart tam banyo donanımlarına ekledir; tuvalet veya duşu değiştirmez.
• Islak/kuru ayrımı, sayılan bir banyonun içindeki iç bölmedir, ek bir banyo değildir.

🍳 Mutfak Detayları#

Tüm kitchenDetails alt alanları isteğe bağlıdır. Mutfak tercihi seçilmediğinde tüm nesneyi atlayın.

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

Kısmi yapılandırma geçerlidir. Örneğin:

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

🚪 Anahtar Odalar#

keyRooms, bu tam değerlerin dizisini kabul eder:

Eski Web değeri balcon de kabul edilir ve balcony olarak normalize edilir.

Kurallar:

• Boş değerler yok sayılır ve yinelenen değerler kaldırılır.
• Seçilen anahtar odalar bir kez talep edilir.
• Seçilmemiş isteğe bağlı alanlar, üretilen oda programından hariç tutulur.
• pantry hem kitchenDetails.features hem de keyRooms içinde görünürse, yalnızca bir kiler talep edilir.

Örnek:

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

🖼️ Referans Görüntüsü#

refImageUrl isteğe bağlıdır ve API sunucusu tarafından doğrudan erişilebilir olmalıdır.

Gereksinimler:

• Biçim: JPG/JPEG, PNG veya WebP.
• Maksimum dosya boyutu: 20 MB.
• Minimum boyutlar: 128 × 128 px.
• Maksimum boyutlar: 6,000 × 6,000 px. Daha büyük görüntüler işlemeden önce orantılı olarak ölçeklenir.

Referans görüntü, yerleşimi, komşuluğu, oranları veya görsel stili yönlendirir. Yapılandırılmış oda sayılarını veya diğer kesin kısıtlamaları geçersiz kılmaz.

🤖 Model Türleri#

Yalnızca Base ve Pro desteklenir.

Herkese açık işlevsel arayüzün kapsamı dışındaki alanlar#

Aşağıdaki alanlara herkese açık API istemcileri tarafından güvenilmemelidir:

Gönderilmemesi gereken kaldırılmış eski alanlar:

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

📥 Görev Oluşturma Örnekleri#

Otomatik yatak odası aralıklarıyla minimal istek#

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

Tam istek#

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

Görev oluşturma başarı yanıtı#

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

2. Görev Sonucunu Al#

Görev ilerlemesini ve mevcut olduğunda üretilen görüntüyü döndürür.

Uç nokta

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

İstek başlıkları

Sorgu parametreleri

Sonuç istek örnekleri#

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

Tamamlanan görev yanıtı#

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

İşleniyor yanıtı#

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

Başarısız görev yanıtı#

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

Sonuç alanları#

📊 Görev Durumu#

Her 3–5 saniyede sorgulayın. API Görev Sınırı bölümüne bakın.

❌ Hata Yanıtları#

Tüm hata yanıtları ortak yanıt yapısını kullanır:

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

Tamamlayıcı ortak hata listesi için Hata Kodu Referansı bölümüne bakın.

🔄 Web Entegrasyon Notları#

Kimlik doğrulanmış Web uygulaması ve herkese açık API farklı uç noktalar ve kimlik doğrulama yöntemleri kullanır:

İş alanı şekilleri uyumludur, ancak herkese açık API istemcileri bu belgedeki sunucu tarafı sınırları ve herkese açık sözleşmeyi takip etmelidir. Özellikle:

• Web istemcileri iç imageNumbers ve extData içerebilir; herkese açık istemciler bunlara ihtiyaç duymaz.
• Herkese açık API, API-çağrı verilerini uç nokta ve kimlik bilgileri tarafından belirler. isApiCall ve genByMember gibi istek alanları gereksizdir.
• balcon, uyumluluk için kabul edilir ve balcony olarak normalize edilir; yeni entegrasyonlar balcony göndermelidir.
• Mevcut herkese açık sunucu sınırları, başka bir arayüz geçici olarak daha geniş seçiciler sunsa bile 0–5 yatak odası ve 0.5–4 banyo olarak kalır.