Ideal House
Aller au contenu principal

Documentation de l'API de changement de mobilier#

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


📖 Vue d'ensemble#

L'API de changement de mobilier restyle ou modifie le mobilier dans une image d'intérieur. Soumettez une image source et des consignes de style optionnelles, puis interrogez le résultat de la tâche de manière asynchrone.

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

🔐 Authentification#

Toutes les requêtes API doivent inclure une clé API dans l'en-tête de la requête.

En-têteValeur
APIKEYyour_api_key_here

💰 Déduction de crédits#

[!WARNING] 🪙 1 crédit est déduit lorsqu'une tâche est créée avec succès. Si la tâche échoue finalement, le crédit déduit sera automatiquement remboursé.
Un solde insuffisant renvoie le code d'erreur 9051. Voir Référence de déduction de crédits.

OpérationCrédits déduits
Tâche de changement de mobilier1 crédit

🎨 Options de style#

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

Utilisation :

Texte brut
GET /api/v1/style/change_furniture/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 IDs d'options joints par une virgule, par exemple id1,id2

Chaque option contient :

ChampDescription
nameNom multilingue de l'option
idValeur à transmettre dans le champ de la requête
urlImage d'aperçu de l'option

📌 Points de terminaison de l'API#

1. Créer une tâche de changement de mobilier#

Point de terminaison

Texte brut
POST /api/v1/changeFurniture/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 intérieure source
promptstring❌ OptionnelInstructions textuelles pour le résultat souhaité
indoorTypeIdstring❌ OptionnelID de type de pièce depuis les options de style roomType
indoorStyleIdstring❌ OptionnelID de style intérieur depuis les options de style style
indoorElemIdstring❌ OptionnelID d'élément de pièce depuis les options de style elements. Prend en charge plusieurs IDs joints par une virgule, par exemple id1,id2

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

🖼️ Exigences relatives aux images : Utilisez 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. L'URL de l'image doit être directement accessible par le serveur API.

📥 Exemples de requête#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/changeFurniture/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "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 ChangeFurnitureApiExample {

    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/living-room.jpg",
                    "prompt": "replace the sofa with a modern warm neutral sofa",
                    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
                    "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/changeFurniture/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/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/changeFurniture/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 createChangeFurnitureTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/changeFurniture/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        prompt: 'replace the sofa with a modern warm neutral sofa',
        indoorTypeId: 'Interior Design_Interior Scene_Living Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Modern Country',
        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);
  }
}

createChangeFurnitureTask();

📤 Réponse#

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

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

Point de terminaison

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

import java.io.IOException;

public class ChangeFurnitureResultExample {

    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/changeFurniture/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/changeFurniture/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 pollChangeFurnitureResult(taskId) {
  const headers = { APIKEY: API_KEY };

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

pollChangeFurnitureResult(1234567890123456789n);

📤 Exemple de réponse#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/change_furniture_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Réponse (Traitement de la tâche / En file d'attente)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa"
    },
    "output": null
  }
}

Réponse (Échec de la tâche)

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

📊 Statut de la tâche#

StatutDescription
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 est 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_ERRORÉchec de l'examen de contenu du prompt
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, voir Référence des codes d'erreur.