توثيق API إنشاء مخططات توزيع المساحات#

URL الأساسي: https://api.ideal.house
الإصدار: v1
آخر تحديث: 2026-08-09

📖 نظرة عامة#

تُولّد API إنشاء مخططات توزيع المساحات مخطط طابق مفاهيمي سكني واحداً باللونين الأسود والأبيض ومن منظور علوي وبأسلوب CAD، بناءً على متطلبات غرف منظمة وتوجيه نصي مخصصة اختيارية أو صورة مرجعية.

النواتج مخصصة للاستكشاف الأولي للتخطيط. ليست مرسوماً إنشائياً، ويجب على مختص مؤهل مراجعة الأبعاد والهندسة المُولَّدة ومواضع التجهيزات الثابتة والتوافق مع اللوائح.

سير العمل غير متزامن:

1. إنشاء مهمة — قدّم معلمات مخطط الطابق واحصل على taskId.
2. استعلم عن النتائج دورياً — استعلم عن نقطة نهاية النتائج باستخدام taskId حتى تصل المهمة إلى حالة نهائية.

🔐 المصادقة#

يجب أن تتضمن جميع طلبات API العامة مفتاح API.

[!WARNING] احتفظ بمفتاح API الخاص بك بأمان. لا تكشفه في أكواد جانب العميل أو المستودعات العامة.

💰 خصم الرصيد#

يتم خصم الرصيد بعد إنشاء مهمة التوليد بنجاح. إذا فشلت المهمة في النهاية، يتم رد الرصيد المخصوم تلقائياً. إرجاع رصيد غير كافٍ رمز الخطأ 9051.

لا يدعم Flash بواسطة API مخططات توزيع المساحات.

انظر مرجع خصم الرصيد لسلوك الفوترة الشائع.

📌 نقاط نهاية API#

1. إنشاء مهمة مخطط طابق#

تُنشئ مهمة توليد مخطط طابق وتُعيد معرف مهمة فريد.

نقطة النهاية

POST /api/v1/floorPlan/generate

رؤوس الطلب

جسم الطلب#

[!IMPORTANT] يُتحقق حالياً من bedrooms كـ 0–5 و bathrooms كـ 0.5–4 بواسطة API العام. لا توسع القيم المتاحة في واجهة مستخدم عميل آخر هذه الحدود الخدمية.

قواعد الطلب العامة#

• جميع قيم النطاق حساسة لحالة الأحرف ويجب أن تستخدم القيم الإنجليزية المعروضة في هذا المستند.
• 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².
• يتم الحفاظ على الأسماء. العناصر الفارغة أو null لا توفر إرشادات لتحديد المساحة.

مدى تلقائي عند حذفه#

يمكن حذف الحقل أو إرساله كمصفوفة فارغة. عندما لا يحتوي أي عنصر على 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 ميجابايت.
• الحد الأدنى للأبعاد: 128 × 128 بكسل.
• الحد الأقصى للأبعاد: 6,000 × 6,000 بكسل. يتم تصغير الصور الأكبر حجماً بشكل متناسب قبل المعالجة.

تُوجّه الصورة المرجعية التخطيط، والتجاور، والتناسب، أو النمط البصري. لا تتجاوز عدّ الغرف المنظمة أو القيود الصلبة الأخرى.

🤖 أنواع النموذج#

يتم دعم 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 من الحمامات حتى لو عرضت واجهة مستخدم أخرى مؤقتاً منتقي أوسع.