Documentatie voor de API voor virtuele meubelplaatsing#
Basis-URL:
https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-03-09
📖 Overzicht#
Met de API voor virtuele meubelplaatsing kun je meubels met AI in een kamerscène plaatsen. Je levert een kamerafbeelding en een lijst meubels, elk met een afbeelding en product-ID, waarna de AI de meubels naadloos in de scène verwerkt. De werkstroom is asynchroon en bestaat uit twee stappen:
- Een taak aanmaken — Dien je kamerafbeelding en meubellijst in en ontvang een
taskId. - Resultaten regelmatig opvragen — Gebruik de
taskIdom de taakstatus op te vragen en de gegenereerde afbeelding op te halen.
📌 Opmerking: Momenteel wordt alleen de modus
creativeondersteund.
🔐 Authenticatie#
Alle API-verzoeken moeten worden geauthenticeerd met een API Key.
Neem je API Key op in de verzoekheader:
| Verzoekheader | Waarde |
|---|---|
APIKEY | your_api_key_here |
⚠️ Houd je API Key geheim. Maak deze niet zichtbaar in clientcode of openbare opslagplaatsen.
💰 Creditafschrijving#
[!WARNING] 🪙 Credits worden op basis van de geselecteerde
modelTypeafgeschreven zodra de taak succesvol is aangemaakt. Als de taak uiteindelijk mislukt, worden de afgeschreven credits automatisch terugbetaald op je account.
Onvoldoende credits leveren foutcode9051op. 📄 Zie de referentie voor creditafschrijving.
Modeltype (modelType) | Afgeschreven credits |
|---|---|
Base | 3 tegoedeenheden |
Pro | 10 tegoedeenheden |
📌 API-endpoints#
1. Een taak voor virtuele meubelplaatsing aanmaken#
Maakt een nieuwe AI-taak voor virtuele meubelplaatsing aan en retourneert een unieke taskId om de status regelmatig op te vragen.
Eindpunt
POST /api/v1/furnitureTryOn/generate
Verzoekheaders
| Verzoekheader | Verplicht | Beschrijving |
|---|---|---|
APIKEY | ✅ Ja | Je API-authenticatiesleutel |
Content-Type | ✅ Ja | application/json |
Verzoekinhoud
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
imageUrl | string | ✅ Ja | URL van de kamerscène waarin meubels worden geplaatst |
furnitureList | array | ✅ Ja | Lijst van meubels die in de scène worden geplaatst. Maximaal 6 items. Zie meubelobject |
prompt | string | ❌ Optioneel | Eigen tekstinstructie om plaatsing en stijl verder te sturen |
modelType | string | ❌ Optioneel | Modelkwaliteitsniveau. Mogelijke waarden: Base, Pro. Standaard Base |
🛋️ Meubelobject#
Elk item in furnitureList moet een object zijn met de volgende velden:
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
imageUrl | string | ✅ Ja | URL van de meubelproductafbeelding; een transparante of egale achtergrond wordt aanbevolen |
⚠️
furnitureListmag maximaal 6 items bevatten.
🖼️ Afbeeldingsvereisten: De kamerafbeelding en elke meubelafbeelding 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.
Voorbeeld
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/table.png"
}
]
Modeltypen
| Waarde | Beschrijving |
|---|---|
Base | Standaard. Evenwicht tussen snelheid en kwaliteit |
Pro | Uitvoer van hogere kwaliteit, tragere verwerking |
📥 Verzoekvoorbeelden#
cURL
# Basic request (Base model)
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/living-room.jpg",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/coffee-table.png"
}
],
"prompt": "modern minimalist style"
}'
# Pro model
curl -X POST "https://api.ideal.house/api/v1/furnitureTryOn/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/living-room.jpg",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
}
],
"prompt": "Scandinavian interior with warm lighting",
"modelType": "Pro"
}'
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class FurnitureTryOnApiExample {
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",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/coffee-table.png"
}
],
"prompt": "modern minimalist style",
"modelType": "Base"
}
""";
Request request = new Request.Builder()
.url(BASE_URL + "/api/v1/furnitureTryOn/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)
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",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/coffee-table.png"
}
],
"prompt": "modern minimalist style",
"modelType": "Base"
}
# Pro model example:
# payload = {
# "imageUrl": "https://example.com/living-room.jpg",
# "furnitureList": [
# {
# "imageUrl": "https://example.com/sofa.png"
# }
# ],
# "prompt": "Scandinavian interior with warm lighting",
# "modelType": "Pro"
# }
response = requests.post(
f"{BASE_URL}/api/v1/furnitureTryOn/generate",
headers=headers,
json=payload
)
data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")
Node.js (axios)
const axios = require('axios');
const BASE_URL = 'https://api.ideal.house';
const API_KEY = 'your_api_key_here';
async function createFurnitureTryOnTask() {
try {
const response = await axios.post(
`${BASE_URL}/api/v1/furnitureTryOn/generate`,
{
imageUrl: 'https://example.com/living-room.jpg',
furnitureList: [
{
imageUrl: 'https://example.com/sofa.png'
},
{
imageUrl: 'https://example.com/coffee-table.png'
}
],
prompt: 'modern minimalist style',
modelType: 'Base'
// Pro model:
// modelType: 'Pro'
},
{
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);
}
}
createFurnitureTryOnTask();
📤 Antwoord#
Succesantwoord
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
| Veld | Type | Beschrijving |
|---|---|---|
code | integer | 0 geeft succes aan |
message | string | Antwoordbericht |
data | long | De unieke taak-ID voor het regelmatig opvragen van resultaten |
2. Taakresultaat ophalen#
Haalt de huidige status en uitvoer van een eerder aangemaakte taak voor virtuele meubelplaatsing op.
Eindpunt
GET /api/v1/furnitureTryOn/result
Verzoekheaders
| Verzoekheader | Verplicht | Beschrijving |
|---|---|---|
APIKEY | ✅ Ja | Je API-authenticatiesleutel |
Queryparameters
| Queryparameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
taskId | long | ✅ Ja | De taak-ID die het endpoint voor het aanmaken van taken retourneert |
📥 Verzoekvoorbeelden#
cURL
curl -X GET "https://api.ideal.house/api/v1/furnitureTryOn/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class FurnitureTryOnResultExample {
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/furnitureTryOn/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)
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/furnitureTryOn/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":
output = result["output"]
print("Result URL:", output["resultUrl"])
print("Matched Items:", output.get("items", []))
else:
print("Task ended with status:", status)
Node.js (axios)
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/furnitureTryOn/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('Matched Items:', result.output.items);
} 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
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Success",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/living-room.jpg",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
},
{
"imageUrl": "https://example.com/coffee-table.png"
}
],
"prompt": "modern minimalist style",
"modelType": "Base"
},
"output": {
"resultUrl": "https://cdn.ideal.house/output/furniture_try_on_result.jpg",
"width": 1024,
"height": 1024
}
}
}
Antwoord: taak in verwerking of in de wachtrij
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Processing",
"waitNumber": 1,
"percentage": 45,
"input": {
"imageUrl": "https://example.com/living-room.jpg",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
}
],
"prompt": "modern minimalist style",
"modelType": "Base"
},
"output": null
}
}
Antwoord: taak mislukt
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 0,
"input": {
"imageUrl": "https://example.com/living-room.jpg",
"furnitureList": [
{
"imageUrl": "https://example.com/sofa.png"
}
],
"modelType": "Base"
},
"output": null
}
}
Antwoordvelden
| Veld | Type | Beschrijving |
|---|---|---|
id | long | Unieke taakidentificatie |
status | string | Huidige taakstatus; zie taakstatus |
waitNumber | integer | Aantal taken vóór deze taak in de wachtrij; 0 betekent dat de taak wordt verwerkt |
percentage | integer | Voltooiingspercentage van de taak (0–100) |
input | object | De oorspronkelijke invoerparameters van de taak |
input.imageUrl | string | URL van de kamerscène |
input.furnitureList | array | Lijst van ingediende meubels, maximaal 6 items |
input.furnitureList[].imageUrl | string | URL van de meubelproductafbeelding |
input.prompt | string | Eigen tekstinstructie, indien opgegeven |
input.modelType | string | Gebruikt modeltype |
output | object | Generatieresultaat, alleen beschikbaar wanneer status gelijk is aan Success |
output.resultUrl | string | URL van de gegenereerde kamerafbeelding met geplaatste meubels |
output.width | integer | Uitvoerbreedte in pixels |
output.height | integer | Uitvoerhoogte in pixels |
📊 Taakstatus#
| Status | Beschrijving |
|---|---|
Unprocessed | De taak is aangemaakt, maar nog niet gestart |
Processing | De taak wordt momenteel verwerkt |
Success | De taak is succesvol voltooid; uitvoer is beschikbaar |
Failed | De 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:
{
"code": 5002,
"message": "Invalid API Key",
"data": null
}
Foutcodereferentie#
| Code | Naam | Beschrijving | Aanbevolen actie |
|---|---|---|---|
1001 | FAILED | Verzoek mislukt: algemene fout | Controleer het veld message voor specifieke foutdetails |
1003 | INTERNAL_ERROR | Interne serverfout | Probeer het na een korte wachttijd opnieuw; neem contact op met ondersteuning als de fout blijft optreden |
1011 | PARAM_ERROR | Fout in verzoekparameters — e.g., imageUrl of furnitureList ontbreekt, of furnitureList bevat meer dan 6 items | Geef zowel imageUrl als furnitureList op; ze mogen niet leeg zijn en niet meer dan 6 items bevatten |
5002 | API_KEY_INVALID | Ongeldige of ontbrekende API Key | Controleer dat de header APIKEY aanwezig is en de waarde klopt |
9010 | SCAN_TEXT_ERROR | Tekstinstructie afgekeurd bij inhoudscontrole | Pas de instructie aan om gevoelige of verboden inhoud te verwijderen |
9038 | PROHIBITED_CONTENT | De gegenereerde uitvoerafbeelding bevat verboden inhoud | Pas instructie, stijl of invoer aan en probeer opnieuw |
9051 | COINS_NOT_ENOUGH | Onvoldoende munten / credits | Vul je accountcredits aan en probeer opnieuw |
📄 Raadpleeg de foutcodereferentie voor de volledige lijst van algemene API-foutcodes.