Ideal House
Passa al contenuto

Documentazione API di ristrutturazione degli interni#

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


📖 Panoramica#

API di ristrutturazione degli interni modifica un'immagine di interni e può usare facoltativamente opzioni di stile della stanza, indicazioni testuali e indicazioni sui colori.

Il flusso di lavoro è asincrono:

  1. Crea un'attività — Invia imageUrl e i parametri facoltativi, quindi ricevi un taskId.
  2. Interroga periodicamente i risultati — Usa taskId per recuperare lo stato dell'attività e l'immagine generata.

🔐 Autenticazione#

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, i crediti detratti vengono rimborsati automaticamente.
Un saldo di crediti insufficiente restituisce il codice di errore 9051. Consulta il Riferimento delle detrazioni dei crediti.

OperazioneCrediti detratti
Attività di ristrutturazione degli interni1 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/interoir_remodel/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.


🎨 Indicazioni sui colori#

colorString e colorImgUrl sono input facoltativi per le indicazioni sui colori:

CasoComportamento
Viene fornito soltanto colorStringUsa colorString
Viene fornito soltanto colorImgUrlUsa l'immagine di riferimento dei colori
Vengono forniti entrambicolorString ha la precedenza
Non viene fornito nessuno dei dueLe indicazioni sui colori assumono il valore predefinito auto

📌 Endpoint API#

1. Crea un'attività di ristrutturazione degli interni#

Endpoint

Testo semplice
POST /api/v1/interiorRemodel/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 la ristrutturazione desiderata
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
colorStringstring❌ FacoltativoStringa della tavolozza di colori, ad esempio [[174,238,238],[36,36,36]]
colorImgUrlstring❌ FacoltativoURL dell'immagine di riferimento dei colori

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

🖼️ Requisiti delle immagini: tutte le immagini originali e di riferimento devono usare 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. Le URLs delle immagini devono essere direttamente accessibili dal server API.

📥 Esempi di richiesta#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/interiorRemodel/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/interior.jpg",
    "prompt": "modern warm remodel with clean built-in storage",
    "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",
    "colorString": "[[174,238,238],[36,36,36],[117,64,95]]"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class InteriorRemodelApiExample {

    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/interior.jpg",
                    "prompt": "modern warm remodel with clean built-in storage",
                    "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",
                    "colorString": "[[174,238,238],[36,36,36],[117,64,95]]"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/interiorRemodel/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/interior.jpg",
    "prompt": "modern warm remodel with clean built-in storage",
    "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",
    "colorString": "[[174,238,238],[36,36,36],[117,64,95]]"
}

response = requests.post(
    f"{BASE_URL}/api/v1/interiorRemodel/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 createInteriorRemodelTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/interiorRemodel/generate`,
      {
        imageUrl: 'https://example.com/interior.jpg',
        prompt: 'modern warm remodel with clean built-in storage',
        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',
        colorString: '[[174,238,238],[36,36,36],[117,64,95]]'
      },
      {
        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);
  }
}

createInteriorRemodelTask();

📤 Risposta#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

2. Ottieni il risultato dell'attività#

Endpoint

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

import java.io.IOException;

public class InteriorRemodelResultExample {

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

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

pollInteriorRemodelResult(1234567890123456789n);

📤 Esempio di risposta#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/interior.jpg",
      "prompt": "modern warm remodel with clean built-in storage",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
      "colorString": "[[174,238,238],[36,36,36],[117,64,95]]"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/interior_remodel_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/interior.jpg",
      "prompt": "modern warm remodel with clean built-in storage"
    },
    "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/interior.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.