Ideal House
Aller au contenu principal

Documentation de l'API de décoration intérieure#

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


📖 Vue d'ensemble#

L'API de décoration intérieure génère des idées de décoration pour une image d'intérieur. Elle prend en charge un accompagnement textuel optionnel, une image de référence, des sélections de style et des 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#

Cette API prend en charge les paramètres de style facultatifs renvoyés par le point de terminaison Configuration des styles de l'API.

Utilisation :

Texte brut
GET /api/v1/style/home_decor_ideas/getStyles
Groupe de styleChamp de la requêteDescription
spaceTypespaceStyleIdOption de type d'espace ou de pièce
decorStylehomeDecorStyleIdOption de style de décoration

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 décoration intérieure#

Point de terminaison

Texte brut
POST /api/v1/homeDecor/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 l'intérieur
referenceUrlstring❌ FacultatifURL de l'image de référence pour guider le style de décoration
spaceStyleIdstring❌ FacultatifID de type d'espace depuis les options de style spaceType
homeDecorStyleIdstring❌ FacultatifID de style de décoration depuis les options de style decorStyle
promptstring❌ FacultatifAccompagnement textuel pour le résultat souhaité
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 sources et de référence doivent utiliser 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. Les URLs d'image doivent être directement accessibles par le serveur API.

📥 Exemples de requête#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/homeDecor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class HomeDecorApiExample {

    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/room.jpg",
                    "referenceUrl": "https://example.com/reference.jpg",
                    "spaceStyleId": "Indoor_Living Room",
                    "homeDecorStyleId": "Holidays_Cozy Christmas",
                    "prompt": "warm seasonal decor with natural textures",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/homeDecor/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/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/homeDecor/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 createHomeDecorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/homeDecor/generate`,
      {
        imageUrl: 'https://example.com/room.jpg',
        referenceUrl: 'https://example.com/reference.jpg',
        spaceStyleId: 'Indoor_Living Room',
        homeDecorStyleId: 'Holidays_Cozy Christmas',
        prompt: 'warm seasonal decor with natural textures',
        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);
  }
}

createHomeDecorTask();

📤 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/homeDecor/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/homeDecor/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class HomeDecorResultExample {

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

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

pollHomeDecorResult(1234567890123456789n);

📤 Exemple de réponse#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "refImageUrl": "https://example.com/reference.jpg",
      "spaceStyleId": "Indoor_Living Room",
      "homeDecorStyleId": "Holidays_Cozy Christmas",
      "prompt": "warm seasonal decor with natural textures",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/home_decor_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/room.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/room.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

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


❌ 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.