Ideal House
Zum Hauptinhalt springen

API zur Raumdekoration Dokumentation#

Basis-URL:https://api.ideal.house
Version: v1
Aktualisiert: 2026-05-21


📖 Übersicht#

Die API zur Raumdekoration erstellt Dekorationsideen für ein Innenraumbild. Sie unterstützt optionale Textanweisungen, ein Referenzbild, Stilauswahlen und Modellmodi.

Der Arbeitsablauf ist asynchron:

  1. Aufgabe erstellen — Senden Sie imageUrl und optionale Parameter, dann erhalten Sie eine taskId.
  2. Ergebnisse regelmäßig abfragen — Verwenden Sie taskId, um Aufgabestatus und das generierte Bild abzurufen.

🔐 Authentifizierung#

KopfzeileWert
APIKEYyour_api_key_here

💰 Guthabenverbrauch#

[!WARNING] Guthabeneinheiten werden bei erfolgreicher Aufgabenerstellung abgezogen. Wenn die Aufgabe letztendlich fehlschlägt, werden abgezogene Guthabeneinheiten automatisch erstattet.
Unzureichende Guthabeneinheiten geben Fehlercode 9051 zurück. Siehe Referenz zum Guthabenverbrauch.

Modell (modelType)Abgezogene Guthabeneinheiten
Base3 Guthabeneinheiten
Pro10 Guthabeneinheiten

Wenn modelType nicht angegeben wird, wird standardmäßig Base verwendet.


🎨 Stileinstellungen#

Diese API unterstützt optionale Stilkonfigurationen, die vom API-Stilkonfiguration-Endpunkt zurückgegeben werden.

Verwenden:

Klartext
GET /api/v1/style/home_decor_ideas/getStyles
StilgruppeAnforderungsfeldBeschreibung
spaceTypespaceStyleIdOption für Raum- oder Zimmerart
decorStylehomeDecorStyleIdOption für Dekorationsstil

Jede Option enthält name, id und url. Übergeben Sie die Option-id in das entsprechende Anforderungsfeld.


📌 API Endpunkte#

1. Aufgabe zur Raumdekoration erstellen#

Endpunkt

Klartext
POST /api/v1/homeDecor/generate

Anforderungsheader

KopfzeileErforderlichBeschreibung
APIKEY✅ JaIhr API Authentifizierungsschlüssel
Content-Type✅ Jaapplication/json

Anforderungskörper

FeldTypErforderlichBeschreibung
imageUrlstring✅ JaURL des Quellinnenraumbilds
referenceUrlstring❌ OptionalReferenzbild-URL zur Steuerung des Dekorationsstils
spaceStyleIdstring❌ OptionalRaumtyp-ID aus den spaceType-Stilauswahlmöglichkeiten
homeDecorStyleIdstring❌ OptionalDekorstil-ID aus den decorStyle-Stilauswahlmöglichkeiten
promptstring❌ OptionalTextanleitung für das gewünschte Ergebnis
modelTypestring❌ OptionalEnum: Base, Pro. Standardmäßig Base

Nur imageUrl ist erforderlich. Alle anderen Felder sind optional.

🖼️ Bildanforderungen: Alle Ausgangs- und Referenzbilder müssen JPG/JPEG, PNG oder WebP verwenden. Jedes Bild darf maximal 20 MB groß sein, mit Abmessungen von 128 × 128 px bis zu 6,000 × 6,000 px (inklusive). Bilder, die die maximalen Pixelabmessungen überschreiten, werden automatisch proportional herunter-skaliert, um innerhalb von 6,000 × 6,000 px vor der Verarbeitung zu passen. Bild-URLs müssen direkt vom API Server erreichbar sein.

📥 Anfragebeispiele#

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

📤 Antwort#

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

2. Aufgabenergebnis abrufen#

Endpunkt

Klartext
GET /api/v1/homeDecor/result

Anforderungsheader

KopfzeileErforderlichBeschreibung
APIKEY✅ JaIhr API Authentifizierungsschlüssel

Abfrageparameter

ParameterTypErforderlichBeschreibung
taskIdlong✅ JaVom Erstellungsendpunkt zurückgegebene Aufgaben-ID

📥 Anfragebeispiele#

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

📤 Antwortbeispiel#

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

Antwort (Aufgabe in Bearbeitung / in Warteschlange)

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

Antwort (Aufgabe fehlgeschlagen)

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

📊 Aufgabenstatus#

StatusBeschreibung
UnprocessedAufgabe wurde erstellt und wartet in der Warteschlange
ProcessingAufgabe wird derzeit ausgeführt
SuccessAufgabe erfolgreich abgeschlossen
FailedAufgabe fehlgeschlagen und keine Ausgabe erzeugt

Alle 3-5 Sekunden abfragen. Siehe API Aufgabenlimit.


❌ Fehlerantworten#

CodeNameBeschreibung
1011PARAM_ERRORAnforderungsparameterfehler
5002API_KEY_INVALIDUngültiger oder fehlender API Schlüssel
9010SCAN_TEXT_ERRORPrompt bestand Inhaltsüberprüfung nicht
9038PROHIBITED_CONTENTGeneriertes Bild enthält verbotene Inhalte
9051COINS_NOT_ENOUGHUnzureichende Guthabeneinheiten

Für vollständige gemeinsame Fehlerdefinitionen siehe Fehlercode-Referenz.