House Plan Generation API Documentation

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

---

📖 Overview

The House Plan Generation API allows you to create AI-generated exterior house plan images based on architectural style, area, structural configuration, and interior layout preferences. Upon successful generation, the API produces exactly 3 result images per task, all stored in output.resultList. The workflow is asynchronous and involves two steps:

1. Create a task — Submit your house plan parameters and receive a taskId.
2. Poll for results — Use the taskId to query task status and retrieve the generated images.

---

🔐 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.
⚠️ Partial Result Refund: If the task status is Success but the number of result images returned in output.resultList is fewer than 3, the originally 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	20 credits
Pro	40 credits

---

📌 API Endpoints

---

1. Create House Plan Task

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

Endpoint

POST /api/v1/housePlan/generate

Request Headers

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

Request Body

Field	Type	Required	Description
style	string	❌ Optional	Architectural style. Defaults to Barndominium. See Style Options
totalArea	string	❌ Optional	Total house area. Supports metric (m²) and imperial (ft²). See Total Area Options
stories	string	❌ Optional	Number of floors / stories (e.g., 1, 2, 3)
bedrooms	string	❌ Optional	Number of bedrooms (e.g.,1,2 3, 4, 5+)
bathrooms	string	❌ Optional	Number of bathrooms (e.g., 1,1.5,2,2.5,3 3.5, 4+)
roofType	string	❌ Optional	Roof structure type. See Roof Type Options
foundation	string	❌ Optional	Foundation type. See Foundation Options
garageCapacity	string	❌ Optional	Number of garage spaces (e.g., 0, 1, 2, 3)
outdoorSpaces	string	❌ Optional	Outdoor areas, multiple values joined with commas. See Outdoor Spaces Options
layoutConcept	string	❌ Optional	Overall interior layout concept. See Layout Concept Options
kitchenFeatures	string	❌ Optional	Kitchen layout style. Defaults to Open. See Kitchen Features Options
keyRooms	string	❌ Optional	Key special rooms, multiple values joined with commas. See Key Rooms Options
prompt	string	❌ Optional	Custom text prompt to further guide the generation
refImageUrl	string	❌ Optional	URL of a reference house image to guide the style
modelType	string	❌ Optional	Model quality type. Enum: Base, Pro. Defaults to Base. ⚠️ Flash mode is not supported

---

🎨 Style Options

Value	Description
Barndominium	Default. Metal barn-style hybrid home
Cabin	Rustic wood cabin style
Cape Cod	Classic New England symmetrical style
Coastal	Light, airy beach-inspired style
Colonial	Traditional symmetric colonial architecture
Contemporary	Clean lines and modern materials
Craftsman	Handcrafted details with natural materials
Farmhouse	Rustic country farmhouse style
French Country	Elegant French provincial style
Mediterranean	Warm stucco with terracotta elements
Mid-Century Modern	1950s–70s clean geometric modernism
Modern	Minimalist flat/angular modern design
Ranch	Single-story sprawling layout
Shingle Style	Continuous wood shingle exterior
Southwestern	Adobe-inspired desert style
Transitional	Blend of traditional and contemporary
Tudor	Half-timbered medieval English style
Victorian	Ornate 19th-century decorative style

💡 You can also enter a custom style description.

---

📐 Total Area Options

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

Metric (m²)

Value	Description
< 140m²	Less than 140 square meters
140-230m²	140 to 230 square meters
150-200m²	150 to 200 square meters
230-325m²	230 to 325 square meters
> 325m²	Greater than 325 square meters

Imperial (ft²)

Value	Description
< 1500ft²	Less than 1500 square feet
1500-2500ft²	1500 to 2500 square feet
2500ft²	2500 square feet
2500-3500ft²	2500 to 3500 square feet
> 3500ft²	Greater than 3500 square feet

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

---

🏠 Roof Type Options

Value	Description
Gable roof	Classic triangular peaked roof
Hip roof	Slopes on all four sides
Flat roof	Minimal pitch flat roof
Pitched roof	General steeply sloped roof

💡 You can also enter a custom roof type description.

---

🏗️ Foundation Options

Value	Description
Slab	Concrete slab directly on ground
Basement	Full basement below ground level

💡 You can also enter a custom foundation type description.

---

🚗 Garage Capacity

The garageCapacity field accepts a numeric string representing the number of car spaces:

Value	Description
0	No garage
1	Single-car garage
2	Double-car garage
3	Triple-car garage
4+	Triple-car garage

---

🌿 Outdoor Spaces Options

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

Value	Description
Front porch	Covered entrance porch at the front
Covered patio	Covered outdoor patio area
Deck	Wooden or composite deck
Balcony	Elevated outdoor platform
Courtyard	Enclosed or semi-enclosed outdoor yard
Breezeway	Covered passageway connecting structures
Outdoor Kitchen	Outdoor cooking and dining area

Example

"outdoorSpaces": "Front porch,Deck,Balcony"

💡 You can also provide custom outdoor space descriptions.

---

🏛️ Layout Concept Options

Value	Description
Open Concept	Open-plan connected living spaces
Traditional	Separated rooms with defined boundaries
Split-Level	Staggered floor levels between areas

💡 You can also enter a custom layout description.

---

🍳 Kitchen Features Options

Value	Description
Open	Default. Open kitchen connected to living/dining area
Close	Enclosed separate kitchen space

---

🚪 Key Rooms Options

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

Value	Description
Home Office	Dedicated home office or study
Bonus Room	Flexible multi-purpose bonus room
Media Room	Home theater or media center
Mudroom	Entry room for outdoor gear
Laundry Room	Dedicated laundry space
Guest Suite	Self-contained guest bedroom suite

Example

"keyRooms": "Home Office,Media Room,Guest Suite"

💡 You can also provide custom room descriptions.

---

Model Types

Value	Description
Base	Default. Balanced speed and quality
Pro	Higher quality output with 4K first-step generation, slower

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

---

📥 Request Examples

cURL

# Basic request
curl -X POST "https://api.ideal.house/api/v1/housePlan/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "style": "Modern",
    "totalArea": "140-230m²",
    "stories": "2",
    "bedrooms": "4",
    "bathrooms": "3",
    "roofType": "Flat roof",
    "foundation": "Slab",
    "garageCapacity": "2",
    "outdoorSpaces": "Front porch,Deck",
    "layoutConcept": "Open Concept",
    "kitchenFeatures": "Open",
    "keyRooms": "Home Office,Media Room",
    "modelType": "Base"
  }'

# Pro model with reference image and custom prompt
curl -X POST "https://api.ideal.house/api/v1/housePlan/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "style": "Victorian",
    "totalArea": "> 325m²",
    "stories": "3",
    "bedrooms": "5",
    "bathrooms": "4",
    "roofType": "Gable roof",
    "foundation": "Basement",
    "garageCapacity": "3",
    "outdoorSpaces": "Front porch,Balcony,Courtyard,Outdoor Kitchen",
    "layoutConcept": "Traditional",
    "kitchenFeatures": "Close",
    "keyRooms": "Home Office,Bonus Room,Media Room,Guest Suite",
    "prompt": "Grand Victorian mansion with ornate details and wraparound porch",
    "refImageUrl": "https://example.com/reference-house.jpg",
    "modelType": "Pro"
  }'

Java (OkHttp)

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

public class HousePlanApiExample {

    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 = """
            {
                "style": "Modern",
                "totalArea": "140-230m²",
                "stories": "2",
                "bedrooms": "4",
                "bathrooms": "3",
                "roofType": "Flat roof",
                "foundation": "Slab",
                "garageCapacity": "2",
                "outdoorSpaces": "Front porch,Deck",
                "layoutConcept": "Open Concept",
                "kitchenFeatures": "Open",
                "keyRooms": "Home Office,Media Room",
                "modelType": "Base"
            }
            """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/housePlan/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 = {
    "style": "Modern",
    "totalArea": "140-230m²",
    "stories": "2",
    "bedrooms": "4",
    "bathrooms": "3",
    "roofType": "Flat roof",
    "foundation": "Slab",
    "garageCapacity": "2",
    "outdoorSpaces": "Front porch,Deck",
    "layoutConcept": "Open Concept",
    "kitchenFeatures": "Open",
    "keyRooms": "Home Office,Media Room",
    "modelType": "Base"
}

# Pro model with reference image and custom prompt
# payload = {
#     "style": "Victorian",
#     "totalArea": "> 325m²",
#     "stories": "3",
#     "bedrooms": "5",
#     "bathrooms": "4",
#     "roofType": "Gable roof",
#     "foundation": "Basement",
#     "garageCapacity": "3",
#     "outdoorSpaces": "Front porch,Balcony,Courtyard,Outdoor Kitchen",
#     "layoutConcept": "Traditional",
#     "kitchenFeatures": "Close",
#     "keyRooms": "Home Office,Bonus Room,Media Room,Guest Suite",
#     "prompt": "Grand Victorian mansion with ornate details and wraparound porch",
#     "refImageUrl": "https://example.com/reference-house.jpg",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/housePlan/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 createHousePlanTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/housePlan/generate`,
      {
        style: 'Modern',
        totalArea: '140-230m²',
        stories: '2',
        bedrooms: '4',
        bathrooms: '3',
        roofType: 'Flat roof',
        foundation: 'Slab',
        garageCapacity: '2',
        outdoorSpaces: 'Front porch,Deck',
        layoutConcept: 'Open Concept',
        kitchenFeatures: 'Open',
        keyRooms: 'Home Office,Media Room',
        modelType: 'Base'

        // Pro model with reference and prompt:
        // style: 'Victorian',
        // totalArea: '> 325m²',
        // stories: '3',
        // bedrooms: '5',
        // roofType: 'Gable roof',
        // foundation: 'Basement',
        // garageCapacity: '3',
        // outdoorSpaces: 'Front porch,Balcony,Courtyard,Outdoor Kitchen',
        // layoutConcept: 'Traditional',
        // kitchenFeatures: 'Close',
        // keyRooms: 'Home Office,Bonus Room,Media Room,Guest Suite',
        // prompt: 'Grand Victorian mansion with ornate details and wraparound porch',
        // refImageUrl: 'https://example.com/reference-house.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);
  }
}

createHousePlanTask();

---

📤 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 house plan task.

Endpoint

GET /api/v1/housePlan/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/housePlan/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

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

public class HousePlanResultExample {

    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/housePlan/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/housePlan/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", "Termination"):
        break

    time.sleep(3)  # Poll every 3 seconds

if status == "Success":
    output = result["output"]
    print("Primary Result URL:", output["resultUrl"])
    print("All Result Images:", output.get("resultList", []))
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/housePlan/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', 'Termination'].includes(status)) {
      if (status === 'Success') {
        console.log('Primary Result URL:', result.output.resultUrl);
        console.log('All Result Images:', result.output.resultList);
      } 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

📸 Note: This API generates exactly 3 result images per successful task. All generated images are stored in output.resultList. The output.resultUrl contains the first (primary) image. If fewer than 3 images are returned despite a Success status, the deducted credits will be automatically refunded.

Success Response (Task Completed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "style": "Modern",
      "totalArea": "140-230m²",
      "stories": "2",
      "bedrooms": "4",
      "bathrooms": "3",
      "roofType": "Flat roof",
      "foundation": "Slab",
      "garageCapacity": "2",
      "outdoorSpaces": "Front porch,Deck",
      "layoutConcept": "Open Concept",
      "kitchenFeatures": "Open",
      "keyRooms": "Home Office,Media Room",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/house_plan_1.jpg",
      "resultList": [
        "https://cdn.ideal.house/output/house_plan_1.jpg",
        "https://cdn.ideal.house/output/house_plan_2.jpg",
        "https://cdn.ideal.house/output/house_plan_3.jpg"
      ],
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "style": "Modern",
      "totalArea": "140-230m²",
      "stories": "2",
      "bedrooms": "4",
      "bathrooms": "3",
      "roofType": "Flat roof",
      "foundation": "Slab",
      "garageCapacity": "2",
      "outdoorSpaces": "Front porch,Deck",
      "layoutConcept": "Open Concept",
      "kitchenFeatures": "Open",
      "keyRooms": "Home Office,Media Room",
      "modelType": "Base"
    },
    "output": null
  }
}

Response (Task Failed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "style": "Modern",
      "totalArea": "140-230m²",
      "stories": "2",
      "bedrooms": "4",
      "bathrooms": "3",
      "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.style	string	Architectural style
input.totalArea	string	Total area range
input.stories	string	Number of floors
input.bedrooms	string	Number of bedrooms
input.bathrooms	string	Number of bathrooms
input.roofType	string	Roof type
input.foundation	string	Foundation type
input.garageCapacity	string	Number of garage spaces
input.outdoorSpaces	string	Outdoor spaces (comma-separated)
input.layoutConcept	string	Overall layout concept
input.kitchenFeatures	string	Kitchen layout style
input.keyRooms	string	Key special rooms (comma-separated)
input.prompt	string	Custom text prompt (if provided)
input.refImageUrl	string	Reference 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 primary generated house plan image
output.resultList	array<string>	URLs to all generated result images (normally 3 images; if fewer than 3 are returned, deducted credits are automatically refunded)
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
Termination	Task was interrupted or terminated

💡 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/housePlan/generate                     │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 3–5 seconds                                    │
│                                                         │
│  3. GET /api/v1/housePlan/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: primary image           │   │
│     │   → output.resultList: all images (normally 3) │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed" or "Termination"           │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

© Ideal House AI — All rights reserved.