Ideal House
Naar inhoud gaan

Documentatie voor de API voor meubelvervanging#

Basis-URL: https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-05-21


📖 Overzicht#

De API voor meubelvervanging verandert de stijl of meubels in een interieurafbeelding. Dien een bronafbeelding en optionele stijlaanwijzingen in en vraag het taakresultaat vervolgens asynchroon op.

  1. Een taak aanmaken — Dien imageUrl en optionele aanwijzingen in en ontvang een taskId.
  2. Resultaten regelmatig opvragen — Gebruik taskId om de taakstatus en uitvoerafbeelding op te vragen.

🔐 Authenticatie#

Alle API-verzoeken moeten een API-sleutel in de verzoekheader bevatten.

VerzoekheaderWaarde
APIKEYyour_api_key_here

💰 Creditafschrijving#

[!WARNING] 🪙 Bij het succesvol aanmaken van een taak wordt 1 tegoedeenheid afgeschreven. Als de taak uiteindelijk mislukt, wordt de afgeschreven credit automatisch terugbetaald.
Onvoldoende credits leveren foutcode 9051 op. Zie de referentie voor creditafschrijving.

BewerkingAfgeschreven credits
Taak voor meubelvervanging1 tegoedeenheid

🎨 Stijlopties#

Deze API ondersteunt optionele stijlparameters die het endpoint voor API-stijlconfiguratie retourneert.

Gebruik:

Platte tekst
GET /api/v1/style/change_furniture/getStyles
StijlgroepVerzoekveldBeschrijving
roomTypeindoorTypeIdOptie voor het kamertype
styleindoorStyleIdOptie voor de interieurstijl
elementsindoorElemIdOptie voor kamerelementen. Ondersteunt meerdere optie-ID's gescheiden door komma's, bijvoorbeeld id1,id2

Elke optie bevat:

VeldBeschrijving
nameMeertalige optienaam
idWaarde om in het verzoekveld door te geven
urlVoorbeeldafbeelding van de optie

📌 API-endpoints#

1. Een taak voor meubelvervanging aanmaken#

Eindpunt

Platte tekst
POST /api/v1/changeFurniture/generate

Verzoekheaders

VerzoekheaderVerplichtBeschrijving
APIKEY✅ JaJe API-authenticatiesleutel
Content-Type✅ Jaapplication/json

Verzoekinhoud

VeldTypeVerplichtBeschrijving
imageUrlstring✅ JaURL van de oorspronkelijke interieurafbeelding
promptstring❌ OptioneelTekstinstructie voor het gewenste resultaat
indoorTypeIdstring❌ OptioneelKamertype-ID uit de stijlopties roomType
indoorStyleIdstring❌ OptioneelInterieurstijl-ID uit de stijlopties style
indoorElemIdstring❌ OptioneelKamerelement-ID uit de stijlopties elements. Ondersteunt meerdere ID's gescheiden door komma's, bijvoorbeeld id1,id2

Alleen imageUrl is verplicht. Alle andere velden zijn optioneel.

🖼️ Afbeeldingsvereisten: Gebruik JPG/JPEG, PNG of WebP. Elke afbeelding mag maximaal 20 MB groot zijn, met afmetingen van 128 × 128 px tot en met 6,000 × 6,000 px. Afbeeldingen boven de maximale pixelafmetingen worden vóór verwerking automatisch evenredig verkleind tot binnen 6,000 × 6,000 px. De afbeeldings-URL moet rechtstreeks bereikbaar zijn voor de API-server.

📥 Verzoekvoorbeelden#

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

📤 Antwoord#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
VeldTypeBeschrijving
codeinteger0 geeft succes aan
messagestringAntwoordbericht
datalongTaak-ID voor het regelmatig opvragen van resultaten

2. Taakresultaat ophalen#

Eindpunt

Platte tekst
GET /api/v1/changeFurniture/result

Verzoekheaders

VerzoekheaderVerplichtBeschrijving
APIKEY✅ JaJe API-authenticatiesleutel

Queryparameters

QueryparameterTypeVerplichtBeschrijving
taskIdlong✅ JaTaak-ID die het aanmaakendpoint retourneert

📥 Verzoekvoorbeelden#

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

📤 Antwoordvoorbeeld#

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

Antwoord: taak in verwerking of in de wachtrij

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

Antwoord: taak mislukt

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

📊 Taakstatus#

StatusBeschrijving
UnprocessedDe taak is aangemaakt en wacht in de wachtrij
ProcessingDe taak wordt momenteel uitgevoerd
SuccessDe taak is succesvol voltooid
FailedDe taak is mislukt en er is geen uitvoer geproduceerd

Vraag de status elke 3-5 seconden op. Zie de taaklimiet voor de API.


❌ Foutantwoorden#

CodeNaamBeschrijving
1011PARAM_ERRORFout in verzoekparameters
5002API_KEY_INVALIDOngeldige of ontbrekende API-sleutel
9010SCAN_TEXT_ERRORTekstinstructie afgekeurd bij inhoudscontrole
9038PROHIBITED_CONTENTDe gegenereerde afbeelding bevat verboden inhoud
9051COINS_NOT_ENOUGHOnvoldoende tegoed

Zie de foutcodereferentie voor de volledige definities van algemene fouten.