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

Документация API по виртуальной меблировке#

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


📖 Обзор#

API по виртуальной меблировке позволяет перепроектировать пустую или частично меблированную комнату с помощью ИИ.
Вы отправляете URL изображения комнаты и необязательный текстовый запрос, затем асинхронно получаете сгенерированный результат.

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

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

Все запросы API должны проходить аутентификацию с помощью ключа API.

Укажите ваш ключ API в заголовке запроса:

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

⚠️ Держите ваш ключ API в тайне. Не публикуйте его в клиентском коде или публичных репозиториях.


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

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

ОперацияСписанные кредиты
Задача виртуальной меблировки1 кредит

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


1. Создание задачи виртуальной меблировки#

Создает новую задачу виртуального меблирования и возвращает уникальный taskId для опроса.

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

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

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

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

Тело запроса

ПолеТипОбязательныйОписание
imageUrlstring✅ ДаURL исходного изображения комнаты
promptstring❌ НетНеобязательный промпт для управления стилем и меблировкой
indoorTypeIdstring❌ НетНеобязательный пресет типа комнаты. См. Варианты типов помещений
indoorStyleIdstring❌ НетНеобязательный пресет стиля интерьера. См. Варианты стилей интерьера
indoorElemIdstring❌ НетНеобязательный пресет элемента комнаты. Поддерживается несколько идентификаторов, разделенных запятой, например id1,id2

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


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

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

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

Обычный текст
GET /api/v1/style/virtual_staging/getStyles
Группа стилейПоле запросаОписание
roomTypeindoorTypeIdВариант типа комнаты
styleindoorStyleIdВариант стиля интерьера
elementsindoorElemIdВариант элемента комнаты. Можно передать несколько идентификаторов вариантов через запятую, например id1,id2

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


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

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/empty-living-room.jpg",
    "prompt": "Warm and modern living room styling",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class VirtualStagingApiExample {

    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/empty-bedroom.jpg",
                    "prompt": "Cozy contemporary bedroom",
                    "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
                    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/virtualStaging/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/empty-home-office.jpg",
    "prompt": "Minimal modern home office",
    "indoorTypeId": "Interior Design_Interior Scene_Home Office",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/virtualStaging/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 createVirtualStagingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/virtualStaging/generate`,
      {
        imageUrl: 'https://example.com/empty-dining-room.jpg',
        prompt: 'Modern luxury dining room',
        indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
        indoorElemId: 'Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table'
      },
      {
        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);
  }
}

createVirtualStagingTask();

📤 Ответ#

Успешный ответ

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
ПолеТипОписание
codeinteger0 указывает на успех
messagestringСообщение в ответе
datalongУникальный идентификатор задачи для опроса результатов

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

Получает текущий статус и результат ранее созданной задачи виртуального меблирования.

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

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

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

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

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

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

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

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

import java.io.IOException;

public class VirtualStagingResultExample {

    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/virtualStaging/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/virtualStaging/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":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Size:", output["width"], "x", output["height"])
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 pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

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

pollResult(1234567890123456789n);

📤 Ответ#

Успешный ответ (задача завершена)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "modern country living room with warm neutral materials",
      "indoorTypeId": "Interior Design_Interior Scene_Living Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
      "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/virtual_staging_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 46,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "coastal bedroom with soft light and natural textures",
      "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
    },
    "output": null
  }
}

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

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

Поля ответа

ПолеТипОписание
idlongУникальный идентификатор задачи
statusstringТекущий статус задачи (см. Статус задачи)
waitNumberintegerКоличество задач впереди в очереди (0 означает текущую обработку)
percentageintegerПроцент завершения задачи (0-100)
errorReasonstringПричина сбоя, когда status равно Failed
inputobjectИсходные входные параметры, отправленные для этой задачи
input.imageUrlstringURL исходного изображения комнаты
input.promptstringПромпт пользователя (если предоставлен)
input.indoorTypeIdstringИспользованный пресет типа комнаты (если предоставлен)
input.indoorStyleIdstringИспользованный пресет стиля интерьера (если предоставлен)
input.indoorElemIdstringИспользованный пресет элемента комнаты (если предоставлен). Может содержать несколько идентификаторов, разделенных запятой
outputobjectРезультат генерации (доступен только когда status равно Success)
output.resultUrlstringURL сгенерированного изображения с результатом виртуальной меблировки
output.widthintegerШирина выходного изображения в пикселях
output.heightintegerВысота выходного изображения в пикселях

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

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

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


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

Все ответы об ошибках имеют одинаковую структуру JSON:

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

Справочник кодов ошибок#

КодНазваниеОписаниеРекомендуемое действие
1001FAILEDЗапрос не выполнен (общая ошибка)Проверьте поле message для получения конкретных деталей
1003INTERNAL_ERRORВнутренняя ошибка сервераПовторите попытку после короткой задержки; обратитесь в поддержку, если проблема сохраняется
1011PARAM_ERRORОшибка параметров запроса (например, отсутствует imageUrl)Убедитесь, что imageUrl предоставлен и является действительным URL
5002API_KEY_INVALIDНедействительный или отсутствующий ключ APIУбедитесь, что заголовок APIKEY присутствует и корректен
9010SCAN_TEXT_ERRORТекстовый запрос не прошёл модерацию контентаУдалите из запроса чувствительный или запрещённый контент
9038PROHIBITED_CONTENTСгенерированное выходное изображение содержит запрещенный контентОтрегулируйте промпт/стиль/входные данные и повторите попытку
9051COINS_NOT_ENOUGHНедостаточно кредитовПополните кредиты и повторите попытку

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