Documentatie voor de API voor tuinontwerp#
Basis-URL:
https://api.ideal.house
Versie: v1
Bijgewerkt: 2026-05-21
📖 Overzicht#
De API voor tuinontwerp verbetert of herontwerpt buitenruimten op basis van een bronafbeelding. Deze ondersteunt optionele tekstinstructies, tuinstijlen, tuinelementen 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 |
|---|---|
Flash | 1 tegoedeenheid |
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/landscaping/getStyles
| Stijlgroep | Verzoekveld | Beschrijving |
|---|---|---|
gardenStyle | sceneId | Optie voor tuin- of landschapsstijl |
elements | sceneElementId | Optie voor tuinelementen. 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.
📌 API-endpoints#
1. Een taak voor tuinontwerp aanmaken#
Eindpunt
POST /api/v1/landscaping/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 afbeelding van de buitenruimte |
prompt | string | ❌ Optioneel | Tekstinstructie voor het gewenste resultaat |
sceneId | string | ❌ Optioneel | Tuinstijl-ID uit de stijlopties gardenStyle |
sceneElementId | string | ❌ Optioneel | Tuinelement-ID uit de stijlopties elements. Ondersteunt meerdere ID's gescheiden door komma's, bijvoorbeeld id1,id2 |
modelType | string | ❌ Optioneel | Mogelijke waarden: Flash, 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/landscaping/generate" \
-H "APIKEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://example.com/backyard.jpg",
"prompt": "lush modern garden with clean stone paths",
"sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
"sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
"modelType": "Base"
}'
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class LandscapingApiExample {
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/backyard.jpg",
"prompt": "lush modern garden with clean stone paths",
"sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
"sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
"modelType": "Base"
}
""";
Request request = new Request.Builder()
.url(BASE_URL + "/api/v1/landscaping/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/backyard.jpg",
"prompt": "lush modern garden with clean stone paths",
"sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
"sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
"modelType": "Base"
}
response = requests.post(
f"{BASE_URL}/api/v1/landscaping/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 createLandscapingTask() {
try {
const response = await axios.post(
`${BASE_URL}/api/v1/landscaping/generate`,
{
imageUrl: 'https://example.com/backyard.jpg',
prompt: 'lush modern garden with clean stone paths',
sceneId: 'Landscape Design_Landscape Style_Mid-Century Modern Pool',
sceneElementId: 'Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover',
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);
}
}
createLandscapingTask();
📤 Antwoord#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Taakresultaat ophalen#
Eindpunt
GET /api/v1/landscaping/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/landscaping/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
import okhttp3.*;
import java.io.IOException;
public class LandscapingResultExample {
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/landscaping/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/landscaping/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 pollLandscapingResult(taskId) {
const headers = { APIKEY: API_KEY };
while (true) {
const response = await axios.get(
`${BASE_URL}/api/v1/landscaping/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));
}
}
pollLandscapingResult(1234567890123456789n);
📤 Antwoordvoorbeeld#
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Success",
"waitNumber": 0,
"percentage": 100,
"input": {
"imageUrl": "https://example.com/backyard.jpg",
"prompt": "lush modern garden with clean stone paths",
"sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
"sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
"modelType": "Base"
},
"output": {
"resultUrl": "https://cdn.ideal.house/output/landscaping_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/backyard.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/backyard.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.