Ideal House
Passa al contenuto

Documentazione API di allestimento virtuale#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-04-13


📖 Panoramica#

API di allestimento virtuale consente di riprogettare una stanza vuota o parzialmente arredata usando l'intelligenza artificiale.
Invia una URL dell'immagine della stanza e un prompt testuale facoltativo, quindi recupera il risultato generato in modo asincrono.

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

🔐 Autenticazione#

Tutte le richieste API devono essere autenticate con una chiave API.

Includi la chiave API nell'intestazione della richiesta:

IntestazioneValore
APIKEYyour_api_key_here

⚠️ Conserva la chiave API in sicurezza. Non esporla nel codice lato client o in repository pubblici.


💰 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 allestimento virtuale1 credito

📌 Endpoint API#


1. Crea un'attività di allestimento virtuale#

Crea una nuova attività di allestimento virtuale e restituisce un taskId univoco per le interrogazioni periodiche.

Endpoint

Testo semplice
POST /api/v1/virtualStaging/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 originale della stanza
promptstring❌ NoPrompt facoltativo per orientare lo stile e l'arredamento
indoorTypeIdstring❌ NoPreimpostazione facoltativa del tipo di stanza. Vedi Opzioni del tipo di ambiente interno
indoorStyleIdstring❌ NoPreimpostazione facoltativa dello stile degli interni. Vedi Opzioni dello stile degli interni
indoorElemIdstring❌ NoPreimpostazione facoltativa degli elementi della stanza. Supporta più identificatori uniti da virgole, ad esempio id1,id2

🖼️ 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.


🎨 Opzioni di stile#

indoorTypeId, indoorStyleId e indoorElemId possono essere selezionati dall'endpoint Configurazione degli stili API.

Usa:

Testo semplice
GET /api/v1/style/virtual_staging/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 name, id e url. Passa l'id dell'opzione nel campo corrispondente della richiesta.


📥 Esempi di richiesta#

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

📤 Risposta#

Risposta di successo

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

2. Ottieni il risultato dell'attività#

Recupera lo stato e l'output correnti di un'attività di allestimento virtuale creata in precedenza.

Endpoint

Testo semplice
GET /api/v1/virtualStaging/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 dell'attività

📥 Esempi di richiesta#

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

📤 Risposta#

Risposta di successo (attività completata)

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

Risposta (attività in elaborazione / in coda)

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

Risposta (attività non riuscita)

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

Campi della risposta

CampoTipoDescrizione
idlongIdentificatore univoco dell'attività
statusstringStato corrente dell'attività (vedi Stato dell'attività)
waitNumberintegerNumero di attività precedenti in coda (0 significa attualmente in elaborazione)
percentageintegerPercentuale di completamento dell'attività (0-100)
errorReasonstringMotivo dell'errore quando status è Failed
inputobjectParametri di input originali inviati per questa attività
input.imageUrlstringURL dell'immagine originale della stanza
input.promptstringPrompt dell'utente (se fornito)
input.indoorTypeIdstringPreimpostazione del tipo di stanza usata (se fornita)
input.indoorStyleIdstringPreimpostazione dello stile degli interni usata (se fornita)
input.indoorElemIdstringPreimpostazione degli elementi della stanza usata (se fornita). Può contenere più identificatori uniti da virgole
outputobjectRisultato della generazione (disponibile soltanto quando status è Success)
output.resultUrlstringURL dell'immagine generata di allestimento virtuale
output.widthintegerLarghezza dell'immagine risultante in pixel
output.heightintegerAltezza dell'immagine risultante in pixel

📊 Stato dell'attività#

StatoSignificato
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#

Tutte le risposte di errore condividono la stessa struttura JSON:

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

Riferimento dei codici di errore#

CodiceNomeDescrizioneAzione suggerita
1001FAILEDRichiesta non riuscita (errore generico)Controlla il campo message per i dettagli specifici
1003INTERNAL_ERRORErrore interno del serverRiprova dopo una breve attesa; contatta l'assistenza se il problema persiste
1011PARAM_ERRORErrore nei parametri della richiesta (ad esempio, imageUrl mancante)Assicurati che imageUrl sia fornito e sia una URL valida
5002API_KEY_INVALIDChiave API non valida o mancanteAssicurati che l'intestazione APIKEY sia presente e corretta
9010SCAN_TEXT_ERRORIl prompt non ha superato la moderazione dei contenutiModifica il prompt per rimuovere contenuti sensibili o vietati
9038PROHIBITED_CONTENTL'immagine generata contiene contenuti vietatiModifica prompt/stile/input e riprova
9051COINS_NOT_ENOUGHCrediti insufficientiRicarica i crediti e riprova

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