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 :
- Créer une tâche — Soumettez
imageUrlet des paramètres optionnels, 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 retournera le code d'erreur9051. Consultez Référence de déduction des crédits.
Modèle (modelType) | Crédits déduits |
|---|---|
Base | 3 crédits |
Pro | 10 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 :
GET /api/v1/style/ai_plan_visualizer/getStyles
| Groupe de style | Champ de la requête | Description |
|---|---|---|
planType | planStyleId | Option de type de plan |
style | styleId | Option de style de visualisation |
view | viewId | Option 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
POST /api/v1/planVisualizer/generate
En-têtes de la requête
| En-tête | Requis | Description |
|---|---|---|
APIKEY | ✅ Oui | Votre clé d'authentification API |
Content-Type | ✅ Oui | application/json |
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
imageUrl | string | ✅ Requis | URL de l'image source du plan |
prompt | string | ❌ Optionnel | Directive textuelle pour la visualisation souhaitée |
planStyleId | string | ❌ Optionnel | ID de type de plan depuis les options planType |
styleId | string | ❌ Optionnel | ID de style de visualisation depuis les options style |
viewId | string | ❌ Optionnel | ID de vue depuis les options view |
modelType | string | ❌ Facultatif | Enum : Base, Pro. Par défaut : Base |
Seul
imageUrlest 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
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();
📤 Réponse#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Obtenir le résultat de la tâche#
Point de terminaison
GET /api/v1/planVisualizer/result
En-têtes de la requête
| En-tête | Requis | Description |
|---|---|---|
APIKEY | ✅ Oui | Votre clé d'authentification API |
Paramètres de requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
taskId | long | ✅ Oui | ID de tâche retourné par le point de terminaison de création |
📥 Exemples de requête#
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);
📤 Exemple de réponse#
{
"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)
{
"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)
{
"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#
| É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 | La tâche a été terminée avec succès |
Failed | La 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#
| 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é au contrôle de contenu |
9038 | PROHIBITED_CONTENT | L'image générée contient du contenu interdit |
9051 | COINS_NOT_ENOUGH | Crédits insuffisants |
Pour les définitions complètes des erreurs courantes, consultez Référence des codes d'erreur.