Ideal House
Aller au contenu principal

Documentation de l'API de visualisation de plans#

URL de base : https://api.ideal.house
Version : v1
Mis à jour le : 2026-05-21


📖 Vue d'ensemble#

L'API de visualisation de plans transforme une image de plan en une visualisation IA. Elle prend en charge les directives textuelles optionnelles, le type de plan, le style visuel, les options de vue et les modes de modèle.

Le flux de travail est asynchrone :

  1. Créer une tâche — Soumettez imageUrl et des paramètres optionnels, 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 retournera le code d'erreur 9051. Consultez Référence de déduction des crédits.

Modèle (modelType)Crédits déduits
Base3 crédits
Pro10 crédits

Si modelType n'est pas fourni, Base est utilisé par défaut.


🎨 Options de style#

Cet API prend en charge des paramètres de style optionnels renvoyés par le point de terminaison Configuration de style API.

Utilisation :

Texte brut
GET /api/v1/style/ai_plan_visualizer/getStyles
Groupe de styleChamp de la requêteDescription
planTypeplanStyleIdOption de type de plan
stylestyleIdOption de style de visualisation
viewviewIdOption de caméra/vue

Chaque option contient name, id et url. Transmettez l'id de l'option dans le champ de requête correspondant.


📌 Points de terminaison de l'API#

1. Créer une tâche de visualisation de plans#

Point de terminaison

Texte brut
POST /api/v1/planVisualizer/generate

En-têtes de la requête

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

Corps de la requête

ChampTypeRequisDescription
imageUrlstring✅ RequisURL de l'image source du plan
promptstring❌ OptionnelDirective textuelle pour la visualisation souhaitée
planStyleIdstring❌ OptionnelID de type de plan depuis les options planType
styleIdstring❌ OptionnelID de style de visualisation depuis les options style
viewIdstring❌ OptionnelID de vue depuis les options view
modelTypestring❌ FacultatifEnum : Base, Pro. Par défaut : Base

Seul imageUrl est obligatoire. Tous les autres champs sont optionnels.

🖼️ Exigences relatives aux images : Toutes les images source 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 dépassant les dimensions maximales en pixels sont automatiquement réduites à la taille proportionnellement pour respecter les 6,000 × 6,000 px avant traitement. Les URL d'image URLs doivent être directement accessibles par le serveur API.

📥 Exemples de requête#

cURL
bash
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)
java
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)
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/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)
javascript
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();

📤 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/planVisualizer/result

En-têtes de la requête

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

Paramètres de requête

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

📥 Exemples de requête#

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

📤 Exemple de réponse#

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

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/floor-plan.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/floor-plan.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
SuccessLa tâche a été terminée avec succès
FailedLa tâche a échoué et aucune sortie n'a été produite

Effectuez une interrogation périodique toutes les 3-5 secondes. Consultez Limite de tâches 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é au contrôle de contenu
9038PROHIBITED_CONTENTL'image générée contient du contenu interdit
9051COINS_NOT_ENOUGHCrédits insuffisants

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