Ideal House
Passa al contenuto

Documentazione API di decorazione della casa#

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


📖 Panoramica#

API di decorazione della casa genera idee decorative per un'immagine di interni. Supporta indicazioni testuali facoltative, un'immagine di riferimento, selezioni di stile e modalità del modello.

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] I crediti vengono detratti 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.

Modello (modelType)Crediti detratti
Base3 crediti
Pro10 crediti

Se modelType non viene fornito, viene usato Base per impostazione predefinita.


🎨 Opzioni di stile#

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

Usa:

Testo semplice
GET /api/v1/style/home_decor_ideas/getStyles
Gruppo di stileCampo della richiestaDescrizione
spaceTypespaceStyleIdOpzione del tipo di spazio o stanza
decorStylehomeDecorStyleIdOpzione dello stile decorativo

Ogni opzione contiene name, id e url. Passa l'id dell'opzione nel campo corrispondente della richiesta.


📌 Endpoint API#

1. Crea un'attività di decorazione della casa#

Endpoint

Testo semplice
POST /api/v1/homeDecor/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
referenceUrlstring❌ FacoltativoURL dell'immagine di riferimento per orientare lo stile decorativo
spaceStyleIdstring❌ FacoltativoIdentificatore del tipo di spazio dalle opzioni di stile spaceType
homeDecorStyleIdstring❌ FacoltativoIdentificatore dello stile decorativo dalle opzioni di stile decorStyle
promptstring❌ FacoltativoIndicazioni testuali per il risultato desiderato
modelTypestring❌ FacoltativoEnumerazione: Base, Pro. Valore predefinito: Base

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

📤 Risposta#

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

2. Ottieni il risultato dell'attività#

Endpoint

Testo semplice
GET /api/v1/homeDecor/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/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);

📤 Esempio di risposta#

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

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/room.jpg",
      "modelType": "Base"
    },
    "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/room.jpg",
      "modelType": "Base"
    },
    "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.