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:
- Görev oluştur — Oda görüntünüzü ve mobilya listenizi gönderin, ardından bir
taskIdalın. - Sonuçları sorgulama — Görev durumunu sorgulamak ve üretilen görüntüyü almak için
taskIdkullanın.
📌 Not: Şu anda yalnızca
creativemodu 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ı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] 🪙 Krediler, görev başarıyla oluşturulduğunda seçilen
modelTypetemelinde düşülür. Görev nihayetinde başarısız olursa, düşülen krediler hesabınıza otomatik olarak iade edilir.
Yetersiz krediler9051hata kodunu döndürür. 📄 Kredi Kesintisi Referansı bölümüne bakın.
Model (modelType) | Kesilen Kredi |
|---|---|
Base | 3 kredi |
Pro | 10 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
POST /api/v1/furnitureTryOn/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 | Mobilyaların yerleştirileceği oda sahnesi görüntüsünün URL |
furnitureList | array | ✅ Evet | Sahneye yerleştirilecek mobilya öğeleri listesi. En fazla 6 öğe. Mobilya Öğesi Nesnesi bkz. |
prompt | string | ❌ İsteğe Bağlı | Yerleşimi ve stilizasyonu daha fazla yönlendirmek için özel metin istemi |
modelType | string | ❌ İ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:
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
imageUrl | string | ✅ Evet | Mobilya ürün görselinin URL (şeffaf veya temiz arka plan önerilir) |
⚠️
furnitureListen 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
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/table.png"
}
]
Model Türleri
| Değer | Açıklama |
|---|---|
Base | Varsayılan. Hız ve kalite dengesi |
Pro | Daha yüksek kalite çıktı, daha yavaş işleme |
📥 İstek Örnekleri#
cURL
# 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)
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)
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)
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
{
"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 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
GET /api/v1/furnitureTryOn/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 kimliği |
📥 İstek Örnekleri#
cURL
curl -X GET "https://api.ideal.house/api/v1/furnitureTryOn/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
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)
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)
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ı)
{
"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)
{
"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)
{
"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ı
| Alan | Tür | Açıklama |
|---|---|---|
id | long | Görev benzersiz tanımlayıcısı |
status | string | Mevcut görev durumu (Görev Durumu bölümüne bakın) |
waitNumber | integer | Kuyrukta öndeki görev sayısı (0 şu anda işleniyor demektir) |
percentage | integer | Görev tamamlanma yüzdesi (0–100) |
input | object | Görevin orijinal girdi parametreleri |
input.imageUrl | string | Oda sahnesi görüntüsü URL |
input.furnitureList | array | Gönderilen mobilya ürünleri listesi (en fazla 6 öğe) |
input.furnitureList[].imageUrl | string | Mobilya ürün görseli URL |
input.prompt | string | Özel metin istemi (verildiyse) |
input.modelType | string | Kullanılan model türü |
output | object | Üretim sonucu (yalnızca status Success olduğunda kullanılabilir) |
output.resultUrl | string | Mobilyalar yerleştirilmiş üretilen oda görüntüsüne URL |
output.width | integer | Piksel cinsinden çıktı genişliği |
output.height | integer | Piksel cinsinden çıktı yüksekliği |
📊 Görev Durumu#
| Durum | Açıklama |
|---|---|
Unprocessed | Görev oluşturuldu ancak henüz başlamadı |
Processing | Görev şu anda işleniyor |
Success | Görev başarıyla tamamlandı — çıktı kullanılabilir |
Failed | Gö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:
{
"code": 5002,
"message": "Invalid API Key",
"data": null
}
Hata Kodu Referansı#
| Kod | Ad | Açıklama | Önerilen Eylem |
|---|---|---|---|
1001 | FAILED | İstek başarısız oldu (genel hata) | Ayrıntılı hata bilgileri 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ı — e.g., imageUrl veya furnitureList eksik, ya da furnitureList 6 öğeyi aşıyor | Hem imageUrl hem de furnitureList sağlandığından, boş olmadığından ve 6 öğeden fazla içermediğinden emin olun |
5002 | API_KEY_INVALID | Geçersiz veya eksik API Anahtarı | APIKEY başlığının mevcut olduğundan ve değerinin doğru olduğundan emin olun |
9010 | SCAN_TEXT_ERROR | Metin ifadesi içerik incelemesinden geçemedi | Hassas veya yasaklı içeriği kaldırmak için ifadeyi değiştirin |
9038 | PROHIBITED_CONTENT | Üretilen çıktı görüntüsü yasaklı içerik barındırıyor | İfadeyi/stili/girdileri ayarlayın ve yeniden deneyin |
9051 | COINS_NOT_ENOUGH | Yetersiz jeton / kredi | Hesap 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.