Ideal House
Passa al contenuto

Documentazione API di sostituzione delle texture#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-03-25


📖 Panoramica#

API di sostituzione delle texture consente di sostituire la texture o il materiale di un'area selezionata in un'immagine usando un'immagine di riferimento dello stile. Fornisci un'immagine originale, un'immagine di riferimento dello stile che definisce la texture/il materiale desiderati e un'immagine maschera che specifica l'area in cui applicare la nuova texture. L'intelligenza artificiale integra armoniosamente la nuova texture nella scena originale. Il flusso di lavoro è asincrono e prevede due passaggi:

  1. Crea un'attività — Invia l'immagine originale, l'immagine dello stile, la maschera e i parametri, quindi ricevi un taskId.
  2. Interroga periodicamente i risultati — Usa il taskId per interrogare lo stato dell'attività e recuperare 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] 🪙 3 crediti vengono detratti alla creazione riuscita dell'attività. Se alla fine l'attività non riesce, i crediti detratti vengono rimborsati automaticamente sul tuo account.
Un saldo di crediti insufficiente restituisce il codice di errore 9051. 📄 Consulta il Riferimento delle detrazioni dei crediti.

OperazioneCrediti detratti
Attività di sostituzione delle texture3 crediti

🖼️ Formato dell'immagine maschera#

L'immagine maschera definisce l'area in cui verrà applicata la sostituzione della texture.

Regole della maschera:

ColoreSignificato
NeroArea in cui applicare la nuova texture (regione da sostituire)
BiancoArea da conservare (sfondo da mantenere invariato)

⚠️ L'immagine maschera deve avere le stesse dimensioni dell'immagine originale (imageUrl).

Esempio di maschera:

Esempio di maschera

L'area nera della maschera definisce dove verrà applicata la nuova texture; l'area bianca è lo sfondo da conservare.


📌 Endpoint API#


1. Crea un'attività di sostituzione delle texture#

Crea una nuova attività di sostituzione delle texture con intelligenza artificiale e restituisce un taskId univoco per le interrogazioni periodiche.

Endpoint

Testo semplice
POST /api/v1/textureReplacer/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 (la stanza/scena a cui applicare la texture)
styleImageUrlstring✅ SìURL dell'immagine di riferimento dello stile che definisce la texture o il materiale desiderati
maskUrlstring⚠️ Uno tra maskUrl e maskBase64URL dell'immagine maschera. Le aree nere riceveranno la nuova texture; quelle bianche verranno conservate
maskBase64string⚠️ Uno tra maskUrl e maskBase64Immagine maschera codificata in Base64 (formato PNG consigliato). Usata quando non puoi fornire una URL ospitata
promptstring❌ FacoltativoPrompt testuale aggiuntivo per orientare ulteriormente la generazione della texture

⚠️ Deve essere fornito almeno uno tra maskUrl e maskBase64. Se sono forniti entrambi, maskUrl ha la precedenza.

🖼️ Requisiti delle immagini: le immagini originale, dello stile e della maschera 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. Una maschera Base64 è soggetta agli stessi limiti per l'immagine decodificata e non deve includere un prefisso data-URL.


📥 Esempi di richiesta#

cURL
bash
# Using maskUrl
curl -X POST "https://api.ideal.house/api/v1/textureReplacer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/marble-texture.jpg",
    "maskUrl": "https://example.com/mask.png"
  }'

# Using maskBase64 with optional prompt
curl -X POST "https://api.ideal.house/api/v1/textureReplacer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/wood-texture.jpg",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "prompt": "natural oak wood grain texture"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class TextureReplacerApiExample {

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

        // Option 1: Use maskUrl
        String requestBody = """
                {
                    "imageUrl": "https://example.com/room.jpg",
                    "styleImageUrl": "https://example.com/marble-texture.jpg",
                    "maskUrl": "https://example.com/mask.png"
                }
                """;

        // Option 2: Use maskBase64 (encode local mask file)
        // byte[] maskBytes = Files.readAllBytes(Path.of("/path/to/mask.png"));
        // String maskBase64 = Base64.getEncoder().encodeToString(maskBytes);
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "styleImageUrl": "https://example.com/marble-texture.jpg",
        //         "maskBase64": "%s",
        //         "prompt": "natural oak wood grain texture"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/textureReplacer/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
import base64

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Option 1: Use maskUrl
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/marble-texture.jpg",
    "maskUrl": "https://example.com/mask.png"
}

# Option 2: Use maskBase64 with optional prompt
# with open("/path/to/mask.png", "rb") as f:
#     mask_base64 = base64.b64encode(f.read()).decode("utf-8")
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "styleImageUrl": "https://example.com/wood-texture.jpg",
#     "maskBase64": mask_base64,
#     "prompt": "natural oak wood grain texture"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/textureReplacer/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 fs = require('fs');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createTextureReplacerTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      styleImageUrl: 'https://example.com/marble-texture.jpg',
      maskUrl: 'https://example.com/mask.png'
    };

    // Option 2: Use maskBase64 with optional prompt
    // const maskBuffer = fs.readFileSync('/path/to/mask.png');
    // const maskBase64 = maskBuffer.toString('base64');
    // const payload = {
    //   imageUrl: 'https://example.com/room.jpg',
    //   styleImageUrl: 'https://example.com/wood-texture.jpg',
    //   maskBase64: maskBase64,
    //   prompt: 'natural oak wood grain texture'
    // };

    const response = await axios.post(
      `${BASE_URL}/api/v1/textureReplacer/generate`,
      payload,
      {
        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);
  }
}

createTextureReplacerTask();

📤 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 sostituzione delle texture creata in precedenza.

Endpoint

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

import java.io.IOException;

public class TextureReplacerResultExample {

    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/textureReplacer/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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/textureReplacer/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)  # Poll every 3 seconds

if status == "Success":
    print("Result URL:", result["output"]["resultUrl"])
else:
    print("Task failed")
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/textureReplacer/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 failed');
      }
      break;
    }

    // Wait 3 seconds before next poll
    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/room.jpg",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png",
      "prompt": "natural marble texture with grey veining"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/texture_replacer_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": 50,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png"
    },
    "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",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png"
    },
    "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)
inputobjectParametri di input originali dell'attività
input.imageUrlstringURL dell'immagine originale
input.styleImageUrlstringURL dell'immagine di riferimento dello stile
input.maskUrlstringURL dell'immagine maschera (se fornita tramite maskUrl)
input.promptstringPrompt testuale aggiuntivo (se fornito)
outputobjectRisultato della generazione (disponibile soltanto quando status è Success)
output.resultUrlstringURL dell'immagine risultante con la texture sostituita
output.widthintegerLarghezza dell'output in pixel
output.heightintegerAltezza dell'output in pixel

📊 Stato dell'attività#

StatoDescrizione
UnprocessedL'attività è stata creata ma non è ancora iniziata
ProcessingL'attività è attualmente in elaborazione
SuccessL'attività è stata completata correttamente — l'output è disponibile
FailedL'attività non è riuscita a causa di un errore

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 dell'errore
1003INTERNAL_ERRORErrore interno del serverRiprova dopo una breve attesa; contatta l'assistenza se il problema persiste
1011PARAM_ERRORErrore nei parametri della richiesta — e.g., imageUrl, styleImageUrl o maschera mancanteAssicurati che tutti i campi obbligatori siano forniti
5002API_KEY_INVALIDChiave API non valida o mancanteAssicurati che l'intestazione APIKEY sia presente e che il valore sia corretto
9010SCAN_TEXT_ERRORIl prompt testuale non ha superato la verifica dei contenutiModifica il prompt per rimuovere eventuali contenuti sensibili o vietati
9038PROHIBITED_CONTENTL'immagine generata contiene contenuti vietatiModifica prompt/stile/input e riprova
9051COINS_NOT_ENOUGHMonete / crediti insufficientiRicarica i crediti dell'account e riprova

📄 Per l'elenco completo dei codici di errore API comuni, consulta il Riferimento dei codici di errore.