दस्तावेज़ीकरण: फ़्लोर प्लान जनरेशन API#

बेस URL: https://api.ideal.house
संस्करण: v1
अपडेट किया गया: 2026-08-09

📖 अवलोकन#

फ़्लोर प्लान जनरेशन API संरचित कमरे की आवश्यकताओं और वैकल्पिक कस्टम प्रॉम्प्ट या संदर्भ इमेज से एक AI-जनरेटेड, काला-सफ़ेद, टॉप-डाउन, CAD-शैली का निवासी कॉन्सेप्ट फ़्लोर प्लान बनाता है।

आउटपुट प्रारंभिक लेआउट एक्सप्लोरेशन के लिए है। यह एक कंस्ट्रक्शन ड्रॉइंग नहीं है, और जनरेटेड आयाम, ज्यामिति, फिक्स्चर प्लेसमेंट, और कोड अनुपालन की समीक्षा एक योग्य पेशेवर को करानी होगी।

वर्कफ़्लो असिंक्रोनस है:

1. टास्क बनाएँ — फ़्लोर प्लान पैरामीटर सबमिट करें और taskId प्राप्त करें।
2. परिणामों के लिए पोल करें — टास्क टर्मिनल स्टेटस तक पहुँचने तक taskId के साथ रिज़ल्ट एंडपॉइंट को क्वेरी करें।

🔐 प्रमाणीकरण#

सभी सार्वजनिक API अनुरोधों में एक API कुंजी शामिल होनी चाहिए।

[!WARNING] अपनी API कुंजी सुरक्षित रखें। इसे क्लाइंट-साइड कोड या सार्वजनिक रिपॉज़िटरी में उजागर न करें।

💰 क्रेडिट कटौती#

जनरेशन टास्क सफलतापूर्वक बनने के बाद क्रेडिट कटते हैं। यदि टास्क अंततः विफल होता है, तो कटे गए क्रेडिट स्वतः रिफंड किए जाते हैं। अपर्याप्त क्रेडिट पर एरर कोड 9051 लौटता है।

फ़्लोर प्लान API में Flash का समर्थन नहीं है।

सामान्य बिलिंग व्यवहार के लिए क्रेडिट कटौती संदर्भ देखें।

📌 API एंडपॉइंट#

1. फ़्लोर प्लान टास्क बनाएँ#

फ़्लोर प्लान जनरेशन टास्क बनाता है और एक यूनिक टास्क आईडी लौटता है।

एंडपॉइंट

POST /api/v1/floorPlan/generate

रिक्वेस्ट हेडर

रिक्वेस्ट बॉडी#

[!IMPORTANT] पब्लिक API वर्तमान में bedrooms को 0–5 और bathrooms को 0.5–4 के रूप में वैलिडेट करता है। किसी अन्य क्लाइंट UI में उपलब्ध मान इन सर्वर-साइड लिमिट्स को विस्तारित नहीं करते।

सामान्य रिक्वेस्ट नियम#

• सभी एनम मानों में बड़े और छोटे अक्षरों का अंतर मायने रखता है और इस दस्तावेज़ में दिए गए अंग्रेज़ी मानों का ही उपयोग करना होगा।
• totalArea एक टार्गेट टोटल एरिया है जो स्केल और अनुपातों को निर्देशित करता है; इसे एक सटीक कंस्ट्रक्शन डायमेंशन के रूप में नहीं माना जाता।
• जब संरचित इमेज प्रॉम्प्ट एकत्रित किया जाता है, तो प्रभावी कस्टम प्रॉम्प्ट को पहले 800 कैरेक्टर तक सीमित किया जाता है।
• संरचित फ़ील्ड्स, prompt में टकराव वाले निर्देशों पर प्राथमिकता रखती हैं।
• एक सफल टास्क ठीक एक इमेज जनरेट करता है।

📐 टोटल एरिया#

totalArea में एक पॉज़िटिव न्यूमेरिक मान के बाद एक एरिया यूनिट होती है।

यूनिट से पहले व्हाइटस्पेस की सिफ़ारिश की जाती है। पॉज़िटिव होने पर डेसिमल मान स्वीकार किए जाते हैं।

मान्य उदाहरण:

{
  "totalArea": "200 m²"
}

{
  "totalArea": "1850 ft²"
}

🛏️ बेडरूम एरिया रेंज#

bedroomAreaRanges सापेक्ष बेडरूम साइज़िंग गाइडेंस प्रदान करता है। यह जनरेटेड इमेज में न्यूमेरिक एरिया लेबल का अनुरोध नहीं करता।

प्रत्येक आइटम का आकार इस प्रकार है:

स्पष्ट रेंज उदाहरण

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

जब एक नॉन-इम्प्टी एरेई सप्लाई की जाती है, नियम:

• इसकी लंबाई bedrooms के बराबर होनी चाहिए।
• प्रत्येक सप्लाई किए गए minArea और maxArea एक पॉज़िटिव न्यूमेरिक स्ट्रिंग होना चाहिए।
• जब दोनों मान सप्लाई किए जाते हैं, तो minArea <= maxArea।
• unit, यदि सप्लाई किया गया है, तो m² या ft² होना चाहिए।
• नामों को सुरक्षित रखा जाता है। खाली या नल आइटम साइज़िंग गाइडेंस प्रदान नहीं करते।

छोड़े जाने पर ऑटोमेटिक रेंज#

फ़ील्ड को छोड़ा जा सकता है या एक खाली एरेई के रूप में भेजा जा सकता है। जब कोई आइटम प्रभावी minArea या maxArea नहीं रखता, तो संरचित जनरेशन पाथ totalArea और bedrooms से आंतरिक बेडरूम रेंज व्युत्पन्न करता है:

• एक बेडरूम के लिए बेडरूम एरिया बजट टोटल एरिया का 20% से शुरू होता है।
• प्रत्येक अतिरिक्त बेडरूम के लिए बजट 7.5 प्रतिशत पॉइंट्स से बढ़ता है, सीमा 50% तक।
• पहले बेडरूम को 1.3 साइज़िंग वेट मिलता है; प्रत्येक अन्य बेडरूम को 1.0 वेट मिलता है।
• प्रत्येक टार्गेट एक अनुमानित ±10% रेंज बन जाता है, जो पूरे एरिया यूनिट्स तक राउंड किया जाता है।
• यूनिट totalArea से वंशित होती है।
• मौजूदा नॉन-इम्प्टी रूम नामों को रखा जाता है; अन्यथा सर्वर Room 1, Room 2, आदि का उपयोग करता है।

200 m² और 4 बेडरूम के लिए, वर्तमान व्युत्पन्न गाइडेंस लगभग इस प्रकार है:

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

ये मान आंतरिक प्रोपोर्शनल गाइडेंस हैं, गारंटीड फ़ाइनल रूम एरिया नहीं। स्पष्ट मान्य रेंज हमेशा ऑटोमेटिक रेंज पर प्राथमिकता रखती हैं।

जब bedrooms 0 है, तो bedroomAreaRanges को छोड़ें या [] भेजें।

🛁 बाथरूम विवरण#

bathrooms कुल बाथरूम संख्या का प्रतिनिधित्व करता है:

• इसका इंटीजर भाग फुल बाथरूमों की संख्या है।
• एक .5 फ्रैक्शन एक हॉफ़ बाथरूम जोड़ता है।
• प्रत्येक फुल बाथरूम में टॉइलेट, वैनटी/सिंक, और शावर या वेट एरिया शामिल करने का निर्देश दिया जाता है।
• हॉफ़ बाथरूम में केवल टॉइलेट और वैनटी/सिंक होता है, शावर या बथटब नहीं।

bathroomDetails केवल फुल बाथरूम कॉन्फ़िगर करता है:

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

नियम:

• fullBathroomOptions.length floor(bathrooms) से अधिक नहीं हो सकता।
• ऐरे में केवल उन फुल बाथरूमों को शामिल किया जा सकता है जिनके लिए प्राथमिकताएँ चुनी गई हैं।
• एक null मान का अर्थ है निर्दिष्ट नहीं।
• एक आवश्यक बथटब मानक फुल-बाथरूम फिक्स्चर्स के अतिरिक्त है; यह टॉइलेट या शावर की जगह नहीं लेता।
• वेट/ड्राई सेपरेशन गिने गए बाथरूम के भीतर एक आंतरिक पार्तिशन है, एक अतिरिक्त बाथरूम नहीं।

🍳 किचन विवरण#

सभी kitchenDetails चाइल्ड फ़ील्ड्स वैकल्पिक हैं। जब कोई किचन प्राथमिकता चुनी नहीं जाती, तो पूरा ऑब्जेक्ट छोड़ें।

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

आंशिक कॉन्फ़िगरेशन मान्य है। उदाहरण के लिए:

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

🚪 मुख्य कमरे#

keyRooms इन सटीक मानों की एक ऐरे स्वीकार करता है:

लीगेसी वेब मान balcon को भी स्वीकार किया जाता है और इसे balcony में नॉर्मलाइज़ किया जाता है।

नियम:

• खाली मानों को अनदेखा किया जाता है और डुप्लिकेट मानों को हटा दिया जाता है।
• चुने गए मुख्य कमरों का एक बार अनुरोध किया जाता है।
• अचुने गए वैकल्पिक स्पेस को जनरेटेड रूम प्रोग्राम से बाहर रखा जाता है।
• यदि pantry दोनों kitchenDetails.features और keyRooms में प्रकट होता है, तो केवल एक पैंट्री का अनुरोध किया जाता है।

उदाहरण:

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

🖼️ संदर्भ इमेज#

refImageUrl वैकल्पिक है और API सर्वर द्वारा सीधे एक्सेसिबल होना चाहिए।

आवश्यकताएँ:

• फ़ॉर्मेट: JPG/JPEG, PNG, या WebP।
• अधिकतम फ़ाइल साइज़: 20 MB।
• न्यूनतम डायमेंशन: 128 × 128 px।
• अधिकतम डायमेंशन: 6,000 × 6,000 px। बड़ी इमेज प्रोसेसिंग से पहले प्रोपोर्शनली स्केल की जाती हैं।

संदर्भ इमेज लेआउट, एडजेसेंसी, अनुपात, या विज़ुअल स्टाइल को निर्देशित करती है। यह संरचित रूम गणनाओं या अन्य हार्ड कन्स्ट्रेंट्स को ओवरराइड नहीं करती।

🤖 मॉडल टाइप्स#

केवल Base और Pro का समर्थन है।

सार्वजनिक उपयोग के अनुबंध में शामिल न होने वाले फ़ील्ड#

सार्वजनिक API क्लाइंट को निम्नलिखित फ़ील्ड पर निर्भर नहीं होना चाहिए:

हटाए गए लीगेसी फ़ील्ड्स जिन्हें भेजना नहीं चाहिए:

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

📥 टास्क बनाने के उदाहरण#

ऑटोमेटिक बेडरूम रेंज के साथ न्यूनतम रिक्वेस्ट#

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

पूर्ण रिक्वेस्ट#

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

टास्क बनाने का सफल रिस्पॉन्स#

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

2. टास्क रिज़ल्ट प्राप्त करें#

टास्क प्रोग्रेस और उपलब्ध होने पर जनरेटेड इमेज लौटता है।

एंडपॉइंट

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

रिक्वेस्ट हेडर

क्वेरी पैरामीटर

रिज़ल्ट रिक्वेस्ट उदाहरण#

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

पूर्ण टास्क रिस्पॉन्स#

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

प्रोसेसिंग रिस्पॉन्स#

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

विफल टास्क रिस्पॉन्स#

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

रिज़ल्ट फ़ील्ड्स#

📊 टास्क स्टेटस#

हर **3–5 सेकंड ** में स्थिति की जाँच करें। API कार्य सीमा देखें।

❌ एरर रिस्पॉन्स#

सभी एरर रिस्पॉन्स सामान्य रिस्पॉन्स स्ट्रक्चर का उपयोग करते हैं:

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

पूर्ण सामान्य एरर सूची के लिए एरर कोड संदर्भ देखें।

🔄 वेब इंटीग्रेशन नोट्स#

ऑथेंटिकेटेड वेब एप्लिकेशन और पब्लिक API अलग-अलग एंडपॉइंट्स और प्रमाणीकरण विधियों का उपयोग करते हैं:

बिज़नेस फ़ील्ड आकार संरेखित हैं, लेकिन पब्लिक API क्लाइंट्स को इस दस्तावेज़ में सर्वर-साइड लिमिट्स और पब्लिक कॉन्ट्रैक्ट का पालन करना चाहिए। विशेष रूप से:

• वेब क्लाइंट्स आंतरिक imageNumbers और extData शामिल कर सकते हैं; पब्लिक क्लाइंट्स को उनकी आवश्यकता नहीं है।
• पब्लिक API एंडपॉइंट और क्रेडेंशियल्स से API-कॉल मेटाडेटा निर्धारित करता है। isApiCall और genByMember जैसे रिक्वेस्ट फ़ील्ड्स आवश्यक नहीं हैं।
• balcon को संगतता के लिए स्वीकार किया जाता है और balcony में नॉर्मलाइज़ किया जाता है; नई इंटीग्रेशन balcony भेजनी चाहिए।
• वर्तमान पब्लिक सर्वर लिमिट्स 0–5 बेडरूम और 0.5–4 बाथरूम रहती हैं, भले ही कोई अन्य UI अस्थायी रूप से चौड़े सिलेक्टर प्रस्तुत करे।