Ideal House
Aller au contenu principal

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 :

  1. Créer une tâche — Soumettez imageUrl et des paramètres facultatifs, puis recevez un taskId.
  2. Interrogation périodique des résultats — Utilisez taskId pour récupérer l'état de la tâche et l'image générée.

🔐 Authentification#

En-têteValeur
APIKEYyour_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'erreur 9051. Consultez la Référence de déduction des crédits.

Modèle (modelType)Crédits déduits
Flash1 crédit
Base3 crédits
Pro10 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 :

Texte brut
GET /api/v1/style/landscaping/getStyles
Groupe de stylesChamp de la requêteDescription
gardenStylesceneIdOption de style de jardin ou paysager
elementssceneElementIdOption 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

Texte brut
POST /api/v1/landscaping/generate

En-têtes de requête

En-têteObligatoireDescription
APIKEY✅ OuiVotre clé d'authentification API
Content-Type✅ Ouiapplication/json

Corps de la requête

ChampTypeObligatoireDescription
imageUrlstring✅ OuiURL de l'image paysage source
promptstring❌ FacultatifInstructions textuelles pour le résultat souhaité
sceneIdstring❌ FacultatifID de style de jardin issu des options de style gardenStyle
sceneElementIdstring❌ FacultatifID 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
modelTypestring❌ FacultatifEnum : Flash, Base, Pro. Par défaut : Base

Seul imageUrl est 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
bash
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)
java
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)
python
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)
javascript
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#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

2. Obtenir le résultat de la tâche#

Point de terminaison

Texte brut
GET /api/v1/landscaping/result

En-têtes de requête

En-têteObligatoireDescription
APIKEY✅ OuiVotre clé d'authentification API

Paramètres de requête

ParamètreTypeObligatoireDescription
taskIdlong✅ OuiID de tâche renvoyé par le point de terminaison de création

📥 Exemples de requête#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/landscaping/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
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)
python
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)
javascript
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#

json
{
  "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)

json
{
  "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)

json
{
  "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#

ÉtatDescription
UnprocessedLa tâche a été créée et attend dans la file d'attente
ProcessingLa tâche est actuellement en cours d'exécution
SuccessTâche terminée avec succès
FailedLa 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#

CodeNomDescription
1011PARAM_ERRORErreur de paramètre de requête
5002API_KEY_INVALIDClé API invalide ou manquante
9010SCAN_TEXT_ERRORL'invite a échoué à l'examen de contenu
9038PROHIBITED_CONTENTL'image générée contient un contenu interdit
9051COINS_NOT_ENOUGHCrédits insuffisants

Pour les définitions complètes des erreurs courantes, consultez la Référence des codes d'erreur.