Floor Plan Generation API Documentation

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-03-06

📖 Overview

The Floor Plan Generation API allows you to create AI-generated floor plan images based on room configuration parameters such as bedrooms, bathrooms, kitchen type, gross area, and extra functional spaces. The workflow is asynchronous and involves two steps:

Create a task — Submit your floor plan parameters and receive a taskId.
Poll for results — Use the taskId to query task status and retrieve the generated floor plan image.

🔐 Authentication

All API requests must be authenticated using an API Key.

Include your API Key in the request header:

Header	Value
`APIKEY`	`your_api_key_here`

⚠️ Keep your API Key secure. Do not expose it in client-side code or public repositories.

💰 Credits Deduction

[!WARNING] 🪙 Credits are deducted based on the selected modelType upon successful task creation. If the task ultimately fails, the deducted credits will be automatically refunded to your account.
Insufficient credits will return error code 9051. 📄 See Credits Deduction Reference.

Model (`modelType`)	Credits Deducted
`Base`	10 credits
`Pro`	20 credits

📌 API Endpoints

1. Create Floor Plan Task

Creates a new AI floor plan generation task and returns a unique taskId for polling.

Endpoint

POST /api/v1/floorPlan/generate

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key
`Content-Type`	✅ Yes	`application/json`

Request Body

Field	Type	Required	Description
`bedrooms`	`integer`	❌ Optional	Number of bedrooms. Defaults to `2`
`bathrooms`	`integer`	❌ Optional	Number of bathrooms. Defaults to `1`
`kitchenType`	`string`	❌ Optional	Kitchen layout type. Defaults to `open`. Common values: `open`, `closed`
`grossArea`	`string`	❌ Optional	Gross floor area range. Supports metric (m²) and imperial (ft²) values. See Gross Area Options
`extras`	`string`	❌ Optional	Extra functional spaces, multiple values joined with commas. See Extras Options
`prompt`	`string`	❌ Optional	Custom text prompt to further guide the floor plan generation
`refImageUrl`	`string`	❌ Optional	URL of a reference floor plan image to guide the generation
`modelType`	`string`	❌ Optional	Model quality type. Enum: `Base`, `Pro`. Defaults to `Base`. ⚠️ `Flash` mode is not supported

📐 Gross Area Options

The grossArea field accepts predefined range values in either metric (m²) or imperial (ft²) units. You may also enter a custom value.

Metric (m²)

Value	Description
`< 50m²`	Less than 50 square meters
`50-80m²`	50 to 80 square meters
`80-100m²`	80 to 100 square meters
`100-120m²`	100 to 120 square meters
`120-150m²`	120 to 150 square meters
`> 150m²`	Greater than 150 square meters

Imperial (ft²)

Value	Description
`< 540ft²`	Less than 540 square feet
`540-860ft²`	540 to 860 square feet
`860-1,080ft²`	860 to 1080 square feet
`1,080-1,290ft²²`	1080 to 1290 square feet
`1,290-1,610ft²`	1290 to 1610 square feet
`> 1,610ft²`	Greater than 1615 square feet

💡 You can also provide a custom value such as "90m²" or "1000ft²".

🏠 Extras Options

The extras field accepts one or more of the following values. When selecting multiple options, join them with a comma (,).

Value	Description
`walk-in closet`	Walk-in wardrobe / dressing room
`laundry room`	Dedicated laundry space
`storage room`	Storage or utility storage room
`utility room`	Utility / service room
`home office`	Home office / study room
`garage`	Garage
`pantry`	Pantry / food storage area
`combined living-dining`	Open-plan combined living and dining room
`balcony`	Balcony

Examples

"extras": "walk-in closet,laundry room,home office"
"extras": "garage,balcony"
"extras": "pantry,storage room,utility room"

💡 You can also provide custom descriptions not listed above.

Model Types

Value	Description
`Base`	Default. Balanced speed and quality
`Pro`	Higher quality output, slower generation

⚠️ Note: Flash mode is not available for this API. Only Base and Pro are supported.

📥 Request Examples

cURL

# Basic request with default settings
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,
    "kitchenType": "open",
    "grossArea": "100-120m²",
    "extras": "walk-in closet,laundry room,home office",
    "modelType": "Base"
  }'

# Pro model with reference image and custom prompt
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": 3,
    "kitchenType": "closed",
    "grossArea": "> 150m²",
    "extras": "garage,pantry,storage room,balcony",
    "prompt": "Modern open-plan layout with large windows",
    "refImageUrl": "https://example.com/reference-floorplan.jpg",
    "modelType": "Pro"
  }'

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

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 IOException {
        OkHttpClient client = new OkHttpClient();

        String requestBody = """
            {
                "bedrooms": 3,
                "bathrooms": 2,
                "kitchenType": "open",
                "grossArea": "100-120m²",
                "extras": "walk-in closet,laundry room,home office",
                "modelType": "Base"
            }
            """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/floorPlan/generate")
            .addHeader("APIKEY", API_KEY)
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "bedrooms": 3,
    "bathrooms": 2,
    "kitchenType": "open",
    "grossArea": "100-120m²",
    "extras": "walk-in closet,laundry room,home office",
    "modelType": "Base"
}

# Pro model with reference image and custom prompt
# payload = {
#     "bedrooms": 4,
#     "bathrooms": 3,
#     "kitchenType": "closed",
#     "grossArea": "> 150m²",
#     "extras": "garage,pantry,storage room,balcony",
#     "prompt": "Modern open-plan layout with large windows",
#     "refImageUrl": "https://example.com/reference-floorplan.jpg",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/floorPlan/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createFloorPlanTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/floorPlan/generate`,
      {
        bedrooms: 3,
        bathrooms: 2,
        kitchenType: 'open',
        grossArea: '100-120m²',
        extras: 'walk-in closet,laundry room,home office',
        modelType: 'Base'

        // Pro model with reference and prompt:
        // bedrooms: 4,
        // bathrooms: 3,
        // kitchenType: 'closed',
        // grossArea: '> 150m²',
        // extras: 'garage,pantry,storage room,balcony',
        // prompt: 'Modern open-plan layout with large windows',
        // refImageUrl: 'https://example.com/reference-floorplan.jpg',
        // modelType: 'Pro'
      },
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const taskId = response.data.data;
    console.log('Task ID:', taskId);
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createFloorPlanTask();

📤 Response

Success Response

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

Field	Type	Description
`code`	`integer`	`0` indicates success
`message`	`string`	Response message
`data`	`long`	The unique task ID for polling results

2. Get Task Result

Retrieves the current status and output of a previously created floor plan task.

Endpoint

GET /api/v1/floorPlan/result

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key

Query Parameters

Parameter	Type	Required	Description
`taskId`	`long`	✅ Yes	The task ID returned from the create task endpoint

📥 Request Examples

cURL

curl -X GET "https://api.ideal.house/api/v1/floorPlan/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class FloorPlanResultExample {

    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 IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/floorPlan/result?taskId=" + taskId)
            .addHeader("APIKEY", API_KEY)
            .get()
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/floorPlan/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(3)  # Poll every 3 seconds

if status == "Success":
    print("Result URL:", result["output"]["resultUrl"])
else:
    print("Task ended with status:", status)

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/floorPlan/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Result URL:', result.output.resultUrl);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Response

Success Response (Task Completed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "bedrooms": 3,
      "bathrooms": 2,
      "kitchenType": "open",
      "grossArea": "100-120m²",
      "extras": "walk-in closet,laundry room,home office",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/floorplan_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 40,
    "input": {
      "bedrooms": 3,
      "bathrooms": 2,
      "kitchenType": "open",
      "grossArea": "100-120m²",
      "extras": "walk-in closet,laundry room,home office",
      "modelType": "Base"
    },
    "output": null
  }
}

Response (Task Failed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "bedrooms": 3,
      "bathrooms": 2,
      "kitchenType": "open",
      "grossArea": "100-120m²",
      "extras": "walk-in closet,laundry room,home office",
      "modelType": "Base"
    },
    "output": null
  }
}

Response Fields

Field	Type	Description
`id`	`long`	Task unique identifier
`status`	`string`	Current task status (see Task Status)
`waitNumber`	`integer`	Number of tasks ahead in the queue (`0` means currently processing)
`percentage`	`integer`	Task completion percentage (`0–100`)
`input`	`object`	The original input parameters of the task
`input.bedrooms`	`integer`	Number of bedrooms
`input.bathrooms`	`integer`	Number of bathrooms
`input.kitchenType`	`string`	Kitchen layout type
`input.grossArea`	`string`	Gross floor area range
`input.extras`	`string`	Extra functional spaces (comma-separated)
`input.prompt`	`string`	Custom text prompt (if provided)
`input.refImageUrl`	`string`	Reference floor plan image URL (if provided)
`input.modelType`	`string`	Model type used
`output`	`object`	Generation result (only available when `status` is `Success`)
`output.resultUrl`	`string`	URL to the generated floor plan image
`output.width`	`integer`	Output width in pixels
`output.height`	`integer`	Output height in pixels

📊 Task Status

Status	Description
`Unprocessed`	Task has been created but not yet started
`Processing`	Task is currently being processed
`Success`	Task completed successfully — output is available
`Failed`	Task failed due to an error

💡 Polling Recommendation: Poll the result endpoint every 3–5 seconds. Avoid polling too frequently to prevent rate limiting.

❌ Error Responses

All error responses share the same JSON structure:

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Error Code Reference

Code	Name	Description	Suggested Action
`1001`	`FAILED`	Request failed (generic error)	Check the `message` field for specific error details
`1003`	`INTERNAL_ERROR`	Internal server error	Retry after a short delay; contact support if it persists
`1011`	`PARAM_ERROR`	Request parameter error	Verify all required parameters are provided and correctly formatted
`5002`	`API_KEY_INVALID`	Invalid or missing API Key	Ensure the `APIKEY` header is present and the value is correct
`9010`	`SCAN_TEXT_ERROR`	Text prompt failed content review	Modify the prompt to remove any sensitive or prohibited content
`9038`	`PROHIBITED_CONTENT`	Generated output image contains prohibited content	Adjust prompt/style/inputs and retry
`9051`	`COINS_NOT_ENOUGH`	Insufficient coins / credits	Top up your account credits and retry

📄 For the complete list of common API error codes, refer to the Error Code Reference.

🔄 Recommended Integration Flow

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  1. POST /api/v1/floorPlan/generate                     │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 3–5 seconds                                    │
│                                                         │
│  3. GET /api/v1/floorPlan/result?taskId={taskId}        │
│     → Check status field                               │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Unprocessed" or "Processing"       │   │
│     │   → waitNumber: position in queue             │   │
│     │   → percentage: current progress              │   │
│     │   → Repeat step 2 & 3                         │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Success"                           │   │
│     │   → output.resultUrl: floor plan image        │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed"                            │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘