Ideal House
Naar inhoud gaan

Documentatie voor de API voor objectverwijdering#

Basis-URL: https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-03-06


📖 Overzicht#

Met de API voor objectverwijdering kun je met AI ongewenste objecten of meubels uit interieurafbeeldingen verwijderen. Er zijn twee modi:

  • single_furniture — Verwijder een specifiek meubel met een maskerafbeelding die het doelgebied aangeeft. De AI vult het verwijderde gebied intelligent op voor een schoon, natuurlijk resultaat.
  • whole_house — Verwijder automatisch alle meubels uit de hele kamer zonder masker.

De werkstroom is asynchroon en bestaat uit twee stappen:

  1. Een taak aanmaken — Dien je bronafbeelding, masker en parameters in en ontvang een taskId.
  2. Resultaten regelmatig opvragen — Gebruik de taskId om de taakstatus op te vragen en de resultaatafbeelding op te halen.

🔐 Authenticatie#

Alle API-verzoeken moeten worden geauthenticeerd met een API Key.

Neem je API Key op in de verzoekheader:

VerzoekheaderWaarde
APIKEYyour_api_key_here

⚠️ Houd je API Key geheim. Maak deze niet zichtbaar in clientcode of openbare opslagplaatsen.


💰 Creditafschrijving#

[!WARNING] 🪙 Elke taak kost 1 tegoedeenheid, afgeschreven van je account zodra de taak succesvol is aangemaakt. Als de taak uiteindelijk mislukt, worden de afgeschreven credits automatisch terugbetaald op je account.
Onvoldoende credits leveren foutcode 9051 op. 📄 Zie de referentie voor creditafschrijving.


🖼️ Formaat van de maskerafbeelding#

De maskerafbeelding bepaalt het gebied dat uit de bronafbeelding moet worden verwijderd.

Maskerregels:

KleurBetekenis
ZwartGebied om te verwijderen: het object of gebied dat moet worden gewist
WitGebied om te behouden: de achtergrond die blijft staan

⚠️ De maskerafbeelding moet dezelfde afmetingen hebben als de bronafbeelding (imageUrl).

Maskervoorbeeld:

Voorbeeld van een masker

Het zwarte maskergebied geeft de te verwijderen meubels aan; het witte gebied is de te behouden achtergrond.


📌 API-endpoints#


1. Een taak voor objectverwijdering aanmaken#

Maakt een nieuwe AI-taak voor objectverwijdering aan en retourneert een unieke taskId om de status regelmatig op te vragen.

Eindpunt

Platte tekst
POST /api/v1/objectRemover/generate

Verzoekheaders

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

Verzoekinhoud

VeldTypeVerplichtBeschrijving
imageUrlstring✅ JaURL van de bronafbeelding
emptyTypestring✅ JaVerwijderingsmodus. Mogelijke waarden: whole_house, single_furniture. Bepaalt hoe de AI het verwijderde gebied opvult
maskUrlstring⚠️ Verplicht wanneer emptyType=single_furnitureURL van de maskerafbeelding. Zwarte gebieden worden verwijderd; witte gebieden blijven behouden. Werkt alleen in de modus single_furniture
maskBase64string⚠️ Verplicht wanneer emptyType=single_furnitureBase64-gecodeerde maskerafbeelding; PNG wordt aanbevolen. Alternatief voor maskUrl. Werkt alleen in de modus single_furniture

⚠️ Maskervereisten per modus:

  • single_furniture — Minstens een van maskUrl of maskBase64 moet worden opgegeven. Als beide worden opgegeven, heeft maskUrl voorrang.
  • whole_house — Maskervelden worden genegeerd. De AI verwijdert automatisch alle meubels uit de hele kamer.

🖼️ Afbeeldingsvereisten: De bronafbeelding en het masker moeten JPG/JPEG, PNG of WebP gebruiken. 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. Afbeeldings-URLs moeten rechtstreeks bereikbaar zijn voor de API-server. Voor een Base64-masker gelden na decodering dezelfde afbeeldingslimieten en het mag geen data-URL-voorvoegsel bevatten.


Opties voor de verwijderingsmodus

WaardeMasker verplichtBeschrijving
single_furniture✅ JaVerwijdert een specifiek meubel dat het masker aangeeft en vult het gebied natuurlijk op
whole_house❌ NeeVerwijdert automatisch alle meubels uit de hele kamer; geen masker nodig

📥 Verzoekvoorbeelden#

cURL
bash
# single_furniture mode — mask required (using maskUrl)
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "single_furniture",
    "maskUrl": "https://example.com/mask.png"
  }'

# single_furniture mode — mask required (using maskBase64)
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "single_furniture",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }'

# whole_house mode — no mask needed
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "whole_house"
  }'
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class ObjectRemoverApiExample {

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

        // Option 1: Use maskUrl
        String requestBody = """
            {
                "imageUrl": "https://example.com/room.jpg",
                "maskUrl": "https://example.com/mask.png",
                "emptyType": "single_furniture"
            }
            """;

        // Option 2: Use maskBase64 (encode local mask file)
        // byte[] maskBytes = Files.readAllBytes(Path.of("/path/to/mask.png"));
        // String maskBase64 = Base64.getEncoder().encodeToString(maskBytes);
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "maskBase64": "%s",
        //         "emptyType": "single_furniture"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/objectRemover/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
import base64

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Option 1: Use maskUrl
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "maskUrl": "https://example.com/mask.png",
    "emptyType": "single_furniture"
}

# Option 2: Use maskBase64 (encode local mask file)
# with open("/path/to/mask.png", "rb") as f:
#     mask_base64 = base64.b64encode(f.read()).decode("utf-8")
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "maskBase64": mask_base64,
#     "emptyType": "single_furniture"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/objectRemover/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 fs = require('fs');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createObjectRemoverTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      maskUrl: 'https://example.com/mask.png',
      emptyType: 'single_furniture'
    };

    // Option 2: Use maskBase64 (encode local mask file)
    // const maskBuffer = fs.readFileSync('/path/to/mask.png');
    // const maskBase64 = maskBuffer.toString('base64');
    // const payload = {
    //   imageUrl: 'https://example.com/room.jpg',
    //   maskBase64: maskBase64,
    //   emptyType: 'single_furniture'
    // };

    const response = await axios.post(
      `${BASE_URL}/api/v1/objectRemover/generate`,
      payload,
      {
        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);
  }
}

createObjectRemoverTask();

📤 Antwoord#

Succesantwoord

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

2. Taakresultaat ophalen#

Haalt de huidige status en uitvoer van een eerder aangemaakte taak voor objectverwijdering op.

Eindpunt

Platte tekst
GET /api/v1/objectRemover/result

Verzoekheaders

VerzoekheaderVerplichtBeschrijving
APIKEY✅ JaJe API-authenticatiesleutel

Queryparameters

QueryparameterTypeVerplichtBeschrijving
taskIdlong✅ JaDe taak-ID die het endpoint voor het aanmaken van taken retourneert

📥 Verzoekvoorbeelden#

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

public class ObjectRemoverResultExample {

    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/objectRemover/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/objectRemover/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":
    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 pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

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

    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Antwoord#

Succesantwoord: taak voltooid

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "maskUrl": "https://example.com/mask.png",
      "emptyType": "single_furniture"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/object_remover_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": 50,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "maskUrl": "https://example.com/mask.png",
      "emptyType": "single_furniture"
    },
    "output": null
  }
}

Antwoord: taak mislukt

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

Antwoordvelden

VeldTypeBeschrijving
idlongUnieke taakidentificatie
statusstringHuidige taakstatus; zie taakstatus
waitNumberintegerAantal taken vóór deze taak in de wachtrij; 0 betekent dat de taak wordt verwerkt
percentageintegerVoltooiingspercentage van de taak (0–100)
inputobjectDe oorspronkelijke invoerparameters van de taak
input.imageUrlstringURL van de bronafbeelding
input.maskUrlstringURL van de maskerafbeelding, indien opgegeven via maskUrl
input.emptyTypestringGebruikte verwijderingsmodus: single_furniture of whole_house
outputobjectGeneratieresultaat, alleen beschikbaar wanneer status gelijk is aan Success
output.resultUrlstringURL van de resultaatafbeelding met verwijderde objecten
output.widthintegerUitvoerbreedte in pixels
output.heightintegerUitvoerhoogte in pixels

📊 Taakstatus#

StatusBeschrijving
UnprocessedDe taak is aangemaakt, maar nog niet gestart
ProcessingDe taak wordt momenteel verwerkt
SuccessDe taak is succesvol voltooid; uitvoer is beschikbaar
FailedDe taak is door een fout mislukt

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


❌ Foutantwoorden#

Alle foutantwoorden hebben dezelfde JSON-structuur:

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

Foutcodereferentie#

CodeNaamBeschrijvingAanbevolen actie
1001FAILEDVerzoek mislukt: algemene foutControleer het veld message voor specifieke foutdetails
1003INTERNAL_ERRORInterne serverfoutProbeer het na een korte wachttijd opnieuw; neem contact op met ondersteuning als de fout blijft optreden
1011PARAM_ERRORFout in verzoekparameters — e.g., zowel maskUrl als maskBase64 ontbreektGeef minstens één maskerveld op
5002API_KEY_INVALIDOngeldige of ontbrekende API KeyControleer dat de header APIKEY aanwezig is en de waarde klopt
9038PROHIBITED_CONTENTDe gegenereerde uitvoerafbeelding bevat verboden inhoudPas instructie, stijl of invoer aan en probeer opnieuw
9051COINS_NOT_ENOUGHOnvoldoende munten / creditsVul je accountcredits aan en probeer opnieuw

📄 Raadpleeg de foutcodereferentie voor de volledige lijst van algemene API-foutcodes.