Documentatie voor de API voor buitenrenovatie#
Basis-URL:
https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-05-20
📖 Overzicht#
Met de API voor buitenrenovatie kun je de buitenkant van een gebouw renoveren of opnieuw vormgeven op basis van een invoerafbeelding. Je levert een bronafbeelding en kunt optioneel tekstinstructies, een referentiebeeld, bouwstijl of omgevingsvoorkeur toevoegen om het renovatieresultaat te sturen.
De werkstroom is asynchroon en bestaat uit twee stappen:
- Een taak aanmaken — Dien je buitenafbeelding en optionele aanwijzingen in en ontvang een
taskId. - Resultaten regelmatig opvragen — Gebruik de
taskIdom de taakstatus op te vragen en de gegenereerde afbeelding op te halen.
🔐 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] 🪙 Bij het succesvol aanmaken van een taak wordt 1 tegoedeenheid afgeschreven. Als de taak uiteindelijk mislukt, wordt de afgeschreven credit automatisch terugbetaald op je account.
Onvoldoende credits leveren foutcode9051op. 📄 Zie de referentie voor creditafschrijving.
| Bewerking | Afgeschreven credits |
|---|---|
| Taak voor buitenrenovatie | 1 tegoedeenheid |
Zie de referentie voor creditafschrijving voor gedetailleerde creditregels.
📌 API-endpoints#
1. Een taak voor buitenrenovatie aanmaken#
Maakt een nieuwe taak voor buitenrenovatie aan en retourneert een unieke taskId om de status regelmatig op te vragen.
Eindpunt
POST /api/v1/exteriorRenovator/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 oorspronkelijke buitenafbeelding die wordt gerenoveerd |
prompt | string | ❌ Optioneel | Optionele tekstinstructie voor het renovatieresultaat |
referenceUrl | string | ❌ Optioneel | Optionele URL van een referentiebeeld om de visuele stijl te sturen |
buildingStyleId | string | ❌ Optioneel | Optionele bouwstijl-ID |
environmentId | string | ❌ Optioneel | Optionele omgevings- of scènestijl-ID. Ondersteunt meerdere ID's gescheiden door komma's, bijvoorbeeld id1,id2 |
⚠️ Alleen
imageUrlis verplicht. Alle andere velden in de verzoekinhoud zijn optioneel.
🖼️ Afbeeldingsvereisten: Alle bron- en referentieafbeeldingen 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.
🎨 Stijlopties#
buildingStyleId en environmentId kunnen worden gekozen via het endpoint voor API-stijlconfiguratie.
Gebruik:
GET /api/v1/style/exterior_renovator/getStyles
| Stijlgroep | Verzoekveld | Beschrijving |
|---|---|---|
buildingStyle | buildingStyleId | Optie voor bouwstijl |
environment | environmentId | Optie voor omgeving of scène. Ondersteunt meerdere optie-ID's gescheiden door komma's, bijvoorbeeld id1,id2 |
Elke optie bevat name, id en url. Geef de id van de optie door in het bijbehorende verzoekveld.
📥 Verzoekvoorbeelden#
cURL
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/exterior.jpg"
}'
# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/exterior.jpg",
"prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
"referenceUrl": "https://example.com/reference-house.jpg",
"buildingStyleId": "modern-farmhouse",
"environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}'
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class ExteriorRenovatorApiExample {
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/exterior.jpg",
"prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
"referenceUrl": "https://example.com/reference-house.jpg",
"buildingStyleId": "modern-farmhouse",
"environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}
""";
Request request = new Request.Builder()
.url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
"prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
"referenceUrl": "https://example.com/reference-house.jpg",
"buildingStyleId": "modern-farmhouse",
"environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}
response = requests.post(
f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
try {
const response = await axios.post(
`${BASE_URL}/api/v1/exteriorRenovator/generate`,
{
imageUrl: 'https://example.com/exterior.jpg',
prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
referenceUrl: 'https://example.com/reference-house.jpg',
buildingStyleId: 'modern-farmhouse',
environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
},
{
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);
}
}
createExteriorRenovatorTask();
📤 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 buitenrenovatie op.
Eindpunt
GET /api/v1/exteriorRenovator/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/exteriorRenovator/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class ExteriorRenovatorResultExample {
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/exteriorRenovator/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
while True:
response = requests.get(
f"{BASE_URL}/api/v1/exteriorRenovator/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 failed")
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/exteriorRenovator/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 failed');
}
break;
}
await new Promise(resolve => setTimeout(resolve, 3000));
}
}
pollResult(1234567890123456789);
📤 Antwoord#
Succesantwoord: taak voltooid
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Success",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/exterior.jpg",
"prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
"refImageUrl": "https://example.com/reference-house.jpg",
"buildingStyleId": "modern-farmhouse",
"environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
},
"output": {
"resultUrl": "https://cdn.ideal.house/output/exterior_renovator_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": 50,
"input": {
"imageUrl": "https://example.com/exterior.jpg"
},
"output": null
}
}
Antwoord: taak mislukt
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 0,
"input": {
"imageUrl": "https://example.com/exterior.jpg"
},
"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 oorspronkelijke buitenafbeelding |
input.prompt | string | Optionele tekstinstructie, indien opgegeven |
input.refImageUrl | string | Optionele URL van het referentiebeeld, indien opgegeven |
input.buildingStyleId | string | Optionele bouwstijl-ID, indien opgegeven |
input.environmentId | string | Optionele omgevings- of scènestijl-ID, indien opgegeven. Kan meerdere ID's gescheiden door komma's bevatten |
output | object | Generatieresultaat, alleen beschikbaar wanneer status gelijk is aan Success |
output.resultUrl | string | URL van de resultaatafbeelding van de buitenrenovatie |
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 | Zorg dat verzoekparameters correct zijn opgemaakt |
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. Zie de referentie voor creditafschrijving |
📄 Raadpleeg de foutcodereferentie voor de volledige lijst van algemene API-foutcodes.