वर्चुअल स्टेजिंग API दस्तावेज़ीकरण#
बेस URL:
https://api.ideal.house
संस्करण: v1
अपडेट किया गया: 2026-04-13
📖 अवलोकन#
वर्चुअल स्टेजिंग API आपको AI का उपयोग करके खाली या आंशिक रूप से फर्नीशर वाली कमरा को पुनर्निर्माण करने की अनुमति देता है।
आप कमरे की छवि URL और एक वैकल्पिक टेक्स्ट प्रॉम्प्ट सबमिट करते हैं, फिर जनरेट किए गए परिणाम को असिंक्रोनस रूप से प्राप्त करते हैं।
- टास्क बनाएं —
imageUrlऔर वैकल्पिकpromptसबमिट करें, फिर एकtaskIdप्राप्त करें। - परिणामों के लिए पोल करें —
taskIdका उपयोग करके टास्क स्थिति का पूछताछ करें और आउटपुट छवि प्राप्त करें।
🔐 प्रमाणीकरण#
सभी API अनुरोधों का प्रमाणीकरण API कुंजी से किया जाना चाहिए।
अनुरोध हेडर में अपना API की शामिल करें:
| हेडर | मान |
|---|---|
APIKEY | your_api_key_here |
⚠️ अपनी API कुंजी सुरक्षित रखें। इसे क्लाइंट-साइड कोड या सार्वजनिक रिपॉज़िटरी में उजागर न करें।
💰 क्रेडिट विलोपन#
[!WARNING] 🪙 1 क्रेडिट तब विलोपित किया जाता है जब टास्क सफलतापूर्वक बनाया जाता है।
यदि टास्क अंततः विफल होता है, तो काटा गया क्रेडिट अपने आप वापस कर दिया जाएगा।
अपर्याप्त क्रेडिट त्रुटि कोड9051लौटाएंगे। 📄 क्रेडिट विलोपन संदर्भ देखें।
| संचालन | विलोपित क्रेडिट |
|---|---|
| वर्चुअल स्टेजिंग टास्क | 1 क्रेडिट |
📌 API एंडपॉइंट#
1. वर्चुअल स्टेजिंग टास्क बनाएं#
नया वर्चुअल स्टेजिंग टास्क बनाता है और पोलिंग के लिए एक अद्वितीय taskId लौटाता है।
एंडपॉइंट
POST /api/v1/virtualStaging/generate
अनुरोध हेडर
| हेडर | आवश्यक | विवरण |
|---|---|---|
APIKEY | ✅ हाँ | आपका API प्रमाणीकरण की |
Content-Type | ✅ हाँ | application/json |
अनुरोध बॉडी
| फ़ील्ड | प्रकार | आवश्यक | विवरण |
|---|---|---|---|
imageUrl | string | ✅ हाँ | स्रोत कमरे की छवि का URL |
prompt | string | ❌ नहीं | शैली और फर्नीशरिंग को मार्गदर्शन करने के लिए वैकल्पिक प्रॉम्प्ट |
indoorTypeId | string | ❌ नहीं | वैकल्पिक कमरे के प्रकार का प्रीसेट। इंदोर टाइप विकल्प देखें |
indoorStyleId | string | ❌ नहीं | वैकल्पिक इंटीरियर शैली का प्रीसेट। इंदोर शैली विकल्प देखें |
indoorElemId | string | ❌ नहीं | वैकल्पिक कमरे के तत्व का प्रीसेट। कॉमा से जुड़े कई आईडी का समर्थन करता है, उदाहरण के लिए id1,id2 |
🖼️ छवि आवश्यकताएं: JPG/JPEG, PNG, या WebP का उपयोग करें। प्रत्येक छवि का आकार 20 MB से अधिक नहीं होना चाहिए, आयाम 128 × 128 px से लेकर 6,000 × 6,000 px (समावेशी) तक। अधिकतम पिक्सेल आयाम से अधिक छवियों को प्रोसेसिंग से पहले स्वतः अनुपात में छोटा कर दिया जाता है ताकि वे 6,000 × 6,000 px के भीतर फिट हों। छवि का URL API सर्वर द्वारा सीधे एक्सेस किया जा सकना चाहिए।
🎨 शैली विकल्प#
indoorTypeId, indoorStyleId, और indoorElemId को API शैली कॉन्फ़िग एंडपॉइंट से चुना जा सकता है।
उपयोग करें:
GET /api/v1/style/virtual_staging/getStyles
| शैली समूह | अनुरोध फ़ील्ड | विवरण |
|---|---|---|
roomType | indoorTypeId | कमरे के प्रकार का विकल्प |
style | indoorStyleId | इंटीरियर शैली का विकल्प |
elements | indoorElemId | कमरे के तत्व का विकल्प। कॉमा से जुड़े कई विकल्प आईडी का समर्थन करता है, उदाहरण के लिए id1,id2 |
प्रत्येक विकल्प में name, id, और url शामिल हैं। विकल्प का id संबंधित अनुरोध फ़ील्ड में पास करें।
📥 अनुरोध उदाहरण#
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();
📤 प्रतिक्रिया#
सफलता प्रतिक्रिया
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
| फ़ील्ड | प्रकार | विवरण |
|---|---|---|
code | integer | 0 सफलता दर्शाता है |
message | string | प्रतिक्रिया संदेश |
data | long | परिणामों के लिए पोलिंग का अद्वितीय टास्क आईडी |
2. टास्क परिणाम प्राप्त करें#
पहले से बनाए गए वर्चुअल स्टेजिंग टास्क की वर्तमान स्थिति और आउटपुट प्राप्त करता है।
एंडपॉइंट
GET /api/v1/virtualStaging/result
अनुरोध हेडर
| हेडर | आवश्यक | विवरण |
|---|---|---|
APIKEY | ✅ हाँ | आपका API प्रमाणीकरण की |
क्वेरी पैरामीटर
| पैरामीटर | प्रकार | आवश्यक | विवरण |
|---|---|---|---|
taskId | long | ✅ हाँ | टास्क बनाए एंडपॉइंट से लौटाया गया टास्क आईडी |
📥 अनुरोध उदाहरण#
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);
📤 प्रतिक्रिया#
सफलता प्रतिक्रिया (टास्क पूर्ण)
{
"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
}
}
}
प्रतिक्रिया (टास्क प्रोसेसिंग / कतार में)
{
"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
}
}
प्रतिक्रिया (टास्क विफल)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/empty-room.jpg",
"prompt": "..."
},
"output": null
}
}
प्रतिक्रिया फ़ील्ड
| फ़ील्ड | प्रकार | विवरण |
|---|---|---|
id | long | टास्क अद्वितीय पहचानकर्ता |
status | string | वर्तमान टास्क स्थिति (टास्क स्थिति देखें) |
waitNumber | integer | कतार में आगे टास्क की संख्या (0 का अर्थ है वर्तमान में प्रोसेसिंग) |
percentage | integer | टास्क पूर्णता प्रतिशत (0-100) |
errorReason | string | विफलता का कारण जब status Failed हो |
input | object | इस टास्क के लिए सबमिट किए गए मूल इनपुट पैरामीटर |
input.imageUrl | string | स्रोत कमरे की छवि का URL |
input.prompt | string | उपयोगकर्ता प्रॉम्प्ट (यदि प्रदान किया गया हो) |
input.indoorTypeId | string | उपयोग किया गया कमरे के प्रकार का प्रीसेट (यदि प्रदान किया गया हो) |
input.indoorStyleId | string | उपयोग किया गया इंटीरियर शैली का प्रीसेट (यदि प्रदान किया गया हो) |
input.indoorElemId | string | उपयोग किया गया कमरे के तत्व का प्रीसेट (यदि प्रदान किया गया हो)। कॉमा से जुड़े कई आईडी हो सकते हैं |
output | object | जनरेशन परिणाम (केवल तब उपलब्ध जब status Success हो) |
output.resultUrl | string | जनरेट की गई वर्चुअल स्टेजिंग परिणाम छवि का URL |
output.width | integer | आउटपुट छवि की चौड़ाई पिक्सेल में |
output.height | integer | आउटपुट छवि की ऊंचाई पिक्सेल में |
📊 टास्क स्थिति#
| स्थिति | अर्थ |
|---|---|
Unprocessed | टास्क बनाया गया है और कतार में प्रतीक्षा कर रहा है |
Processing | टास्क वर्तमान में चालू है |
Success | टास्क सफलतापूर्वक पूर्ण हुआ |
Failed | टास्क विफल हुआ और कोई आउटपुट नहीं बना |
हर 3-5 सेकंड में पोल करें। API टास्क सीमा देखें।
❌ त्रुटि प्रतिक्रियाएं#
सभी त्रुटि प्रतिक्रियाएं समान JSON संरचना साझा करती हैं:
{
"code": 5002,
"message": "Invalid API Key",
"data": null
}
त्रुटि कोड संदर्भ#
| कोड | नाम | विवरण | सुझाया गया कार्य |
|---|---|---|---|
1001 | FAILED | अनुरोध विफल (सामान्य त्रुटि) | विशिष्ट विवरण के लिए message फ़ील्ड की जांच करें |
1003 | INTERNAL_ERROR | आंतरिक सर्वर त्रुटि | छोटे विलंब के बाद पुनः प्रयास करें; यदि जारी रहे तो सहायता से संपर्क करें |
1011 | PARAM_ERROR | अनुरोध पैरामीटर त्रुटि (उदाहरण के लिए, imageUrl का अभाव) | सुनिश्चित करें कि imageUrl प्रदान किया गया है और यह एक मान्य URL है |
5002 | API_KEY_INVALID | अमान्य या अनुपस्थित API की | सुनिश्चित करें कि APIKEY हेडर मौजूद और सही है |
9010 | SCAN_TEXT_ERROR | प्रॉम्प्ट ने कंटेंट मॉडरेशन में विफलता दर्शाई | संवेदनशील या प्रतिबंधित सामग्री हटाने के लिए प्रॉम्प्ट संशोधित करें |
9038 | PROHIBITED_CONTENT | जनरेट की गई आउटपुट छवि में प्रतिबंधित सामग्री शामिल है | प्रॉम्प्ट/शैली/इनपुट को समायोजित करें और पुनः प्रयास करें |
9051 | COINS_NOT_ENOUGH | अपर्याप्त क्रेडिट | क्रेडिट टॉप-अप करें और पुनः प्रयास करें |
📄 पूर्ण सामान्य त्रुटि परिभाषाओं के लिए, त्रुटि कोड संदर्भ देखें।