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:
- Utwórz zadanie — Prześlij
imageUrli opcjonalne parametry, a następnie otrzymajtaskId. - Sprawdzaj wyniki — Użyj
taskId, aby pobrać status zadania i wygenerowany obraz.
🔐 Uwierzytelnianie#
| Nagłówek | Wartość |
|---|---|
APIKEY | your_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łędu9051. Zobacz Referencja odejmowania kredytów.
Model (modelType) | Odejęte kredyty |
|---|---|
Flash | 1 kredyt |
Base | 3 kredyty |
Pro | 10 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:
GET /api/v1/style/landscaping/getStyles
| Grupa stylu | Pole żądania | Opis |
|---|---|---|
gardenStyle | sceneId | Opcja stylu ogrodu lub krajobrazu |
elements | sceneElementId | Opcja 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
POST /api/v1/landscaping/generate
Nagłówki żądania
| Nagłówek | Wymagany | Opis |
|---|---|---|
APIKEY | ✅ Tak | Twój klucz uwierzytelniający API |
Content-Type | ✅ Tak | application/json |
Ciało żądania
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
imageUrl | string | ✅ Tak | URL źródłowego obrazu krajobrazu |
prompt | string | ❌ Opcjonalnie | Wskazówka tekstowa dla pożądanego wyniku |
sceneId | string | ❌ Opcjonalnie | Identyfikator stylu ogrodu z opcji stylu gardenStyle |
sceneElementId | string | ❌ Opcjonalnie | Identyfikator elementu krajobrazu z opcji stylu elements. Obsługuje wiele identyfikatorów połączonych przecinkiem, na przykład id1,id2 |
modelType | string | ❌ Opcjonalnie | Wyliczenie: 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
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)
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)
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)
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ź#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Pobierz wynik zadania#
Endpoint
GET /api/v1/landscaping/result
Nagłówki żądania
| Nagłówek | Wymagany | Opis |
|---|---|---|
APIKEY | ✅ Tak | Twój klucz uwierzytelniający API |
Parametry zapytania
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
taskId | long | ✅ Tak | Identyfikator zadania zwrócony przez endpoint tworzenia |
📥 Przykłady żądań#
cURL
curl -X GET "https://api.ideal.house/api/v1/landscaping/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
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)
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)
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#
{
"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)
{
"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ę)
{
"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#
| Status | Opis |
|---|---|
Unprocessed | Zadanie zostało utworzone i czeka w kolejce |
Processing | Zadanie jest obecnie w trakcie wykonywania |
Success | Zadanie zakończyło się pomyślnie |
Failed | Zadanie nie powiodło się i nie wygenerowano wyniku |
Wykonuj cykliczne sprawdzanie stanu co 3-5 sekund. Zobacz Limit zadań API.
❌ Odpowiedzi błędów#
| Kod | Nazwa | Opis |
|---|---|---|
1011 | PARAM_ERROR | Błąd parametru żądania |
5002 | API_KEY_INVALID | Nieprawidłowy lub brakujący klucz API |
9010 | SCAN_TEXT_ERROR | Wskazówka tekstowa nie przeszła weryfikacji treści |
9038 | PROHIBITED_CONTENT | Wygenerowany obraz zawiera treści zakazane |
9051 | COINS_NOT_ENOUGH | Niewystarczające kredyty |
Pełne definicje wspólnych błędów znajdziesz w Referencji kodów błędów.