Ideal House
İçeriğe atla

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.

  1. Görev oluşturmaimageUrl ve isteğe bağlı prompt gönderin, ardından bir taskId alın.
  2. Sonuçları sorgulama — Görev durumunu sorgulamak ve çıktı görselini almak için taskId kullanı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ıkDeğer
APIKEYyour_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, 9051 hata kodunu döndürür. 📄 Kredi Kesintisi Referansı bölümüne bakın.

İşlemKesilen Kredi
Sanal Sahneleme görevi1 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

Düz metin
POST /api/v1/virtualStaging/generate

İstek Başlıkları

BaşlıkZorunluAçıklama
APIKEY✅ EvetAPI kimlik doğrulama anahtarınız
Content-Type✅ Evetapplication/json

İstek Gövdesi

AlanTürZorunluAçıklama
imageUrlstring✅ EvetKaynak oda görselinin URL
promptstring❌ HayırStili ve mobilyayı yönlendirmek için isteğe bağlı komut
indoorTypeIdstring❌ Hayırİsteğe bağlı oda tipi ön ayarı. İç Mekan Tipi Seçenekleri bölümüne bakın
indoorStyleIdstring❌ Hayırİsteğe bağlı iç mekan stili ön ayarı. İç Mekan Stili Seçenekleri bölümüne bakın
indoorElemIdstring❌ 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:

Düz metin
GET /api/v1/style/virtual_staging/getStyles
Stil Grubuİstek AlanıAçıklama
roomTypeindoorTypeIdOda tipi seçeneği
styleindoorStyleIdİç mekan stili seçeneği
elementsindoorElemIdOda 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
bash
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)
java
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)
python
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)
javascript
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

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
AlanTürAçıklama
codeinteger0 başarıyı gösterir
messagestringYanıt mesajı
datalongSonuç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

Düz metin
GET /api/v1/virtualStaging/result

İstek Başlıkları

BaşlıkZorunluAçıklama
APIKEY✅ EvetAPI kimlik doğrulama anahtarınız

Sorgu Parametreleri

ParametreTürZorunluAçıklama
taskIdlong✅ EvetGörev oluşturma uç noktasından döndürülen görev kimlik numarası

📥 İstek Örnekleri#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/virtualStaging/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
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)
python
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)
javascript
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ı)

json
{
  "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)

json
{
  "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)

json
{
  "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ı

AlanTürAçıklama
idlongGörev benzersiz kimlik numarası
statusstringGüncel görev durumu (Görev Durumu bölümüne bakın)
waitNumberintegerSırada bekleyen görev sayısı (0, şu anda işleniyor anlamına gelir)
percentageintegerGörev tamamlanma yüzdesi (0-100)
errorReasonstringstatus Failed olduğunda başarısızlık nedeni
inputobjectBu görev için gönderilen orijinal girdi parametreleri
input.imageUrlstringKaynak oda görseli URL
input.promptstringKullanıcı komutu (verildiyse)
input.indoorTypeIdstringKullanılan oda tipi ön ayarı (verildiyse)
input.indoorStyleIdstringKullanılan iç mekan stili ön ayarı (verildiyse)
input.indoorElemIdstringKullanılan oda elemanı ön ayarı (verildiyse). Virgülle birleştirilmiş birden fazla kimlik numarası içerebilir
outputobjectÜretim sonucu (yalnızca status Success olduğunda kullanılabilir)
output.resultUrlstringOluşturulan sanal sahneleme sonuç görselinin URL
output.widthintegerÇıktı görseli genişliği (piksel)
output.heightintegerÇıktı görseli yüksekliği (piksel)

📊 Görev Durumu#

DurumAnlam
UnprocessedGörev oluşturuldu ve sırada bekliyor
ProcessingGörev şu anda çalışıyor
SuccessGörev başarıyla tamamlandı
FailedGö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:

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

Hata Kodu Referansı#

KodAdAçıklamaÖnerilen İşlem
1001FAILEDİstek başarısız oldu (genel hata)Spesifik ayrıntılar için message alanını kontrol edin
1003INTERNAL_ERRORDahili sunucu hatasıKısa bir gecikme sonrası yeniden deneyin; devam ederse destek ekibiyle iletişime geçin
1011PARAM_ERRORİstek parametresi hatası (örneğin, eksik imageUrl)imageUrl sağlandığından ve geçerli bir URL olduğundan emin olun
5002API_KEY_INVALIDGeçersiz veya eksik API AnahtarıAPIKEY başlığının mevcut ve doğru olduğundan emin olun
9010SCAN_TEXT_ERRORKomut içerik denetiminden geçemediHassas veya yasaklı içeriği kaldırmak için komutu düzeltin
9038PROHIBITED_CONTENTOluşturulan çıktı görseli yasaklı içerik barındırıyorKomutu/stili/girdileri ayarlayın ve yeniden deneyin
9051COINS_NOT_ENOUGHYetersiz krediKredileri yükleyin ve yeniden deneyin

📄 Tam ortak hata tanımları için Hata Kodu Referansı bölümüne bakın.