Documentation de l'API d'aménagement paysager#
URL de base :
https://api.ideal.house
Version : v1
Mis à jour : 2026-05-21
📖 Aperçu#
L'API de paysagisme améliore ou redessine les espaces paysagers extérieurs à partir d'une image source. Elle prend en charge les instructions textuelles facultatives, les options de style de jardin, les éléments paysagers et les modes de modèle.
Le flux de travail est asynchrone :
- Créer une tâche — Soumettez
imageUrlet des paramètres facultatifs, puis recevez untaskId. - Interrogation périodique des résultats — Utilisez
taskIdpour récupérer l'état de la tâche et l'image générée.
🔐 Authentification#
| En-tête | Valeur |
|---|---|
APIKEY | your_api_key_here |
💰 Déduction de crédits#
[!WARNING] Les crédits sont déduits lorsqu'une tâche est créée avec succès. Si la tâche échoue finalement, les crédits déduits seront automatiquement remboursés.
Un solde insuffisant renverra le code d'erreur9051. Consultez la Référence de déduction des crédits.
Modèle (modelType) | Crédits déduits |
|---|---|
Flash | 1 crédit |
Base | 3 crédits |
Pro | 10 crédits |
Si modelType n'est pas fourni, Base est utilisé par défaut.
🎨 Options de style#
Cette API prend en charge les paramètres de style facultatifs renvoyés par le point de terminaison Config des styles de l'API.
À utiliser :
GET /api/v1/style/landscaping/getStyles
| Groupe de styles | Champ de la requête | Description |
|---|---|---|
gardenStyle | sceneId | Option de style de jardin ou paysager |
elements | sceneElementId | Option d'élément paysager. Prend en charge plusieurs IDs d'option séparés par des virgules, par exemple id1,id2 |
Chaque option contient name, id et url. Transmettez l'id de l'option dans le champ de requête correspondant.
📌 API Points de terminaison#
1. Créer une tâche de paysagisme#
Point de terminaison
POST /api/v1/landscaping/generate
En-têtes de requête
| En-tête | Obligatoire | Description |
|---|---|---|
APIKEY | ✅ Oui | Votre clé d'authentification API |
Content-Type | ✅ Oui | application/json |
Corps de la requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
imageUrl | string | ✅ Oui | URL de l'image paysage source |
prompt | string | ❌ Facultatif | Instructions textuelles pour le résultat souhaité |
sceneId | string | ❌ Facultatif | ID de style de jardin issu des options de style gardenStyle |
sceneElementId | string | ❌ Facultatif | ID d'élément paysager issu des options de style elements. Prend en charge plusieurs IDs séparés par des virgules, par exemple id1,id2 |
modelType | string | ❌ Facultatif | Enum : Flash, Base, Pro. Par défaut : Base |
Seul
imageUrlest obligatoire. Tous les autres champs sont facultatifs.
🖼️ Exigences relatives aux images : Toutes les images sources et de référence doivent être au format JPG/JPEG, PNG ou WebP. Chaque image ne doit pas dépasser 20 Mo, avec des dimensions comprises entre 128 × 128 px et 6,000 × 6,000 px (inclus). Les images dont les dimensions maximales en pixels sont dépassées sont automatiquement redimensionnées proportionnellement pour s'intégrer dans 6,000 × 6,000 px avant le traitement. Les URLs des images doivent être directement accessibles par le serveur API.
📥 Exemples de requête#
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();
📤 Réponse#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Obtenir le résultat de la tâche#
Point de terminaison
GET /api/v1/landscaping/result
En-têtes de requête
| En-tête | Obligatoire | Description |
|---|---|---|
APIKEY | ✅ Oui | Votre clé d'authentification API |
Paramètres de requête
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
taskId | long | ✅ Oui | ID de tâche renvoyé par le point de terminaison de création |
📥 Exemples de requête#
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);
📤 Exemple de réponse#
{
"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
}
}
}
Réponse (tâche en cours de traitement / en file d'attente)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Processing",
"waitNumber": 1,
"percentage": 45,
"input": {
"imageUrl": "https://example.com/backyard.jpg",
"modelType": "Base"
},
"output": null
}
}
Réponse (tâche échouée)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Failed",
"waitNumber": 0,
"percentage": 0,
"input": {
"imageUrl": "https://example.com/backyard.jpg",
"modelType": "Base"
},
"output": null
}
}
📊 État de la tâche#
| État | Description |
|---|---|
Unprocessed | La tâche a été créée et attend dans la file d'attente |
Processing | La tâche est actuellement en cours d'exécution |
Success | Tâche terminée avec succès |
Failed | La tâche a échoué et aucune sortie n'a été produite |
Interrogez toutes les 3-5 secondes. Consultez la Limite de tâches de l'API.
❌ Réponses d'erreur#
| Code | Nom | Description |
|---|---|---|
1011 | PARAM_ERROR | Erreur de paramètre de requête |
5002 | API_KEY_INVALID | Clé API invalide ou manquante |
9010 | SCAN_TEXT_ERROR | L'invite a échoué à l'examen de contenu |
9038 | PROHIBITED_CONTENT | L'image générée contient un contenu interdit |
9051 | COINS_NOT_ENOUGH | Crédits insuffisants |
Pour les définitions complètes des erreurs courantes, consultez la Référence des codes d'erreur.