Documentatie voor de API voor planvisualisatie#
Basis-URL:
https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-05-21
📖 Overzicht#
De API voor planvisualisatie zet een planafbeelding om in een AI-visualisatie. Deze ondersteunt optionele tekstinstructies, plantype, visuele stijl, weergaveopties en modelmodi.
De werkstroom is asynchroon:
- Een taak aanmaken — Dien
imageUrlen optionele parameters in en ontvang eentaskId. - Resultaten regelmatig opvragen — Gebruik
taskIdom de taakstatus en de gegenereerde afbeelding op te halen.
🔐 Authenticatie#
| Verzoekheader | Waarde |
|---|---|
APIKEY | your_api_key_here |
💰 Creditafschrijving#
[!WARNING] Credits worden afgeschreven wanneer een taak succesvol wordt aangemaakt. Als de taak uiteindelijk mislukt, worden de afgeschreven credits automatisch terugbetaald.
Onvoldoende credits leveren foutcode9051op. Zie de referentie voor creditafschrijving.
Modeltype (modelType) | Afgeschreven credits |
|---|---|
Base | 3 tegoedeenheden |
Pro | 10 tegoedeenheden |
Als modelType niet wordt opgegeven, wordt standaard Base gebruikt.
🎨 Stijlopties#
Deze API ondersteunt optionele stijlparameters die het endpoint voor API-stijlconfiguratie retourneert.
Gebruik:
GET /api/v1/style/ai_plan_visualizer/getStyles
| Stijlgroep | Verzoekveld | Beschrijving |
|---|---|---|
planType | planStyleId | Optie voor plantype |
style | styleId | Optie voor visualisatiestijl |
view | viewId | Optie voor camera of weergave |
Elke optie bevat name, id en url. Geef de id van de optie door in het bijbehorende verzoekveld.
📌 API-endpoints#
1. Een taak voor planvisualisatie aanmaken#
Eindpunt
POST /api/v1/planVisualizer/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 planafbeelding |
prompt | string | ❌ Optioneel | Tekstinstructie voor de gewenste visualisatie |
planStyleId | string | ❌ Optioneel | Plantype-ID uit de stijlopties planType |
styleId | string | ❌ Optioneel | Visualisatiestijl-ID uit de stijlopties style |
viewId | string | ❌ Optioneel | Weergave-ID uit de stijlopties view |
modelType | string | ❌ Optioneel | Mogelijke waarden: Base, Pro. Standaard Base |
Alleen
imageUrlis verplicht. Alle andere velden 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.
📥 Verzoekvoorbeelden#
cURL
curl -X POST "https://api.ideal.house/api/v1/planVisualizer/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/floor-plan.jpg",
"prompt": "bright modern residential visualization",
"planStyleId": "AI plan visualizer_Plan type_Master plan",
"styleId": "AI plan visualizer_Style_Marker pen",
"viewId": "AI plan visualizer_View_Top-Down View",
"modelType": "Base"
}'
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class PlanVisualizerApiExample {
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/floor-plan.jpg",
"prompt": "bright modern residential visualization",
"planStyleId": "AI plan visualizer_Plan type_Master plan",
"styleId": "AI plan visualizer_Style_Marker pen",
"viewId": "AI plan visualizer_View_Top-Down View",
"modelType": "Base"
}
""";
Request request = new Request.Builder()
.url(BASE_URL + "/api/v1/planVisualizer/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/floor-plan.jpg",
"prompt": "bright modern residential visualization",
"planStyleId": "AI plan visualizer_Plan type_Master plan",
"styleId": "AI plan visualizer_Style_Marker pen",
"viewId": "AI plan visualizer_View_Top-Down View",
"modelType": "Base"
}
response = requests.post(
f"{BASE_URL}/api/v1/planVisualizer/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 createPlanVisualizerTask() {
try {
const response = await axios.post(
`${BASE_URL}/api/v1/planVisualizer/generate`,
{
imageUrl: 'https://example.com/floor-plan.jpg',
prompt: 'bright modern residential visualization',
planStyleId: 'AI plan visualizer_Plan type_Master plan',
styleId: 'AI plan visualizer_Style_Marker pen',
viewId: 'AI plan visualizer_View_Top-Down View',
modelType: 'Base'
},
{
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);
}
}
createPlanVisualizerTask();
📤 Antwoord#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Taakresultaat ophalen#
Eindpunt
GET /api/v1/planVisualizer/result
Verzoekheaders
| Verzoekheader | Verplicht | Beschrijving |
|---|---|---|
APIKEY | ✅ Ja | Je API-authenticatiesleutel |
Queryparameters
| Queryparameter | Type | Verplicht | Beschrijving |
|---|---|---|---|
taskId | long | ✅ Ja | Taak-ID die het aanmaakendpoint retourneert |
📥 Verzoekvoorbeelden#
cURL
curl -X GET "https://api.ideal.house/api/v1/planVisualizer/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class PlanVisualizerResultExample {
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/planVisualizer/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/planVisualizer/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)
const axios = require('axios');
const BASE_URL = 'https://api.ideal.house';
const API_KEY = 'your_api_key_here';
async function pollPlanVisualizerResult(taskId) {
const headers = { APIKEY: API_KEY };
while (true) {
const response = await axios.get(
`${BASE_URL}/api/v1/planVisualizer/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));
}
}
pollPlanVisualizerResult(1234567890123456789n);
📤 Antwoordvoorbeeld#
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Success",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/floor-plan.jpg",
"prompt": "bright modern residential visualization",
"planStyleId": "AI plan visualizer_Plan type_Master plan",
"styleId": "AI plan visualizer_Style_Marker pen",
"viewId": "AI plan visualizer_View_Top-Down View",
"modelType": "Base"
},
"output": {
"resultUrl": "https://cdn.ideal.house/output/plan_visualizer_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/floor-plan.jpg",
"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/floor-plan.jpg",
"modelType": "Base"
},
"output": null
}
}
📊 Taakstatus#
| Status | Beschrijving |
|---|---|
Unprocessed | De taak is aangemaakt en wacht in de wachtrij |
Processing | De taak wordt momenteel uitgevoerd |
Success | De taak is succesvol voltooid |
Failed | De taak is mislukt en er is geen uitvoer geproduceerd |
Vraag de status elke 3-5 seconden op. Zie de taaklimiet voor de API.
❌ Foutantwoorden#
| Code | Naam | Beschrijving |
|---|---|---|
1011 | PARAM_ERROR | Fout in verzoekparameters |
5002 | API_KEY_INVALID | Ongeldige of ontbrekende API-sleutel |
9010 | SCAN_TEXT_ERROR | Tekstinstructie afgekeurd bij inhoudscontrole |
9038 | PROHIBITED_CONTENT | De gegenereerde afbeelding bevat verboden inhoud |
9051 | COINS_NOT_ENOUGH | Onvoldoende tegoed |
Zie de foutcodereferentie voor de volledige definities van algemene fouten.