Ideal House
Перейти к содержанию

Документация API по ландшафтному дизайну#

Базовый URL: https://api.ideal.house
Версия: v1
Обновлено: 2026-05-21


📖 Обзор#

API по ландшафтному дизайну улучшает или перепроектирует внешние ландшафтные зоны на основе исходного изображения. Поддерживаются необязательные текстовые указания, варианты стиля сада, элементы ландшафта и режимы моделей.

Рабочий процесс является асинхронным:

  1. Создание задачи — Отправьте imageUrl и необязательные параметры, затем получите taskId.
  2. Опрос результатов — Используйте taskId для получения статуса задачи и сгенерированного изображения.

🔐 Аутентификация#

ЗаголовокЗначение
APIKEYyour_api_key_here

💰 Списание кредитов#

[!WARNING] Кредиты списываются при успешном создании задачи. Если задача в итоге завершится ошибкой, списанные кредиты будут автоматически возвращены.
При недостатке кредитов возвращается код ошибки 9051. См. Справочник по списанию кредитов.

Модель (modelType)Списанные кредиты
Flash1 кредит
Base3 кредита
Pro10 кредитов

Если modelType не предоставлен, по умолчанию используется Base.


🎨 Варианты стиля#

Этот API поддерживает необязательные параметры стиля, возвращаемые конечной точкой Конфигурация стилей API.

Используйте:

Обычный текст
GET /api/v1/style/landscaping/getStyles
Группа стилейПоле запросаОписание
gardenStylesceneIdВариант стиля сада или ландшафта
elementssceneElementIdВариант элемента ландшафта. Поддерживается несколько идентификаторов вариантов, разделенных запятой, например id1,id2

Каждый вариант содержит name, id и url. Передайте id варианта в соответствующее поле запроса.


📌 Конечные точки API#

1. Создание задачи ландшафтного дизайна#

Конечная точка

Обычный текст
POST /api/v1/landscaping/generate

Заголовки запроса

ЗаголовокОбязательныйОписание
APIKEY✅ ДаВаш ключ аутентификации API
Content-Type✅ Даapplication/json

Тело запроса

ПолеТипОбязательныйОписание
imageUrlstring✅ ДаURL исходного изображения ландшафта
promptstring❌ НеобязательноТекстовые указания для желаемого результата
sceneIdstring❌ НеобязательноИдентификатор стиля сада из вариантов стиля gardenStyle
sceneElementIdstring❌ НеобязательноИдентификатор элемента ландшафта из вариантов стиля elements. Поддерживается несколько идентификаторов, разделенных запятой, например id1,id2
modelTypestring❌ НеобязательноПеречисление: Flash, Base, Pro. По умолчанию Base

Обязательно только imageUrl. Все остальные поля являются необязательными.

🖼️ Требования к изображениям: Все исходные изображения и изображения-образцы должны быть в формате JPG/JPEG, PNG или WebP. Размер файла не должен превышать 20 МБ, а размеры изображения должны находиться в пределах от 128 × 128 пикс. до 6,000 × 6,000 пикс. (включительно). Перед обработкой изображения, превышающие максимальные размеры в пикселях, автоматически уменьшаются с сохранением пропорций до пределов 6,000 × 6,000 пикс. Изображения по указанным URL должны быть напрямую доступны серверу API.

📥 Примеры запросов#

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

📤 Ответ#

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

2. Получение результата задачи#

Конечная точка

Обычный текст
GET /api/v1/landscaping/result

Заголовки запроса

ЗаголовокОбязательныйОписание
APIKEY✅ ДаВаш ключ аутентификации API

Параметры запроса

ПараметрТипОбязательныйОписание
taskIdlong✅ ОбязательноИдентификатор задачи, возвращенный конечной точкой создания

📥 Примеры запросов#

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

📤 Пример ответа#

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

Ответ (обработка задачи / в очереди)

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

Ответ (задача завершилась ошибкой)

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

📊 Статус задачи#

СтатусОписание
UnprocessedЗадача создана и ожидает в очереди
ProcessingЗадача в настоящее время выполняется
SuccessЗадача успешно завершена
FailedЗадача завершилась ошибкой, результат не создан

Опрашивайте каждые 3-5 секунд. См. Лимит задач API.


❌ Ответы об ошибках#

КодНазваниеОписание
1011PARAM_ERRORОшибка параметров запроса
5002API_KEY_INVALIDНедействительный или отсутствующий ключ API
9010SCAN_TEXT_ERRORПромпт не прошел проверку контента
9038PROHIBITED_CONTENTСгенерированное изображение содержит запрещенный контент
9051COINS_NOT_ENOUGHНедостаточно кредитов

Полные описания общих ошибок приведены в Справочнике кодов ошибок.