Ideal House
Passa al contenuto

Documentazione API di sostituzione dei mobili#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-05-21


📖 Panoramica#

API di sostituzione dei mobili cambia lo stile o sostituisce i mobili in un'immagine di interni. Invia un'immagine originale e indicazioni di stile facoltative, quindi interroga periodicamente il risultato dell'attività in modo asincrono.

  1. Crea un'attività — Invia imageUrl e le indicazioni facoltative, quindi ricevi un taskId.
  2. Interroga periodicamente i risultati — Usa taskId per interrogare lo stato dell'attività e l'immagine risultante.

🔐 Autenticazione#

Tutte le richieste API devono includere una chiave API nell'intestazione della richiesta.

IntestazioneValore
APIKEYyour_api_key_here

💰 Detrazione dei crediti#

[!WARNING] 🪙 1 credito viene detratto quando un'attività viene creata correttamente. Se alla fine l'attività non riesce, il credito detratto viene rimborsato automaticamente.
Un saldo di crediti insufficiente restituisce il codice di errore 9051. Consulta il Riferimento delle detrazioni dei crediti.

OperazioneCrediti detratti
Attività di sostituzione dei mobili1 credito

🎨 Opzioni di stile#

Questa API supporta parametri di stile facoltativi restituiti dall'endpoint Configurazione degli stili API.

Usa:

Testo semplice
GET /api/v1/style/change_furniture/getStyles
Gruppo di stileCampo della richiestaDescrizione
roomTypeindoorTypeIdOpzione del tipo di stanza
styleindoorStyleIdOpzione dello stile degli interni
elementsindoorElemIdOpzione degli elementi della stanza. Supporta più identificatori di opzione uniti da virgole, ad esempio id1,id2

Ogni opzione contiene:

CampoDescrizione
nameNome multilingue dell'opzione
idValore da passare nel campo della richiesta
urlImmagine di anteprima dell'opzione

📌 Endpoint API#

1. Crea un'attività di sostituzione dei mobili#

Endpoint

Testo semplice
POST /api/v1/changeFurniture/generate

Intestazioni della richiesta

IntestazioneObbligatoriaDescrizione
APIKEY✅ SìLa tua chiave di autenticazione API
Content-Type✅ Sìapplication/json

Corpo della richiesta

CampoTipoObbligatorioDescrizione
imageUrlstring✅ SìURL dell'immagine di interni originale
promptstring❌ FacoltativoIndicazioni testuali per il risultato desiderato
indoorTypeIdstring❌ FacoltativoIdentificatore del tipo di stanza dalle opzioni di stile roomType
indoorStyleIdstring❌ FacoltativoIdentificatore dello stile degli interni dalle opzioni di stile style
indoorElemIdstring❌ FacoltativoIdentificatore degli elementi della stanza dalle opzioni di stile elements. Supporta più identificatori uniti da virgole, ad esempio id1,id2

Soltanto imageUrl è obbligatorio. Tutti gli altri campi sono facoltativi.

🖼️ Requisiti delle immagini: usa JPG/JPEG, PNG o WebP. Ogni immagine non deve superare 20 MB, con dimensioni da 128 × 128 px fino a 6,000 × 6,000 px (estremi inclusi). Prima dell'elaborazione, le immagini che superano le dimensioni massime in pixel vengono ridotte automaticamente in modo proporzionale per rientrare in 6,000 × 6,000 px. La URL dell'immagine deve essere direttamente accessibile dal server API.

📥 Esempi di richiesta#

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();

📤 Risposta#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
CampoTipoDescrizione
codeinteger0 indica il successo
messagestringMessaggio della risposta
datalongIdentificatore dell'attività per interrogare periodicamente i risultati

2. Ottieni il risultato dell'attività#

Endpoint

Testo semplice
GET /api/v1/changeFurniture/result

Intestazioni della richiesta

IntestazioneObbligatoriaDescrizione
APIKEY✅ SìLa tua chiave di autenticazione API

Parametri di interrogazione

ParametroTipoObbligatorioDescrizione
taskIdlong✅ SìIdentificatore dell'attività restituito dall'endpoint di creazione

📥 Esempi di richiesta#

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);

📤 Esempio di risposta#

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
    }
  }
}

Risposta (attività in elaborazione / in coda)

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
  }
}

Risposta (attività non riuscita)

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

📊 Stato dell'attività#

StatoDescrizione
UnprocessedL'attività è stata creata ed è in attesa in coda
ProcessingL'attività è attualmente in esecuzione
SuccessL'attività è stata completata correttamente
FailedL'attività non è riuscita e non è stato prodotto alcun output

Interroga lo stato ogni 3-5 secondi. Consulta i Limiti delle attività API.


❌ Risposte di errore#

CodiceNomeDescrizione
1011PARAM_ERRORErrore nei parametri della richiesta
5002API_KEY_INVALIDChiave API non valida o mancante
9010SCAN_TEXT_ERRORIl prompt non ha superato la verifica dei contenuti
9038PROHIBITED_CONTENTL'immagine generata contiene contenuti vietati
9051COINS_NOT_ENOUGHCrediti insufficienti

Per le definizioni complete degli errori comuni, consulta il Riferimento dei codici di errore.