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.
- Crea un'attività — Invia
imageUrle le indicazioni facoltative, quindi ricevi untaskId. - Interroga periodicamente i risultati — Usa
taskIdper interrogare lo stato dell'attività e l'immagine risultante.
🔐 Autenticazione#
Tutte le richieste API devono includere una chiave API nell'intestazione della richiesta.
| Intestazione | Valore |
|---|---|
APIKEY | your_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 errore9051. Consulta il Riferimento delle detrazioni dei crediti.
| Operazione | Crediti detratti |
|---|---|
| Attività di sostituzione dei mobili | 1 credito |
🎨 Opzioni di stile#
Questa API supporta parametri di stile facoltativi restituiti dall'endpoint Configurazione degli stili API.
Usa:
GET /api/v1/style/change_furniture/getStyles
| Gruppo di stile | Campo della richiesta | Descrizione |
|---|---|---|
roomType | indoorTypeId | Opzione del tipo di stanza |
style | indoorStyleId | Opzione dello stile degli interni |
elements | indoorElemId | Opzione degli elementi della stanza. Supporta più identificatori di opzione uniti da virgole, ad esempio id1,id2 |
Ogni opzione contiene:
| Campo | Descrizione |
|---|---|
name | Nome multilingue dell'opzione |
id | Valore da passare nel campo della richiesta |
url | Immagine di anteprima dell'opzione |
📌 Endpoint API#
1. Crea un'attività di sostituzione dei mobili#
Endpoint
POST /api/v1/changeFurniture/generate
Intestazioni della richiesta
| Intestazione | Obbligatoria | Descrizione |
|---|---|---|
APIKEY | ✅ Sì | La tua chiave di autenticazione API |
Content-Type | ✅ Sì | application/json |
Corpo della richiesta
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
imageUrl | string | ✅ Sì | URL dell'immagine di interni originale |
prompt | string | ❌ Facoltativo | Indicazioni testuali per il risultato desiderato |
indoorTypeId | string | ❌ Facoltativo | Identificatore del tipo di stanza dalle opzioni di stile roomType |
indoorStyleId | string | ❌ Facoltativo | Identificatore dello stile degli interni dalle opzioni di stile style |
indoorElemId | string | ❌ Facoltativo | Identificatore 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
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)
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)
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)
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#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
| Campo | Tipo | Descrizione |
|---|---|---|
code | integer | 0 indica il successo |
message | string | Messaggio della risposta |
data | long | Identificatore dell'attività per interrogare periodicamente i risultati |
2. Ottieni il risultato dell'attività#
Endpoint
GET /api/v1/changeFurniture/result
Intestazioni della richiesta
| Intestazione | Obbligatoria | Descrizione |
|---|---|---|
APIKEY | ✅ Sì | La tua chiave di autenticazione API |
Parametri di interrogazione
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
taskId | long | ✅ Sì | Identificatore dell'attività restituito dall'endpoint di creazione |
📥 Esempi di richiesta#
cURL
curl -X GET "https://api.ideal.house/api/v1/changeFurniture/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
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)
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)
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#
{
"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)
{
"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)
{
"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à#
| Stato | Descrizione |
|---|---|
Unprocessed | L'attività è stata creata ed è in attesa in coda |
Processing | L'attività è attualmente in esecuzione |
Success | L'attività è stata completata correttamente |
Failed | L'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#
| Codice | Nome | Descrizione |
|---|---|---|
1011 | PARAM_ERROR | Errore nei parametri della richiesta |
5002 | API_KEY_INVALID | Chiave API non valida o mancante |
9010 | SCAN_TEXT_ERROR | Il prompt non ha superato la verifica dei contenuti |
9038 | PROHIBITED_CONTENT | L'immagine generata contiene contenuti vietati |
9051 | COINS_NOT_ENOUGH | Crediti insufficienti |
Per le definizioni complete degli errori comuni, consulta il Riferimento dei codici di errore.