เอกสาร API การสร้างแปลนชั้น#

URLพื้นฐาน: https://api.ideal.house
เวอร์ชัน: v1
อัปเดต: 2026-08-09

📖 ภาพรวม#

การเจนเนอเรทแปลนชั้น API สร้างแปลนบ้านแนวคิดแบบ CAD มองจากด้านบน สีดำ-ขาว ที่สร้างโดย AI ขึ้นหนึ่งฉบับ จากข้อกำหนดห้องแบบโครงสร้าง และพรอมต์กำหนดเองหรือภาพอ้างอิงแบบไม่บังคับ

ผลลัพธ์มีไว้สำหรับการสำรวจเลย์เอาต์เบื้องต้น ไม่ใช่แบบก่อสร้าง และขนาดเรขาคณิต ตำแหน่งอุปกรณ์ และความสอดคล้องกับมาตรฐานที่สร้างขึ้นมาต้องได้รับการตรวจสอบโดยผู้เชี่ยวชาญที่มีคุณสมบัติเหมาะสม

เวิร์กโฟลว์เป็นแบบอะซิงโครนัส:

1. สร้างงาน — ส่งพารามิเตอร์แปลนชั้นและรับ taskId
2. ตรวจสอบผลลัพธ์ — สอบถามจุดปลายทางผลลัพธ์ด้วย taskId จนกว่างานจะถึงสถานะสิ้นสุด

🔐 การรับรองความถูกต้อง#

คำขอ API สาธารณะทั้งหมดต้องรวมคีย์ API

[!WARNING] รักษาความปลอดภัยของคีย์ API ของคุณ อย่าเปิดเผยในโค้ดฝั่งไคลเอนต์หรือคลังสาธารณะ

💰 การหักเครดิต#

เครดิตจะถูกหักหลังจากสร้างรายการงานสำเร็จ หากงานนั้นล้มเหลวในภายหลัง เครดิตที่หักไปจะถูกคืนโดยอัตโนมัติ หากเครดิตไม่เพียงพอ ระบบจะส่งคืนรหัสข้อผิดพลาด 9051

Flash ไม่รองรับใน API แปลนชั้น

ดู เอกสารอ้างอิงการหักเครดิต สำหรับพฤติกรรมบิลลิ่งทั่วไป

📌 จุดปลายทาง API#

1. สร้างงานแปลนชั้น#

สร้างงานสร้างแปลนชั้นและคืน ID งานที่ไม่ซ้ำกัน

จุดปลายทาง

POST /api/v1/floorPlan/generate

หัวข้อความขอ

เนื้อหาคำขอ#

[!IMPORTANT] API สาธารณะปัจจุบันตรวจสอบ bedrooms เป็น 0–5 และ bathrooms เป็น 0.5–4 ค่าที่มีอยู่ใน UI ฝั่งไคลเอนต์อื่นจะไม่ขยายขีดจำกัดฝั่งเซิร์ฟเวอร์เหล่านี้

กฎคำขอทั่วไป#

• ค่า enum ทั้งหมดมีความไวต่อตัวพิมพ์ใหญ่-เล็ก และต้องใช้ค่าภาษาอังกฤษตามที่แสดงไว้ในเอกสารนี้
• 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 รับอาร์เรย์ของค่าเหล่านี้เท่านั้น:

ค่า Web แบบเดิม 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}

หัวข้อความขอ

พารามิเตอร์ Query

ตัวอย่างคำขอผลลัพธ์#

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
}

ดู เอกสารอ้างอิงรหัสข้อผิดพลาด สำหรับรายการข้อผิดพลาดทั่วไปทั้งหมด

🔄 หมายเหตุการรวมระบบ Web#

แอปพลิเคชัน Web ที่รับรองความถูกต้องแล้วและ API สาธารณะใช้จุดปลายทางและวิธีการรับรองความถูกต้องที่แตกต่างกัน:

รูปร่างฟิลด์ธุรกิจสอดคล้องกัน แต่ไคลเอนต์ API สาธารณะควรปฏิบัติตามขีดจำกัดฝั่งเซิร์ฟเวอร์และสัญญาสาธารณะในเอกสารนี้ โดยเฉพาะ:

• ไคลเอนต์ Web อาจรวม imageNumbers และ extData ภายใน; ไคลเอนต์สาธารณะไม่จำเป็นต้องมี
• API สาธารณะกำหนดเมทาดาทาการเรียก API จากจุดปลายทางและข้อมูลรับรอง ฟิลด์คำขอเช่น isApiCall และ genByMember ไม่จำเป็น
• balcon ยอมรับเพื่อเข้ากันได้และปรับให้เป็น balcony; การรวมระบบใหม่ควรส่ง balcony
• ขีดจำกัดเซิร์ฟเวอร์สาธารณะปัจจุบันยังคงเป็น 0–5 ห้องนอนและ 0.5–4 ห้องน้ำ แม้ UI อื่นจะแสดงตัวเลือกที่กว้างขึ้นชั่วคราว