Ideal House
Przejdź do treści

Dokumentacja API Zmiany Mebli#

Podstawowy URL: https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-05-21


📖 Przegląd#

API Zmiany Mebli umożliwia zmianę stylu lub wymianę mebli na obrazie wnętrza. Prześlij obraz źródłowy i opcjonalne wskazówki stylu, a następnie asynchronicznie sprawdzaj wynik zadania.

  1. Utwórz zadanie — Prześlij imageUrl i opcjonalne wskazówki, a następnie otrzymaj taskId.
  2. Sprawdzaj wyniki — Użyj taskId, aby zapytać o status zadania i obraz wyjściowy.

🔐 Uwierzytelnianie#

Wszystkie żądania API muszą zawierać klucz API w nagłówku żądania.

NagłówekWartość
APIKEYyour_api_key_here

💰 Odejmowanie kredytów#

[!WARNING] 🪙 1 kredyt jest odejmowany, gdy zadanie zostanie pomyślnie utworzone. Jeśli zadanie ostatecznie zawiedzie, odejęty kredyt zostanie automatycznie zwrócony.
Niewystarczające kredyty spowodują zwrócenie kodu błędu 9051. Zobacz Referencja odejmowania kredytów.

OperacjaOdejęte kredyty
Zadanie Zmiany Mebli1 kredyt

🎨 Opcje stylu#

Ten API obsługuje opcjonalne parametry stylu zwracane przez endpoint API Konfiguracja stylu.

Użyj:

Zwykły tekst
GET /api/v1/style/change_furniture/getStyles
Grupa styluPole żądaniaOpis
roomTypeindoorTypeIdOpcja typu pomieszczenia
styleindoorStyleIdOpcja stylu wnętrza
elementsindoorElemIdOpcja elementu pomieszczenia. Obsługuje wiele identyfikatorów opcji połączonych przecinkiem, na przykład id1,id2

Każda opcja zawiera:

PoleOpis
nameWielojęzyczna nazwa opcji
idWartość do przesłania w polu żądania
urlObraz podglądu opcji

📌 Endpoints API#

1. Utwórz zadanie Zmiany Mebli#

Endpoint

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

Nagłówki żądania

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

Ciało żądania

PoleTypWymaganeOpis
imageUrlstring✅ TakURL źródłowego obrazu wnętrza
promptstring❌ OpcjonalnieWskazówka tekstowa dla pożądanego wyniku
indoorTypeIdstring❌ OpcjonalnieIdentyfikator typu pomieszczenia z opcji stylu roomType
indoorStyleIdstring❌ OpcjonalnieIdentyfikator stylu wnętrza z opcji stylu style
indoorElemIdstring❌ OpcjonalnieIdentyfikator elementu pomieszczenia z opcji stylu elements. Obsługuje wiele identyfikatorów połączonych przecinkiem, na przykład id1,id2

Wymagane jest tylko imageUrl. Wszystkie inne pola są opcjonalne.

🖼️ Wymagania dotyczące obrazów: Użyj 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ły się w granicach 6,000 × 6,000 px przed przetwarzaniem. Adres URL obrazu musi być bezpośrednio dostępny dla serwera API.

📥 Przykłady żądań#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/changeFurniture/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "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 ChangeFurnitureApiExample {

    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",
                    "prompt": "replace the sofa with a modern warm neutral sofa",
                    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
                    "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/changeFurniture/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",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/changeFurniture/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 createChangeFurnitureTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/changeFurniture/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        prompt: 'replace the sofa with a modern warm neutral sofa',
        indoorTypeId: 'Interior Design_Interior Scene_Living Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Modern Country',
        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);
  }
}

createChangeFurnitureTask();

📤 Odpowiedź#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
PoleTypOpis
codeinteger0 oznacza sukces
messagestringKomunikat odpowiedzi
datalongIdentyfikator zadania do sprawdzania wyników

2. Pobierz wynik zadania#

Endpoint

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

Nagłówki żądania

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

Parametry zapytania

ParametrTypWymaganyOpis
taskIdlong✅ TakIdentyfikator zadania zwrócony przez endpoint tworzenia

📥 Przykłady żądań#

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

import java.io.IOException;

public class ChangeFurnitureResultExample {

    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/changeFurniture/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/changeFurniture/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":
    print("Result URL:", result["output"]["resultUrl"])
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 pollChangeFurnitureResult(taskId) {
  const headers = { APIKEY: API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/changeFurniture/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));
  }
}

pollChangeFurnitureResult(1234567890123456789n);

📤 Przykład odpowiedzi#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/change_furniture_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Odpowiedź (Zadanie w trakcie przetwarzania / W kolejce)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa"
    },
    "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"
    },
    "output": null
  }
}

📊 Status zadania#

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

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


❌ Odpowiedzi błędów#

KodNazwaOpis
1011PARAM_ERRORBłąd parametru żądania
5002API_KEY_INVALIDNieprawidłowy lub brakujący klucz API
9010SCAN_TEXT_ERRORWskazówka tekstowa nie przeszła weryfikacji treści
9038PROHIBITED_CONTENTWygenerowany obraz zawiera treści zakazane
9051COINS_NOT_ENOUGHNiewystarczające kredyty

Pełne definicje wspólnych błędów znajdziesz w Referencji kodów błędów.