Dokumentacja Home Decor API#
Podstawowy URL:
https://api.ideal.house
Wersja: v1
Zaktualizowano: 2026-05-21
📖 Przegląd#
Home Decor API generuje pomysły dekoracyjne dla obrazu wnętrza. Obsługuje opcjonalne wytyczne tekstowe, obraz referencyjny, wybór stylów i tryby modeli.
Przepływ pracy jest asynchroniczny:
- Utworzenie zadania — Prześlij
imageUrli opcjonalne parametry, a następnie otrzymasztaskId. - Cykliczne sprawdzanie wyników — 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, odejmowane kredyty zostaną automatycznie zwrócone.
Niewystarczająca liczba kredytów spowoduje zwrócenie kodu błędu9051. Zobacz Odniesienie do odejmowania kredytów.
Model (modelType) | Odejmowane kredyty |
|---|---|
Base | 3 kredyty |
Pro | 10 kredyty |
Jeśli nie podano modelType, domyślnie używany jest Base.
🎨 Opcje stylów#
Ten API obsługuje opcjonalne parametry stylów zwracane przez punkt końcowy Konfiguracja stylów API.
Użyj:
GET /api/v1/style/home_decor_ideas/getStyles
| Grupa stylów | Pole żądania | Opis |
|---|---|---|
spaceType | spaceStyleId | Opcja typu przestrzeni lub pokoju |
decorStyle | homeDecorStyleId | Opcja stylu dekoracji |
Każda opcja zawiera name, id i url. Przekazuj id opcji do odpowiedniego pola żądania.
📌 API Punkty końcowe#
1. Utworzenie zadania Home Decor#
Punkt końcowy
POST /api/v1/homeDecor/generate
Nagłówki żądania
| Nagłówek | Wymagane | Opis |
|---|---|---|
APIKEY | ✅ Tak | Twój klucz uwierzytelniający API |
Content-Type | ✅ Tak | application/json |
Ciało żądania
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
imageUrl | string | ✅ Tak | Adres URL źródłowego obrazu wnętrza |
referenceUrl | string | ❌ Opcjonalnie | Adres URL obrazu referencyjnego do kierowania stylem dekoracji |
spaceStyleId | string | ❌ Opcjonalnie | ID typu przestrzeni z opcji stylów spaceType |
homeDecorStyleId | string | ❌ Opcjonalnie | ID stylu dekoracji z opcji stylów decorStyle |
prompt | string | ❌ Opcjonalnie | Wytyczne tekstowe dla pożądanego wyniku |
modelType | string | ❌ Opcjonalnie | Wyliczenie: Base, Pro. Domyślnie 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ć się w 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/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)
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)
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)
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();
📤 Odpowiedź#
{
"code": 0,
"message": "success",
"data": 1234567890123456789
}
2. Pobranie wyniku zadania#
Punkt końcowy
GET /api/v1/homeDecor/result
Nagłówki żądania
| Nagłówek | Wymagane | Opis |
|---|---|---|
APIKEY | ✅ Tak | Twój klucz uwierzytelniający API |
Parametry zapytania
| Parametr | Typ | Wymagane | Opis |
|---|---|---|---|
taskId | long | ✅ Tak | Identyfikator zadania zwrócony przez punkt końcowy tworzenia |
📥 Przykłady żądań#
cURL
curl -X GET "https://api.ideal.house/api/v1/homeDecor/result?taskId=1234567890123456789" \
-H "APIKEY: your_api_key_here"
Java (OkHttp)
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)
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)
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);
📤 Przykład odpowiedzi#
{
"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
}
}
}
Odpowiedź (Zadanie w trakcie / W kolejce)
{
"code": 0,
"message": "success",
"data": {
"id": 1234567890123456789,
"status": "Processing",
"waitNumber": 1,
"percentage": 45,
"input": {
"imageUrl": "https://example.com/room.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/room.jpg",
"modelType": "Base"
},
"output": null
}
}
📊 Status zadania#
| Status | Opis |
|---|---|
Unprocessed | Zadanie zostało utworzone i czeka w kolejce |
Processing | Zadanie jest obecnie w trakcie |
Success | Zadanie zakończono pomyślnie |
Failed | Zadanie nie powiodło się i nie wygenerowano wyniku |
Wykonuj cykliczne sprawdzanie 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 | Prompt nie przeszedł przeglądu treści |
9038 | PROHIBITED_CONTENT | Wygenerowany obraz zawiera zakazane treści |
9051 | COINS_NOT_ENOUGH | Niewystarczająca liczba kredytów |
Pełne definicje wspólnych błędów znajdziesz w Odniesieniu do kodów błędów.