Ideal House
Naar inhoud gaan

Documentatie voor de API voor intelligent vervangen#

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


📖 Overzicht#

Met de API voor intelligent vervangen kun je een geselecteerd gebied in een afbeelding vervangen door AI-gegenereerde inhoud op basis van je tekstinstructie. Je levert een bronafbeelding, een maskerafbeelding die het te vervangen gebied bepaalt en een tekstinstructie die beschrijft wat dat gebied moet vullen. De AI verwerkt de gegenereerde inhoud naadloos in de oorspronkelijke afbeelding. De werkstroom is asynchroon en bestaat uit twee stappen:

  1. Een taak aanmaken — Dien je afbeelding, masker en instructie 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 in de bronafbeelding dat moet worden vervangen.

Maskerregels:

KleurBetekenis
ZwartGebied om te vervangen: hier wordt nieuwe inhoud gegenereerd
WitGebied om te behouden: de achtergrond blijft ongewijzigd

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

Maskervoorbeeld:

Voorbeeld van een masker

Het zwarte maskergebied geeft aan waar de AI inhoud moet vervangen; het witte gebied is de te behouden achtergrond.


📌 API-endpoints#


1. Een taak voor intelligent vervangen aanmaken#

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

Eindpunt

Platte tekst
POST /api/v1/smartReplace/generate

Verzoekheaders

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

Verzoekinhoud

VeldTypeVerplichtBeschrijving
imageUrlstring✅ JaURL van de bronafbeelding
promptstring✅ JaTekstinstructie die de te genereren inhoud in het gemaskeerde gebied beschrijft (e.g., "a modern armchair", "marble flooring")
maskUrlstring⚠️ maskUrl of maskBase64URL van de maskerafbeelding. Zwarte gebieden worden vervangen; witte gebieden blijven behouden
maskBase64string⚠️ maskUrl of maskBase64Base64-gecodeerde maskerafbeelding; PNG wordt aanbevolen. Gebruik dit als je geen gehoste URL kunt opgeven

⚠️ Geef minstens een van maskUrl of maskBase64 op. Als beide worden opgegeven, heeft maskUrl voorrang.

🖼️ 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.


📥 Verzoekvoorbeelden#

cURL
bash
# Using maskUrl
curl -X POST "https://api.ideal.house/api/v1/smartReplace/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "a modern velvet sofa in dark blue",
    "maskUrl": "https://example.com/mask.png"
  }'

# Using maskBase64
curl -X POST "https://api.ideal.house/api/v1/smartReplace/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "a modern velvet sofa in dark blue",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }'
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 SmartReplaceApiExample {

    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",
                "prompt": "a modern velvet sofa in dark blue",
                "maskUrl": "https://example.com/mask.png"
            }
            """;

        // 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",
        //         "prompt": "a modern velvet sofa in dark blue",
        //         "maskBase64": "%s"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/smartReplace/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",
    "prompt": "a modern velvet sofa in dark blue",
    "maskUrl": "https://example.com/mask.png"
}

# 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",
#     "prompt": "a modern velvet sofa in dark blue",
#     "maskBase64": mask_base64
# }

response = requests.post(
    f"{BASE_URL}/api/v1/smartReplace/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 createSmartReplaceTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      prompt: 'a modern velvet sofa in dark blue',
      maskUrl: 'https://example.com/mask.png'
    };

    // 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',
    //   prompt: 'a modern velvet sofa in dark blue',
    //   maskBase64: maskBase64
    // };

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

createSmartReplaceTask();

📤 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 intelligent vervangen op.

Eindpunt

Platte tekst
GET /api/v1/smartReplace/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/smartReplace/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;
import java.io.IOException;

public class SmartReplaceResultExample {

    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/smartReplace/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/smartReplace/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/smartReplace/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",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/smart_replace_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/room.jpg",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "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",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "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.promptstringTekstinstructie die de vervangende inhoud beschrijft
input.maskUrlstringURL van de maskerafbeelding, indien opgegeven via maskUrl
outputobjectGeneratieresultaat, alleen beschikbaar wanneer status gelijk is aan Success
output.resultUrlstringURL van de resultaatafbeelding met intelligent vervangen inhoud
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., prompt of het masker ontbreektGeef zowel prompt als minstens één maskerveld op
5002API_KEY_INVALIDOngeldige of ontbrekende API KeyControleer dat de header APIKEY aanwezig is en de waarde klopt
9010SCAN_TEXT_ERRORTekstinstructie afgekeurd bij inhoudscontrolePas de instructie aan om gevoelige of verboden inhoud te verwijderen
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.