Ideal House
Przejdź do treści

Dokumentacja Virtual Staging API#

Podstawowy URL: https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-04-13


📖 Przegląd#

Virtual Staging API umożliwia projektowanie pustego lub częściowo umeblowanego pokoju za pomocą AI.
Przesyłasz adres URL obrazu pokoju oraz opcjonalny tekstowy opis, a następnie pobierasz wygenerowany wynik asynchronicznie.

  1. Utworzenie zadania — Prześlij imageUrl i opcjonalny prompt, a następnie otrzymasz taskId.
  2. Cykliczne sprawdzanie wyników — Użyj taskId, aby sprawdzić status zadania i pobrać obraz wyjściowy.

🔐 Uwierzytelnianie#

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

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] 🪙 1 kredyt jest odejmowany, gdy zadanie zostanie pomyślnie utworzone.
Jeśli zadanie ostatecznie zawiedzie, odejmowany kredyt zostanie automatycznie zwrócony.
Niewystarczająca liczba kredytów spowoduje zwrócenie kodu błędu 9051. 📄 Zobacz Odniesienie do odejmowania kredytów.

OperacjaOdejmowane kredyty
Zadanie Virtual Staging1 kredyt

📌 API Punkty końcowe#


1. Utworzenie zadania Virtual Staging#

Tworzy nowe zadanie virtual staging i zwraca unikalny taskId do cyklicznego sprawdzania.

Punkt końcowy

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

Nagłówki żądania

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

Ciało żądania

PoleTypWymaganeOpis
imageUrlstring✅ TakURL źródłowego obrazu pokoju
promptstring❌ NieOpcjonalny prompt kierujący stylem i umeblowaniem
indoorTypeIdstring❌ NieOpcjonalny preset typu pokoju. Zobacz Opcje typów wnętrz
indoorStyleIdstring❌ NieOpcjonalny preset stylu wnętrza. Zobacz Opcje stylów wnętrz
indoorElemIdstring❌ NieOpcjonalny preset elementów pokoju. Obsługuje wiele ID połączonych przecinkiem, na przykład id1,id2

🖼️ Wymagania dotyczące obrazów: Użyj 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 w pikselach są automatycznie skalowane proporcjonalnie tak, aby mieściły się w granicach 6,000 × 6,000 px przed rozpoczęciem przetwarzania. Adres URL obrazu musi być bezpośrednio dostępny dla serwera API.


🎨 Opcje stylów#

indoorTypeId, indoorStyleId i indoorElemId można wybrać z punktu końcowego Konfiguracja stylów API.

Użyj:

Zwykły tekst
GET /api/v1/style/virtual_staging/getStyles
Grupa stylówPole żądaniaOpis
roomTypeindoorTypeIdOpcja typu pokoju
styleindoorStyleIdOpcja stylu wnętrza
elementsindoorElemIdOpcja elementów pokoju. Obsługuje wiele ID opcji połączonych przecinkiem, na przykład id1,id2

Każda opcja zawiera name, id i url. Przekazuj id opcji do odpowiedniego pola żądania.


📥 Przykłady żądań#

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

📤 Odpowiedź#

Odpowiedź sukcesu

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
PoleTypOpis
codeinteger0 oznacza 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 virtual staging.

Punkt końcowy

Zwykły tekst
GET /api/v1/virtualStaging/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/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);

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

Odpowiedź (Zadanie w trakcie / W kolejce)

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

Odpowiedź (Zadanie nie powiodło się)

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

Pola odpowiedzi

PoleTypOpis
idlongUnikalny identyfikator zadania
statusstringBieżący status zadania (zobacz Status zadania)
waitNumberintegerLiczba zadań przed obecnym w kolejce (0 oznacza przetwarzanie w toku)
percentageintegerProcent ukończenia zadania (0-100)
errorReasonstringPowód niepowodzenia, gdy status wynosi Failed
inputobjectOryginalne parametry wejściowe przesłane dla tego zadania
input.imageUrlstringAdres URL obrazu źródłowego pokoju
input.promptstringPrompt użytkownika (jeśli podano)
input.indoorTypeIdstringUżyty preset typu pokoju (jeśli podano)
input.indoorStyleIdstringUżyty preset stylu wnętrza (jeśli podano)
input.indoorElemIdstringUżyty preset elementów pokoju (jeśli podano). Może zawierać wiele ID połączonych przecinkiem
outputobjectWynik generowania (dostępny tylko, gdy status wynosi Success)
output.resultUrlstringAdres URL wygenerowanego obrazu wyniku wirtualnego wystroju
output.widthintegerSzerokość obrazu wyjściowego w pikselach
output.heightintegerWysokość obrazu wyjściowego w pikselach

📊 Status zadania#

StatusZnaczenie
UnprocessedZadanie zostało utworzone i czeka w kolejce
ProcessingZadanie jest obecnie w trakcie
SuccessZadanie zakończono pomyślnie
FailedZadanie nie powiodło się i nie wygenerowano wyniku

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
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 (na przykład brak imageUrl)Upewnij się, że imageUrl jest podany i jest prawidłowym adresem URL
5002API_KEY_INVALIDNieprawidłowy lub brakujący klucz APIUpewnij się, że nagłówek APIKEY jest obecny i poprawny
9010SCAN_TEXT_ERRORPrompt nie przeszedł moderacji treściZmień prompt, aby usunąć wrażliwe lub zakazane treści
9038PROHIBITED_CONTENTWygenerowany obraz wyjściowy zawiera zakazane treściDostosuj prompt/styl/wejścia i ponów
9051COINS_NOT_ENOUGHNiewystarczająca liczba kredytówDoładuj kredyty i ponów

📄 Pełne definicje wspólnych błędów znajdziesz w Odniesieniu do kodów błędów.