Ideal House
İçeriğe atla

Mobilya Deneme API Belgelendirmesi#

Temel URL: https://api.ideal.house
Sürüm: v1
Güncellendi: 2026-03-09


📖 Genel Bakış#

Mobilya Deneme API, mobilya ürünlerini bir oda sahnesine sanal olarak yerleştirmenizi sağlar. Bir oda görüntüsü ve mobilya ürünleri listesi (her biri bir görsel ve ürün kimliği ile) sağlarsınız ve yapay zeka mobilyaları sahneye kusursuz bir şekilde birleştirir. İş akışı asenkroniktir ve iki adımdan oluşur:

  1. Görev oluştur — Oda görüntünüzü ve mobilya listenizi gönderin, ardından bir taskId alın.
  2. Sonuçları sorgulama — Görev durumunu sorgulamak ve üretilen görüntüyü almak için taskId kullanın.

📌 Not: Şu anda yalnızca creative modu desteklenmektedir.


🔐 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] 🪙 Krediler, görev başarıyla oluşturulduğunda seçilen modelType temelinde düşülür. Görev nihayetinde başarısız olursa, düşülen krediler hesabınıza otomatik olarak iade edilir.
Yetersiz krediler 9051 hata kodunu döndürür. 📄 Kredi Kesintisi Referansı bölümüne bakın.

Model (modelType)Kesilen Kredi
Base3 kredi
Pro10 kredi

📌 API Uç Noktalar#


1. Mobilya Deneme Görevi Oluştur#

Yeni bir yapay zeka mobilya deneme görevi oluşturur ve durum sorgulama için benzersiz bir taskId döndürür.

Uç Nokta

Düz metin
POST /api/v1/furnitureTryOn/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✅ EvetMobilyaların yerleştirileceği oda sahnesi görüntüsünün URL
furnitureListarray✅ EvetSahneye yerleştirilecek mobilya öğeleri listesi. En fazla 6 öğe. Mobilya Öğesi Nesnesi bkz.
promptstring❌ İsteğe BağlıYerleşimi ve stilizasyonu daha fazla yönlendirmek için özel metin istemi
modelTypestring❌ İsteğe BağlıModel kalite türü. Sayısal: Base, Pro. Varsayılan Base

🛋️ Mobilya Öğesi Nesnesi#

furnitureList içindeki her öğe, aşağıdaki alanlara sahip bir nesne olmalıdır:

AlanTürZorunluAçıklama
imageUrlstring✅ EvetMobilya ürün görselinin URL (şeffaf veya temiz arka plan önerilir)

⚠️ furnitureList en fazla 6 öğe içerebilir.

🖼️ Görsel gereksinimleri: Oda görüntüsü ve her mobilya görüntüsü JPG/JPEG, PNG veya WebP kullanmalıdır. 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 içine sığacak şekilde orantılı olarak otomatik olarak küçültülür. Görsel URLs, API sunucusu tarafından doğrudan erişilebilir olmalıdır.

Örnek

json
"furnitureList": [
  {
    "imageUrl": "https://example.com/sofa.png"
  },
  {
    "imageUrl": "https://example.com/table.png"
  }
]

Model Türleri

DeğerAçıklama
BaseVarsayılan. Hız ve kalite dengesi
ProDaha yüksek kalite çıktı, daha yavaş işleme

📥 İstek Örnekleri#

cURL
bash
# Basic request (Base model)
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      },
      {
        "imageUrl": "https://example.com/coffee-table.png"
      }
    ],
    "prompt": "modern minimalist style"
  }'

# Pro model
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "furnitureList": [
      {
        "imageUrl": "https://example.com/sofa.png"
      }
    ],
    "prompt": "Scandinavian interior with warm lighting",
    "modelType": "Pro"
  }'
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;

public class FurnitureTryOnApiExample {

    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/living-room.jpg",
                "furnitureList": [
                    {
                        "imageUrl": "https://example.com/sofa.png"
                    },
                    {
                        "imageUrl": "https://example.com/coffee-table.png"
                    }
                ],
                "prompt": "modern minimalist style",
                "modelType": "Base"
            }
            """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/furnitureTryOn/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/living-room.jpg",
    "furnitureList": [
        {
            "imageUrl": "https://example.com/sofa.png"
        },
        {
            "imageUrl": "https://example.com/coffee-table.png"
        }
    ],
    "prompt": "modern minimalist style",
    "modelType": "Base"
}

# Pro model example:
# payload = {
#     "imageUrl": "https://example.com/living-room.jpg",
#     "furnitureList": [
#         {
#             "imageUrl": "https://example.com/sofa.png"
#         }
#     ],
#     "prompt": "Scandinavian interior with warm lighting",
#     "modelType": "Pro"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/furnitureTryOn/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 createFurnitureTryOnTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/furnitureTryOn/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        furnitureList: [
          {
            imageUrl: 'https://example.com/sofa.png'
          },
          {
            imageUrl: 'https://example.com/coffee-table.png'
          }
        ],
        prompt: 'modern minimalist style',
        modelType: 'Base'

        // Pro model:
        // 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);
  }
}

createFurnitureTryOnTask();

📤 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 kimliği

2. Görev Sonucunu Al#

Daha önce oluşturulmuş bir mobilya deneme görevinin mevcut durumunu ve çıktısını getirir.

Uç Nokta

Düz metin
GET /api/v1/furnitureTryOn/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 kimliği

📥 İstek Örnekleri#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/furnitureTryOn/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;

public class FurnitureTryOnResultExample {

    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/furnitureTryOn/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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/furnitureTryOn/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)  # Poll every 3 seconds

if status == "Success":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Matched Items:", output.get("items", []))
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/furnitureTryOn/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('Matched Items:', result.output.items);
      } else {
        console.log('Task ended with status:', status);
      }
      break;
    }

    // Wait 3 seconds before next poll
    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/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        },
        {
          "imageUrl": "https://example.com/coffee-table.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/furniture_try_on_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Yanıt (Görev İşleniyor / Kuyrukta)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "prompt": "modern minimalist style",
      "modelType": "Base"
    },
    "output": null
  }
}

Yanıt (Görev Başarısız)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "furnitureList": [
        {
          "imageUrl": "https://example.com/sofa.png"
        }
      ],
      "modelType": "Base"
    },
    "output": null
  }
}

Yanıt Alanları

AlanTürAçıklama
idlongGörev benzersiz tanımlayıcısı
statusstringMevcut görev durumu (Görev Durumu bölümüne bakın)
waitNumberintegerKuyrukta öndeki görev sayısı (0 şu anda işleniyor demektir)
percentageintegerGörev tamamlanma yüzdesi (0–100)
inputobjectGörevin orijinal girdi parametreleri
input.imageUrlstringOda sahnesi görüntüsü URL
input.furnitureListarrayGönderilen mobilya ürünleri listesi (en fazla 6 öğe)
input.furnitureList[].imageUrlstringMobilya ürün görseli URL
input.promptstringÖzel metin istemi (verildiyse)
input.modelTypestringKullanılan model türü
outputobjectÜretim sonucu (yalnızca status Success olduğunda kullanılabilir)
output.resultUrlstringMobilyalar yerleştirilmiş üretilen oda görüntüsüne URL
output.widthintegerPiksel cinsinden çıktı genişliği
output.heightintegerPiksel cinsinden çıktı yüksekliği

📊 Görev Durumu#

DurumAçıklama
UnprocessedGörev oluşturuldu ancak henüz başlamadı
ProcessingGörev şu anda işleniyor
SuccessGörev başarıyla tamamlandı — çıktı kullanılabilir
FailedGörev bir hata nedeniyle başarısız oldu

Her 3-5 saniye arayla sorgulayı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 Eylem
1001FAILEDİstek başarısız oldu (genel hata)Ayrıntılı hata bilgileri 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ı — e.g., imageUrl veya furnitureList eksik, ya da furnitureList 6 öğeyi aşıyorHem imageUrl hem de furnitureList sağlandığından, boş olmadığından ve 6 öğeden fazla içermediğinden emin olun
5002API_KEY_INVALIDGeçersiz veya eksik API AnahtarıAPIKEY başlığının mevcut olduğundan ve değerinin doğru olduğundan emin olun
9010SCAN_TEXT_ERRORMetin ifadesi içerik incelemesinden geçemediHassas veya yasaklı içeriği kaldırmak için ifadeyi değiştirin
9038PROHIBITED_CONTENTÜretilen çıktı görüntüsü yasaklı içerik barındırıyorİfadeyi/stili/girdileri ayarlayın ve yeniden deneyin
9051COINS_NOT_ENOUGHYetersiz jeton / krediHesap kredilerinizi yükleyin ve yeniden deneyin

📄 Yaygın API hata kodlarının tam listesi için Hata Kodu Referansı bölümüne başvurun.