Virtual Staging API Documentation
Base URL:
https://api.ideal.house
Version: v1
Updated: 2026-04-13
š Overview
The Virtual Staging API allows you to redesign an empty or partially furnished room using AI.
You submit a room image URL and an optional text prompt, then retrieve the generated result asynchronously.
- Create a task ā Submit
imageUrland optionalprompt, then receive ataskId. - Poll for results ā Use
taskIdto query task status and get the output 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] šŖ 1 credit is deducted when a task is successfully created.
If the task ultimately fails, the deducted credit will be automatically refunded.
Insufficient credits will return error code9051. š See Credits Deduction Reference.
| Operation | Credits Deducted |
|---|---|
| Virtual Staging task | 1 credit |
š API Endpoints
1. Create Virtual Staging Task
Creates a new virtual staging task and returns a unique taskId for polling.
Endpoint
POST /api/v1/virtualStaging/generate
Request Headers
| Header | Required | Description |
|---|---|---|
APIKEY | ā Yes | Your API authentication key |
Content-Type | ā Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
imageUrl | string | ā Yes | URL of the source room image |
prompt | string | ā No | Optional prompt to guide style and furnishing |
indoorTypeId | string | ā No | Optional room type preset. See Indoor Type Options |
indoorStyleId | string | ā No | Optional interior style preset. See Indoor Style Options |
indoorElemId | string | ā No | Optional room element preset. Supports multiple IDs joined by comma, for example id1,id2 |
š¼ļø Image requirements: Use JPG/JPEG, PNG, or WebP. Each image must be no larger than 20 MB, with dimensions from 128 Ć 128 px up to 6,000 Ć 6,000 px (inclusive). Images exceeding the maximum pixel dimensions are automatically scaled down proportionally to fit within 6,000 Ć 6,000 px before processing. The image URL must be directly accessible by the API server.
šØ Style Options
indoorTypeId, indoorStyleId, and indoorElemId can be selected from the API Style Config endpoint.
Use:
GET /api/v1/style/virtual_staging/getStyles
| Style Group | Request Field | Description |
|---|---|---|
roomType | indoorTypeId | Room type option |
style | indoorStyleId | Interior style option |
elements | indoorElemId | Room element option. Supports multiple option IDs joined by comma, for example id1,id2 |
Each option contains name, id, and url. Pass the option id into the corresponding request field.
š„ Request Examples
cURL
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/empty-living-room.jpg",
"prompt": "Warm and modern living room styling",
"indoorTypeId": "Interior Design_Interior Scene_Living Room",
"indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
"indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}'
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class VirtualStagingApiExample {
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 = """
{
"imageUrl": "https://example.com/empty-bedroom.jpg",
"prompt": "Cozy contemporary bedroom",
"indoorTypeId": "Interior Design_Interior Scene_Bed Room",
"indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
"indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}
""";
Request request = new Request.Builder()
.url(BASE_URL + "/api/v1/virtualStaging/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 = {
"imageUrl": "https://example.com/empty-home-office.jpg",
"prompt": "Minimal modern home office",
"indoorTypeId": "Interior Design_Interior Scene_Home Office",
"indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
"indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}
response = requests.post(
f"{BASE_URL}/api/v1/virtualStaging/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 createVirtualStagingTask() {
try {
const response = await axios.post(
`${BASE_URL}/api/v1/virtualStaging/generate`,
{
imageUrl: 'https://example.com/empty-dining-room.jpg',
prompt: 'Modern luxury dining room',
indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
},
{
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);
}
}
createVirtualStagingTask();
š¤ 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 virtual staging task.
Endpoint
GET /api/v1/virtualStaging/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/virtualStaging/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class VirtualStagingResultExample {
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/virtualStaging/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
while True:
response = requests.get(
f"{BASE_URL}/api/v1/virtualStaging/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)
if status == "Success":
output = result["output"]
print("Result URL:", output["resultUrl"])
print("Size:", output["width"], "x", output["height"])
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/virtualStaging/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);
console.log('Size:', result.output.width, 'x', result.output.height);
} else {
console.log('Task ended with status:', status);
}
break;
}
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": {
"imageUrl": "https://example.com/empty-room.jpg",
"prompt": "modern country living room with warm neutral materials",
"indoorTypeId": "Interior Design_Interior Scene_Living Room",
"indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
"indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
},
"output": {
"resultUrl": "https://cdn.ideal.house/output/virtual_staging_result.jpg",
"width": 1024,
"height": 1024
}
}
}
Response (Task Processing / In Queue)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Processing",
"waitNumber": 1,
"percentage": 46,
"input": {
"imageUrl": "https://example.com/empty-room.jpg",
"prompt": "coastal bedroom with soft light and natural textures",
"indoorTypeId": "Interior Design_Interior Scene_Bed Room",
"indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
},
"output": null
}
}
Response (Task Failed)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/empty-room.jpg",
"prompt": "..."
},
"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 queue (0 means currently processing) |
percentage | integer | Task completion percentage (0-100) |
errorReason | string | Failure reason when status is Failed |
input | object | Original input parameters submitted for this task |
input.imageUrl | string | Source room image URL |
input.prompt | string | User prompt (if provided) |
input.indoorTypeId | string | Room type preset used (if provided) |
input.indoorStyleId | string | Interior style preset used (if provided) |
input.indoorElemId | string | Room element preset used (if provided). May contain multiple IDs joined by comma |
output | object | Generation result (available only when status is Success) |
output.resultUrl | string | URL of the generated virtual staging result image |
output.width | integer | Output image width in pixels |
output.height | integer | Output image height in pixels |
š Task Status
| Status | Meaning |
|---|---|
Unprocessed | Task is created and waiting in queue |
Processing | Task is currently running |
Success | Task completed successfully |
Failed | Task failed and no output was produced |
Poll every 3-5 seconds. See API Task Limit.
ā 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 details |
1003 | INTERNAL_ERROR | Internal server error | Retry after a short delay; contact support if it persists |
1011 | PARAM_ERROR | Request parameter error (for example, missing imageUrl) | Ensure imageUrl is provided and is a valid URL |
5002 | API_KEY_INVALID | Invalid or missing API Key | Ensure the APIKEY header is present and correct |
9010 | SCAN_TEXT_ERROR | Prompt failed content moderation | Revise the prompt to remove sensitive or prohibited content |
9038 | PROHIBITED_CONTENT | Generated output image contains prohibited content | Adjust prompt/style/inputs and retry |
9051 | COINS_NOT_ENOUGH | Insufficient credits | Top up credits and retry |
š For full common error definitions, see Error Code Reference.
