Ideal House
Przejdź do treści

Dokumentacja API Renowacji Elewacji#

Podstawowy URL: https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-05-20


📖 Przegląd#

API Renowacji Elewacji umożliwia renowację lub zmianę stylu elewacji budynku na podstawie obrazu wejściowego. Przesyłasz obraz źródłowy, a opcjonalnie dodajesz wskazówki tekstowe, obraz referencyjny, styl budynku lub preferencje środowiskowe, aby sterować wynikiem renowacji.

Przepływ pracy jest asynchroniczny i obejmuje dwa kroki:

  1. Utwórz zadanie — Prześlij swój obraz elewacji i opcjonalne wskazówki, a następnie otrzymaj taskId.
  2. Sprawdzaj wyniki — Użyj taskId, aby zapytać o status zadania i pobrać wygenerowany obraz.

🔐 Uwierzytelnianie#

Wszystkie żądania API muszą być uwierzytelniane za pomocą klucza API.

Włącz swój klucz API Key w nagłówku żądania:

NagłówekWartość
APIKEYyour_api_key_here

⚠️ Zachowaj klucz API w tajemnicy. Nie ujawniaj go w kodzie po stronie klienta ani w publicznych repozytoriach.


💰 Odejmowanie kredytów#

[!WARNING] 🪙 1 kredyt jest odejmowany po pomyślnym utworzeniu zadania. Jeśli zadanie ostatecznie zawiedzie, odejęty kredyt zostanie automatycznie zwrócony na Twoje konto.
Niewystarczające kredyty spowodują zwrócenie kodu błędu 9051. 📄 Zobacz Referencja odejmowania kredytów.

OperacjaOdejęte kredyty
Zadanie Renowacji Elewacji1 kredyt

Szczegółowe zasady dotyczące kredytów znajdziesz w Referencji odejmowania kredytów.


📌 Endpoints API#


1. Utwórz zadanie Renowacji Elewacji#

Tworzy nowe zadanie renowacji elewacji i zwraca unikalny taskId do sprawdzania wyników.

Endpoint

Zwykły tekst
POST /api/v1/exteriorRenovator/generate

Nagłówki żądania

NagłówekWymaganyOpis
APIKEY✅ TakTwój klucz uwierzytelniający API
Content-Type✅ Takapplication/json

Ciało żądania

PoleTypWymaganeOpis
imageUrlstring✅ TakURL źródłowego obrazu elewacji do renowacji
promptstring❌ OpcjonalnieOpcjonalna wskazówka tekstowa dla wyniku renowacji
referenceUrlstring❌ OpcjonalnieOpcjonalny URL obrazu referencyjnego do sterowania stylem wizualnym
buildingStyleIdstring❌ OpcjonalnieOpcjonalny identyfikator stylu budynku
environmentIdstring❌ OpcjonalnieOpcjonalny identyfikator stylu środowiska lub sceny. Obsługuje wiele identyfikatorów połączonych przecinkiem, na przykład id1,id2

⚠️ Wymagane jest tylko imageUrl. Wszystkie inne pola w ciele żądania są opcjonalne.

🖼️ Wymagania dotyczące obrazów: Wszystkie obrazy źródłowe i referencyjne muszą być w formacie JPG/JPEG, PNG lub WebP. Każdy obraz nie może być większy niż 20 MB, a jego wymiary muszą mieścić się w przedziale od 128 × 128 px do 6,000 × 6,000 px (włącznie). Obrazy przekraczające maksymalne wymiary pikseli są automatycznie skalowane proporcjonalnie, aby zmieściły się w granicach 6,000 × 6,000 px przed przetwarzaniem. Adresy URL obrazów muszą być bezpośrednio dostępne dla serwera API.


🎨 Opcje stylu#

buildingStyleId i environmentId można wybrać z endpointu API Konfiguracja stylu.

Użyj:

Zwykły tekst
GET /api/v1/style/exterior_renovator/getStyles
Grupa styluPole żądaniaOpis
buildingStylebuildingStyleIdOpcja stylu budynku
environmentenvironmentIdOpcja środowiska lub sceny. Obsługuje wiele identyfikatorów opcji połączonych przecinkiem, na przykład id1,id2

Każda opcja zawiera name, id i url. Prześlij identyfikator opcji id do odpowiedniego pola żądania.


📥 Przykłady żądań#

cURL
bash
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg"
  }'

# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorApiExample {

    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/exterior.jpg",
                    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
                    "referenceUrl": "https://example.com/reference-house.jpg",
                    "buildingStyleId": "modern-farmhouse",
                    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}

response = requests.post(
    f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/exteriorRenovator/generate`,
      {
        imageUrl: 'https://example.com/exterior.jpg',
        prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
        referenceUrl: 'https://example.com/reference-house.jpg',
        buildingStyleId: 'modern-farmhouse',
        environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
      },
      {
        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);
  }
}

createExteriorRenovatorTask();

📤 Odpowiedź#

Odpowiedź sukcesu

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
PoleTypOpis
codeinteger0 oznacza sukces
messagestringKomunikat odpowiedzi
datalongUnikalny identyfikator zadania do sprawdzania wyników

2. Pobierz wynik zadania#

Pobiera bieżący status i wynik wcześniej utworzonego zadania renowacji elewacji.

Endpoint

Zwykły tekst
GET /api/v1/exteriorRenovator/result

Nagłówki żądania

NagłówekWymaganyOpis
APIKEY✅ TakTwój klucz uwierzytelniający API

Parametry zapytania

ParametrTypWymaganyOpis
taskIdlong✅ TakIdentyfikator zadania zwrócony z endpointu tworzenia zadania

📥 Przykłady żądań#

cURL
bash
curl -X GET "https://api.ideal.house/api/v1/exteriorRenovator/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorResultExample {

    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/exteriorRenovator/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/exteriorRenovator/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 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/exteriorRenovator/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;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789);

📤 Odpowiedź#

Odpowiedź sukcesu (Zadanie zakończone)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg",
      "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
      "refImageUrl": "https://example.com/reference-house.jpg",
      "buildingStyleId": "modern-farmhouse",
      "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/exterior_renovator_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Odpowiedź (Zadanie w trakcie przetwarzania / W kolejce)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 50,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg"
    },
    "output": null
  }
}

Odpowiedź (Zadanie nie powiodło się)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg"
    },
    "output": null
  }
}

Pola odpowiedzi

PoleTypOpis
idlongUnikalny identyfikator zadania
statusstringBieżący status zadania (zobacz Status zadania)
waitNumberintegerLiczba zadań przed Tobą w kolejce (0 oznacza, że zadanie jest obecnie przetwarzane)
percentageintegerProcent ukończenia zadania (0–100)
inputobjectOryginalne parametry wejściowe zadania
input.imageUrlstringURL źródłowego obrazu elewacji
input.promptstringOpcjonalna wskazówka tekstowa, jeśli została podana
input.refImageUrlstringOpcjonalny URL obrazu referencyjnego, jeśli został podany
input.buildingStyleIdstringOpcjonalny identyfikator stylu budynku, jeśli został podany
input.environmentIdstringOpcjonalny identyfikator stylu środowiska lub sceny, jeśli został podany. Może zawierać wiele identyfikatorów połączonych przecinkiem
outputobjectWynik generacji (dostępny tylko, gdy status wynosi Success)
output.resultUrlstringURL do obrazu wyniku renowacji elewacji
output.widthintegerSzerokość wyjściowa w pikselach
output.heightintegerWysokość wyjściowa w pikselach

📊 Status zadania#

StatusOpis
UnprocessedZadanie zostało utworzone, ale nie zostało jeszcze rozpoczęte
ProcessingZadanie jest obecnie przetwarzane
SuccessZadanie zakończyło się pomyślnie — wynik jest dostępny
FailedZadanie nie powiodło się z powodu błędu

Wykonuj cykliczne sprawdzanie stanu co 3-5 sekund. Zobacz Limit zadań API.


❌ Odpowiedzi błędów#

Wszystkie odpowiedzi błędów mają tę samą strukturę JSON:

json
{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Referencja kodów błędów#

KodNazwaOpisSugerowane działanie
1001FAILEDŻądanie nie powiodło się (błąd ogólny)Sprawdź pole message, aby uzyskać szczegółowe informacje o błędzie
1003INTERNAL_ERRORWewnętrzny błąd serweraPonów próbę po krótkim opóźnieniu; skontaktuj się z pomocą techniczną, jeśli problem utrzymuje się
1011PARAM_ERRORBłąd parametru żądaniaUpewnij się, że parametry żądania są poprawnie sformatowane
5002API_KEY_INVALIDNieprawidłowy lub brakujący klucz APIUpewnij się, że nagłówek APIKEY jest obecny i ma poprawną wartość
9010SCAN_TEXT_ERRORWskazówka tekstowa nie przeszła weryfikacji treściZmodyfikuj wskazówkę, aby usunąć wszelkie treści wrażliwe lub zakazane
9038PROHIBITED_CONTENTWygenerowany obraz wyjściowy zawiera treści zakazaneDostosuj wskazówkę/styl/wejścia i ponów próbę
9051COINS_NOT_ENOUGHNiewystarczające monety / kredytyDoładuj kredyty na swoim koncie i ponów próbę. Zobacz Referencja odejmowania kredytów

📄 Pełną listę wspólnych kodów błędów API znajdziesz w Referencji kodów błędów.