Sanal Sahneleme API Belgeleme#
Temel URL:
https://api.ideal.house
Sürüm: v1
Güncellendi: 2026-04-13
📖 Genel Bakış#
Sanal Sahneleme API, boş veya kısmen mobilyalı bir odayı yapay zeka kullanarak yeniden tasarlamanızı sağlar.
Bir oda görseli URL ve isteğe bağlı bir metin komutu gönderir, ardından oluşturulan sonucu asenkron olarak alırsınız.
- Görev oluşturma —
imageUrlve isteğe bağlıpromptgönderin, ardından birtaskIdalın. - Sonuçları sorgulama — Görev durumunu sorgulamak ve çıktı görselini almak için
taskIdkullanın.
🔐 Kimlik Doğrulama#
Tüm API istekleri, bir API Anahtarı kullanılarak kimlik doğrulanmalıdır.
İstek başlığına API Anahtarınızı ekleyin:
| Başlık | Değer |
|---|---|
APIKEY | your_api_key_here |
⚠️ API Anahtarınızı güvenli tutun. İstemci tarafı kodda veya herkese açık depolarda ifşa etmeyin.
💰 Kredi Kesintisi#
[!WARNING] 🪙 1 kredi, görev başarıyla oluşturulduğunda kesilir.
Görev nihayetinde başarısız olursa, kesilen kredi otomatik olarak iade edilir.
Yetersiz kredi,9051hata kodunu döndürür. 📄 Kredi Kesintisi Referansı bölümüne bakın.
| İşlem | Kesilen Kredi |
|---|---|
| Sanal Sahneleme görevi | 1 kredi |
📌 API Uç Noktaları#
1. Sanal Sahneleme Görevi Oluşturma#
Yeni bir sanal sahneleme görevi oluşturur ve sorgulama için benzersiz bir taskId döndürür.
Uç Nokta
POST /api/v1/virtualStaging/generate
İstek Başlıkları
| Başlık | Zorunlu | Açıklama |
|---|---|---|
APIKEY | ✅ Evet | API kimlik doğrulama anahtarınız |
Content-Type | ✅ Evet | application/json |
İstek Gövdesi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
imageUrl | string | ✅ Evet | Kaynak oda görselinin URL |
prompt | string | ❌ Hayır | Stili ve mobilyayı yönlendirmek için isteğe bağlı komut |
indoorTypeId | string | ❌ Hayır | İsteğe bağlı oda tipi ön ayarı. İç Mekan Tipi Seçenekleri bölümüne bakın |
indoorStyleId | string | ❌ Hayır | İsteğe bağlı iç mekan stili ön ayarı. İç Mekan Stili Seçenekleri bölümüne bakın |
indoorElemId | string | ❌ Hayır | İsteğe bağlı oda elemanı ön ayarı. Virgülle birleştirilmiş birden fazla kimlik numarasını destekler, örneğin id1,id2 |
🖼️ Görsel gereksinimleri: JPG/JPEG, PNG veya WebP kullanın. Her görsel en fazla 20 MB boyutunda olmalı, boyutları 128 × 128 px ile 6,000 × 6,000 px (dahil) arasında olmalıdır. Maksimum piksel boyutlarını aşan görseller, işlemden önce 6,000 × 6,000 px boyutlarına sığacak şekilde orantılı olarak otomatik olarak küçültülür. Görsel URL, API sunucusu tarafından doğrudan erişilebilir olmalıdır.
🎨 Stil Seçenekleri#
indoorTypeId, indoorStyleId ve indoorElemId, API Stil Yapılandırması uç noktasından seçilebilir.
Kullanım:
GET /api/v1/style/virtual_staging/getStyles
| Stil Grubu | İstek Alanı | Açıklama |
|---|---|---|
roomType | indoorTypeId | Oda tipi seçeneği |
style | indoorStyleId | İç mekan stili seçeneği |
elements | indoorElemId | Oda elemanı seçeneği. Virgülle birleştirilmiş birden fazla seçenek kimlik numarasını destekler, örneğin id1,id2 |
Her seçenek name, id ve url içerir. Seçenek id değerini ilgili istek alanına geçirin.
📥 İstek Örnekleri#
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();
📤 Yanıt#
Başarılı Yanıt
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
| Alan | Tür | Açıklama |
|---|---|---|
code | integer | 0 başarıyı gösterir |
message | string | Yanıt mesajı |
data | long | Sonuçları sorgulamak için benzersiz görev kimlik numarası |
2. Görev Sonucunu Alma#
Daha önce oluşturulmuş bir sanal sahneleme görevinin güncel durumunu ve çıktısını alır.
Uç Nokta
GET /api/v1/virtualStaging/result
İstek Başlıkları
| Başlık | Zorunlu | Açıklama |
|---|---|---|
APIKEY | ✅ Evet | API kimlik doğrulama anahtarınız |
Sorgu Parametreleri
| Parametre | Tür | Zorunlu | Açıklama |
|---|---|---|---|
taskId | long | ✅ Evet | Görev oluşturma uç noktasından döndürülen görev kimlik numarası |
📥 İstek Örnekleri#
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);
📤 Yanıt#
Başarılı Yanıt (Görev Tamamlandı)
{
"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
}
}
}
Yanıt (Görev İşleniyor / Sırada)
{
"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
}
}
Yanıt (Görev Başarısız)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/empty-room.jpg",
"prompt": "..."
},
"output": null
}
}
Yanıt Alanları
| Alan | Tür | Açıklama |
|---|---|---|
id | long | Görev benzersiz kimlik numarası |
status | string | Güncel görev durumu (Görev Durumu bölümüne bakın) |
waitNumber | integer | Sırada bekleyen görev sayısı (0, şu anda işleniyor anlamına gelir) |
percentage | integer | Görev tamamlanma yüzdesi (0-100) |
errorReason | string | status Failed olduğunda başarısızlık nedeni |
input | object | Bu görev için gönderilen orijinal girdi parametreleri |
input.imageUrl | string | Kaynak oda görseli URL |
input.prompt | string | Kullanıcı komutu (verildiyse) |
input.indoorTypeId | string | Kullanılan oda tipi ön ayarı (verildiyse) |
input.indoorStyleId | string | Kullanılan iç mekan stili ön ayarı (verildiyse) |
input.indoorElemId | string | Kullanılan oda elemanı ön ayarı (verildiyse). Virgülle birleştirilmiş birden fazla kimlik numarası içerebilir |
output | object | Üretim sonucu (yalnızca status Success olduğunda kullanılabilir) |
output.resultUrl | string | Oluşturulan sanal sahneleme sonuç görselinin URL |
output.width | integer | Çıktı görseli genişliği (piksel) |
output.height | integer | Çıktı görseli yüksekliği (piksel) |
📊 Görev Durumu#
| Durum | Anlam |
|---|---|
Unprocessed | Görev oluşturuldu ve sırada bekliyor |
Processing | Görev şu anda çalışıyor |
Success | Görev başarıyla tamamlandı |
Failed | Görev başarısız oldu ve çıktı üretilmedi |
Her 3-5 saniyede bir sorgulama yapın. API Görev Sınırı bölümüne bakın.
❌ Hata Yanıtları#
Tüm hata yanıtları aynı JSON yapısını paylaşır:
{
"code": 5002,
"message": "Invalid API Key",
"data": null
}
Hata Kodu Referansı#
| Kod | Ad | Açıklama | Önerilen İşlem |
|---|---|---|---|
1001 | FAILED | İstek başarısız oldu (genel hata) | Spesifik ayrıntılar için message alanını kontrol edin |
1003 | INTERNAL_ERROR | Dahili sunucu hatası | Kısa bir gecikme sonrası yeniden deneyin; devam ederse destek ekibiyle iletişime geçin |
1011 | PARAM_ERROR | İstek parametresi hatası (örneğin, eksik imageUrl) | imageUrl sağlandığından ve geçerli bir URL olduğundan emin olun |
5002 | API_KEY_INVALID | Geçersiz veya eksik API Anahtarı | APIKEY başlığının mevcut ve doğru olduğundan emin olun |
9010 | SCAN_TEXT_ERROR | Komut içerik denetiminden geçemedi | Hassas veya yasaklı içeriği kaldırmak için komutu düzeltin |
9038 | PROHIBITED_CONTENT | Oluşturulan çıktı görseli yasaklı içerik barındırıyor | Komutu/stili/girdileri ayarlayın ve yeniden deneyin |
9051 | COINS_NOT_ENOUGH | Yetersiz kredi | Kredileri yükleyin ve yeniden deneyin |
📄 Tam ortak hata tanımları için Hata Kodu Referansı bölümüne bakın.