Ideal House
Przejdź do treści

Dokumentacja API Zagospodarowania Terenu#

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


📖 Przegląd#

API Zagospodarowania Terenu ulepsza lub projektuje na nowo zewnętrzne obszary krajobrazu na podstawie obrazu źródłowego. Obsługuje opcjonalne wskazówki tekstowe, opcje stylu ogrodu, elementy krajobrazu oraz tryby modelu.

Przepływ pracy jest asynchroniczny:

  1. Utwórz zadanie — Prześlij imageUrl i opcjonalne parametry, a następnie otrzymaj taskId.
  2. Sprawdzaj wyniki — Użyj taskId, aby pobrać status zadania i wygenerowany obraz.

🔐 Uwierzytelnianie#

NagłówekWartość
APIKEYyour_api_key_here

💰 Odejmowanie kredytów#

[!WARNING] Kredyty są odejmowane, gdy zadanie zostanie pomyślnie utworzone. Jeśli zadanie ostatecznie zawiedzie, odejęte kredyty zostaną automatycznie zwrócone.
Niewystarczające kredyty spowodują zwrócenie kodu błędu 9051. Zobacz Referencja odejmowania kredytów.

Model (modelType)Odejęte kredyty
Flash1 kredyt
Base3 kredyty
Pro10 kredytów

Jeśli nie podano modelType, domyślnie używany jest Base.


🎨 Opcje stylu#

Ten API obsługuje opcjonalne parametry stylu zwracane przez endpoint API Konfiguracja stylu.

Użyj:

Zwykły tekst
GET /api/v1/style/landscaping/getStyles
Grupa styluPole żądaniaOpis
gardenStylesceneIdOpcja stylu ogrodu lub krajobrazu
elementssceneElementIdOpcja elementu krajobrazu. 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.


📌 Endpoints API#

1. Utwórz zadanie Zagospodarowania Terenu#

Endpoint

Zwykły tekst
POST /api/v1/landscaping/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 krajobrazu
promptstring❌ OpcjonalnieWskazówka tekstowa dla pożądanego wyniku
sceneIdstring❌ OpcjonalnieIdentyfikator stylu ogrodu z opcji stylu gardenStyle
sceneElementIdstring❌ OpcjonalnieIdentyfikator elementu krajobrazu z opcji stylu elements. Obsługuje wiele identyfikatorów połączonych przecinkiem, na przykład id1,id2
modelTypestring❌ OpcjonalnieWyliczenie: Flash, Base, Pro. Domyślnie ustawione na Base

Wymagane jest tylko imageUrl. Wszystkie inne pola 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.

📥 Przykłady żądań#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/landscaping/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class LandscapingApiExample {

    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/backyard.jpg",
                    "prompt": "lush modern garden with clean stone paths",
                    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
                    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/landscaping/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/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/landscaping/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 createLandscapingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/landscaping/generate`,
      {
        imageUrl: 'https://example.com/backyard.jpg',
        prompt: 'lush modern garden with clean stone paths',
        sceneId: 'Landscape Design_Landscape Style_Mid-Century Modern Pool',
        sceneElementId: 'Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover',
        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);
  }
}

createLandscapingTask();

📤 Odpowiedź#

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

2. Pobierz wynik zadania#

Endpoint

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

Nagłówki żądania

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

Parametry zapytania

ParametrTypWymaganyOpis
taskIdlong✅ TakIdentyfikator zadania zwrócony przez endpoint tworzenia

📥 Przykłady żądań#

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

import java.io.IOException;

public class LandscapingResultExample {

    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/landscaping/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/landscaping/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 pollLandscapingResult(taskId) {
  const headers = { APIKEY: API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/landscaping/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));
  }
}

pollLandscapingResult(1234567890123456789n);

📤 Przykład odpowiedzi#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/backyard.jpg",
      "prompt": "lush modern garden with clean stone paths",
      "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
      "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/landscaping_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": 45,
    "input": {
      "imageUrl": "https://example.com/backyard.jpg",
      "modelType": "Base"
    },
    "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/backyard.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

📊 Status zadania#

StatusOpis
UnprocessedZadanie zostało utworzone i czeka w kolejce
ProcessingZadanie jest obecnie w trakcie wykonywania
SuccessZadanie zakończyło się pomyślnie
FailedZadanie nie powiodło się i nie wygenerowano wyniku

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


❌ Odpowiedzi błędów#

KodNazwaOpis
1011PARAM_ERRORBłąd parametru żądania
5002API_KEY_INVALIDNieprawidłowy lub brakujący klucz API
9010SCAN_TEXT_ERRORWskazówka tekstowa nie przeszła weryfikacji treści
9038PROHIBITED_CONTENTWygenerowany obraz zawiera treści zakazane
9051COINS_NOT_ENOUGHNiewystarczające kredyty

Pełne definicje wspólnych błędów znajdziesz w Referencji kodów błędów.