Ideal House
Aller au contenu principal

Documentation de l'API de mise en scène virtuelle#

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


📖 Vue d'ensemble#

L'API de mise en scène virtuelle vous permet de repenser une pièce vide ou partiellement meublée à l'aide de l'IA.
Vous soumettez une URL d'image de pièce et une invite textuelle facultative, puis récupérez le résultat généré de manière asynchrone.

  1. Créer une tâche — Soumettez imageUrl et prompt optionnel, puis recevez un taskId.
  2. Interrogation périodique des résultats — Utilisez taskId pour interroger l'état de la tâche et obtenir l'image de sortie.

🔐 Authentification#

Toutes les requêtes API doivent être authentifiées à l'aide d'une clé API.

Incluez votre clé API dans l'en-tête de la requête :

En-têteValeur
APIKEYyour_api_key_here

⚠️ Conservez votre clé API en sécurité. Ne l'exposez pas dans du code côté client ou dans des dépôts publics.


💰 Déduction de crédits#

[!WARNING] 🪙 1 crédit est déduit lors de la création réussie d'une tâche.
Si la tâche échoue finalement, le crédit déduit sera automatiquement remboursé.
Un solde insuffisant retournera le code d'erreur 9051. 📄 Consultez Référence de déduction des crédits.

OpérationCrédits déduits
Tâche de mise en scène virtuelle1 crédit

📌 Points de terminaison de l'API#


1. Créer une tâche de mise en scène virtuelle#

Crée une nouvelle tâche d’aménagement virtuel et renvoie un taskId unique pour l'interrogation périodique.

Point de terminaison

Texte brut
POST /api/v1/virtualStaging/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✅ OuiURL de l'image source de la pièce
promptstring❌ NonInvite textuelle optionnelle pour guider le style et le mobilier
indoorTypeIdstring❌ NonPréréglage du type de pièce. Voir Options de type de pièce
indoorStyleIdstring❌ NonPréréglage du style intérieur. Voir Options de style intérieur
indoorElemIdstring❌ NonPréréglage des éléments de la pièce. Prend en charge plusieurs ID joints par une virgule, par exemple id1,id2

🖼️ Exigences relatives aux images : Utilisez JPG/JPEG, PNG ou WebP. Chaque image doit faire au maximum 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 proportionnellement pour tenir dans 6,000 × 6,000 px avant le traitement. L'URL de l'image doit être directement accessible par le serveur API.


🎨 Options de style#

indoorTypeId, indoorStyleId et indoorElemId peuvent être sélectionnés via le point de terminaison Configuration des styles de l'API.

Utilisation :

Texte brut
GET /api/v1/style/virtual_staging/getStyles
Groupe de styleChamp de la requêteDescription
roomTypeindoorTypeIdOption de type de pièce
styleindoorStyleIdOption de style intérieur
elementsindoorElemIdOption d'élément de pièce. Prend en charge plusieurs ID d'options joints par une virgule, par exemple id1,id2

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


📥 Exemples de requête#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/empty-living-room.jpg",
    "prompt": "Warm and modern living room styling",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingApiExample {

    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/empty-bedroom.jpg",
                    "prompt": "Cozy contemporary bedroom",
                    "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
                    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/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/empty-home-office.jpg",
    "prompt": "Minimal modern home office",
    "indoorTypeId": "Interior Design_Interior Scene_Home Office",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/virtualStaging/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 createVirtualStagingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/virtualStaging/generate`,
      {
        imageUrl: 'https://example.com/empty-dining-room.jpg',
        prompt: 'Modern luxury dining room',
        indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
        indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
      },
      {
        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);
  }
}

createVirtualStagingTask();

📤 Réponse#

Réponse de succès

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
ChampTypeDescription
codeinteger0 indique le succès
messagestringMessage de réponse
datalongL'ID de tâche unique pour l'interrogation des résultats

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

Récupère l'état actuel et la sortie d'une tâche de mise en scène virtuelle précédemment créée.

Point de terminaison

Texte brut
GET /api/v1/virtualStaging/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✅ OuiL'ID 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/virtualStaging/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingResultExample {

    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/virtualStaging/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/virtualStaging/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":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Size:", output["width"], "x", output["height"])
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 pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/virtualStaging/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));
  }
}

pollResult(1234567890123456789n);

📤 Réponse#

Réponse de succès (tâche terminée)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "modern country living room with warm neutral materials",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/virtual_staging_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": 46,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "coastal bedroom with soft light and natural textures",
      "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
    },
    "output": null
  }
}

Réponse (tâche échouée)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "..."
    },
    "output": null
  }
}

Champs de la réponse

ChampTypeDescription
idlongIdentifiant unique de la tâche
statusstringÉtat actuel de la tâche (voir État de la tâche)
waitNumberintegerNombre de tâches devant celle-ci dans la file d'attente (0 signifie actuellement en cours de traitement)
percentageintegerPourcentage d'avancement de la tâche (0-100)
errorReasonstringRaison de l'échec lorsque status est Failed
inputobjectParamètres d'entrée originaux soumis pour cette tâche
input.imageUrlstringURL de l'image source de la pièce
input.promptstringInvite utilisateur (le cas échéant)
input.indoorTypeIdstringPréréglage du type de pièce utilisé (le cas échéant)
input.indoorStyleIdstringPréréglage du style intérieur utilisé (le cas échéant)
input.indoorElemIdstringPréréglage des éléments de la pièce utilisé (le cas échéant). Peut contenir plusieurs ID joints par une virgule
outputobjectRésultat de la génération (disponible uniquement lorsque status est Success)
output.resultUrlstringURL de l'image résultat de la mise en scène virtuelle générée
output.widthintegerLargeur de l'image de sortie en pixels
output.heightintegerHauteur de l'image de sortie en pixels

📊 État de la tâche#

ÉtatSignification
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

Interroger périodiquement toutes les 3-5 secondes. Consultez Limite des tâches de l'API.


❌ Réponses d'erreur#

Toutes les réponses d'erreur partagent la même structure JSON :

json
{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Référence des codes d'erreur#

CodeNomDescriptionAction recommandée
1001FAILEDÉchec de la requête (erreur générique)Consultez le champ message pour des détails spécifiques
1003INTERNAL_ERRORErreur interne du serveurRéessayez après un bref délai ; contactez le support si le problème persiste
1011PARAM_ERRORErreur de paramètre de requête (par exemple, imageUrl manquant)Assurez-vous que imageUrl est fourni et constitue une URL valide
5002API_KEY_INVALIDClé API invalide ou manquanteAssurez-vous que l'en-tête APIKEY est présent et correct
9010SCAN_TEXT_ERRORL'invite a échoué à la modération de contenuModifiez l'invite pour retirer le contenu sensible ou interdit
9038PROHIBITED_CONTENTL'image de sortie générée contient du contenu interditAjustez l'invite/le style/les entrées et réessayez
9051COINS_NOT_ENOUGHCrédits insuffisantsApprovisionnez vos crédits et réessayez

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