Ideal House
Przejdź do treści

Dokumentacja API wirtualnego przymierzania mebli#

Podstawowy URL: https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-03-09


📖 Przegląd#

API wirtualnego przymierzania mebli umożliwia wirtualne umieszczenie elementów mebli w scenie pokoju za pomocą AI. Podajesz obraz pokoju oraz listę elementów mebli (każdy z obrazem i identyfikatorem produktu), a AI bezszwowo komponuje meble w scenie. Praca jest asynchroniczna i obejmuje dwa kroki:

  1. Utwórz zadanie — Prześlij obraz pomieszczenia i listę mebli, a następnie otrzymasz taskId.
  2. Sprawdzaj wyniki — Użyj taskId, aby zapytać o status zadania i pobrać wygenerowany obraz.

📌 Uwaga: Obecnie obsługiwany jest tylko tryb creative.


🔐 Uwierzytelnianie#

Wszystkie żądania API muszą być uwierzytelniane za pomocą klucza API Key.

Włącz swój klucz API w nagłówku żądania:

NagłówekWartość
APIKEYyour_api_key_here

⚠️ Utrzymuj swój klucz API w poufności. Nie ujawniaj go w kodzie klienckim ani w publicznych repozytoriach.


💰 Odejmowanie kredytów#

[!WARNING] 🪙 Kredyty są pobierane na podstawie wybranego modelType po pomyślnym utworzeniu zadania. Jeśli zadanie ostatecznie zawiedzie, pobrane kredyty zostaną automatycznie zwrócone na Twoje konto.
Niewystarczająca liczba kredytów spowoduje zwrócenie kodu błędu 9051. 📄 Zobacz Odniesienie do odejmowania kredytów.

Model (modelType)Odejmowane kredyty
Base3 kredyty
Pro10 kredyty

📌 API Punkty końcowe#


1. Utwórz zadanie wirtualnego przymierzania mebli#

Tworzy nowe zadanie AI wirtualnego przymierzania mebli i zwraca unikalny taskId do cyklicznego sprawdzania statusu.

Punkt końcowy

Zwykły tekst
POST /api/v1/furnitureTryOn/generate

Nagłówki żądania

NagłówekWymaganeOpis
APIKEY✅ TakTwój klucz uwierzytelniający API
Content-Type✅ Takapplication/json

Ciało żądania

PoleTypWymaganeOpis
imageUrlstring✅ TakURL obrazu sceny pomieszczenia, do którego zostaną umieszczone meble
furnitureListarray✅ TakLista elementów meblowych do umieszczenia w scenie. Maksymalnie 6 elementów. Zobacz Obiekt elementu meblowego
promptstring❌ OpcjonalnieWłasny prompt tekstowy, który dodatkowo kieruje umieszczeniem i stylizacją
modelTypestring❌ OpcjonalnieTyp jakości modelu. Enum: Base, Pro. Domyślnie Base

🛋️ Obiekt elementu meblowego#

Każdy element w furnitureList musi być obiektem z następującymi polami:

PoleTypWymaganeOpis
imageUrlstring✅ TakURL obrazu produktu meblowego (zalecane tło przezroczyste lub czyste)

⚠️ furnitureList może zawierać maksymalnie 6 elementów.

🖼️ Wymagania dotyczące obrazów: Obraz pomieszczenia i każdy obraz mebla muszą używać formatu JPG/JPEG, PNG lub WebP. Każdy obraz nie może być większy niż 20 MB, a jego wymiary muszą mieścić się w przedziale od 128 × 128 px do 6,000 × 6,000 px (włącznie). Obrazy przekraczające maksymalne wymiary pikseli są automatycznie skalowane proporcjonalnie, aby zmieścić się w 6,000 × 6,000 px przed przetwarzaniem. Adresy URL muszą być bezpośrednio dostępne dla serwera API.

Przykład

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

Typy modeli

WartośćOpis
BaseDomyślny. Zbalansowana prędkość i jakość
ProWyższa jakość wyjścia, wolniejsze przetwarzanie

📥 Przykłady żądań#

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();

📤 Odpowiedź#

Odpowiedź sukcesu

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
PoleTypOpis
codeinteger0 wskazuje sukces
messagestringKomunikat odpowiedzi
datalongUnikalny identyfikator zadania do cyklicznego sprawdzania wyników

2. Pobranie wyniku zadania#

Pobiera bieżący status i wynik wcześniej utworzonego zadania wirtualnego przymierzania mebli.

Punkt końcowy

Zwykły tekst
GET /api/v1/furnitureTryOn/result

Nagłówki żądania

NagłówekWymaganeOpis
APIKEY✅ TakTwój klucz uwierzytelniający API

Parametry zapytania

ParametrTypWymaganeOpis
taskIdlong✅ TakIdentyfikator zadania zwrócony z punktu końcowego tworzenia zadania

📥 Przykłady żądań#

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);

📤 Odpowiedź#

Odpowiedź sukcesu (Zadanie zakończone)

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
    }
  }
}

Odpowiedź (Zadanie w trakcie / W kolejce)

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
  }
}

Odpowiedź (Zadanie nie powiodło się)

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
  }
}

Pola odpowiedzi

PoleTypOpis
idlongUnikalny identyfikator zadania
statusstringBieżący status zadania (zobacz Status zadania)
waitNumberintegerLiczba zadań przed Tobą w kolejce (0 oznacza, że zadanie jest obecnie przetwarzane)
percentageintegerProcent ukończenia zadania (0–100)
inputobjectOryginalne parametry wejściowe zadania
input.imageUrlstringAdres URL obrazu sceny pomieszczenia
input.furnitureListarrayLista przesłanych elementów meblowych (maks. 6 elementów)
input.furnitureList[].imageUrlstringAdres URL obrazu produktu meblowego
input.promptstringWłasny prompt tekstowy (jeśli podano)
input.modelTypestringUżyty typ modelu
outputobjectWynik generowania (dostępny tylko, gdy status wynosi Success)
output.resultUrlstringAdres URL do wygenerowanego obrazu pomieszczenia z umieszczonymi meblami
output.widthintegerSzerokość wyjściowa w pikselach
output.heightintegerWysokość wyjściowa w pikselach

📊 Status zadania#

StatusOpis
UnprocessedZadanie zostało utworzone, ale nie zostało jeszcze rozpoczęte
ProcessingZadanie jest obecnie przetwarzane
SuccessZadanie zakończyło się pomyślnie — wynik jest dostępny
FailedZadanie nie powiodło się z powodu błędu

Wykonuj cykliczne sprawdzanie co 3-5 sekund. Zobacz Limit zadań API.


❌ Odpowiedzi błędów#

Wszystkie odpowiedzi błędów mają tę samą strukturę JSON:

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

Odniesienie do kodów błędów#

KodNazwaOpisZalecana czynność
1001FAILEDŻądanie nie powiodło się (błąd ogólny)Sprawdź pole message, aby uzyskać szczegółowe informacje o błędzie
1003INTERNAL_ERRORBłąd wewnętrzny serweraPonów po krótkim opóźnieniu; skontaktuj się z pomocą techniczną, jeśli problem trwa
1011PARAM_ERRORBłąd parametru żądania — np. np., brak imageUrl lub furnitureList, lub furnitureList przekracza 6 elementówUpewnij się, że zarówno imageUrl, jak i furnitureList są podane, niepuste i zawierają nie więcej niż 6 elementów
5002API_KEY_INVALIDNieprawidłowy lub brakujący klucz APIUpewnij się, że nagłówek APIKEY jest obecny i wartość jest poprawna
9010SCAN_TEXT_ERRORPrompt tekstowy nie przeszedł weryfikacji treściZmodyfikuj prompt, aby usunąć wszelką wrażliwą lub zakazaną treść
9038PROHIBITED_CONTENTWygenerowany obraz wyjściowy zawiera zakazane treściDostosuj prompt/styl/wejścia i ponów
9051COINS_NOT_ENOUGHNiewystarczające monety / kredytyDoładuj kredyty na swoim koncie i spróbuj ponownie

📄 Pełną listę powszechnych kodów błędów API znajdziesz w Referencji kodów błędów.