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

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

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


📖 Обзор#

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

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

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

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

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

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

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

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


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

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

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

Подробные правила списания кредитов приведены в Справочнике по списанию кредитов.


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


1. Создание задачи обновления экстерьера#

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

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

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

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

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

Тело запроса

ПолеТипОбязательныйОписание
imageUrlstring✅ ДаURL исходного изображения фасада для обновления
promptstring❌ НеобязательноНеобязательные текстовые указания для результата обновления
referenceUrlstring❌ НеобязательноНеобязательный URL изображения-образца, задающего визуальный стиль
buildingStyleIdstring❌ НеобязательноНеобязательный идентификатор стиля здания
environmentIdstring❌ НеобязательноНеобязательный идентификатор стиля окружения или сцены. Поддерживается несколько идентификаторов, разделенных запятой, например id1,id2

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

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


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

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

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

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

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


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

cURL
bash
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg"
  }'

# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorApiExample {

    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/exterior.jpg",
                    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
                    "referenceUrl": "https://example.com/reference-house.jpg",
                    "buildingStyleId": "modern-farmhouse",
                    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}

response = requests.post(
    f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/exteriorRenovator/generate`,
      {
        imageUrl: 'https://example.com/exterior.jpg',
        prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
        referenceUrl: 'https://example.com/reference-house.jpg',
        buildingStyleId: 'modern-farmhouse',
        environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
      },
      {
        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);
  }
}

createExteriorRenovatorTask();

📤 Ответ#

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

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

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

Получает текущий статус и результат ранее созданной задачи по обновлению фасада.

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

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

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

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

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

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

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

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

import java.io.IOException;

public class ExteriorRenovatorResultExample {

    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/exteriorRenovator/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/exteriorRenovator/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 failed")
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/exteriorRenovator/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 failed');
      }
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789);

📤 Ответ#

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg",
      "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
      "refImageUrl": "https://example.com/reference-house.jpg",
      "buildingStyleId": "modern-farmhouse",
      "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/exterior_renovator_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 50,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg"
    },
    "output": null
  }
}

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

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

Поля ответа

ПолеТипОписание
idlongУникальный идентификатор задачи
statusstringТекущий статус задачи (см. Статус задачи)
waitNumberintegerКоличество задач впереди в очереди (0 означает текущую обработку)
percentageintegerПроцент завершения задачи (0–100)
inputobjectИсходные входные параметры задачи
input.imageUrlstringURL исходного изображения фасада
input.promptstringНеобязательные текстовые указания, если предоставлены
input.refImageUrlstringНеобязательный URL изображения-образца, если он предоставлен
input.buildingStyleIdstringНеобязательный идентификатор стиля здания, если предоставлен
input.environmentIdstringНеобязательный идентификатор стиля окружения или сцены, если предоставлен. Может содержать несколько идентификаторов, разделенных запятой
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Ошибка параметров запросаУбедитесь, что параметры запроса правильно отформатированы
5002API_KEY_INVALIDНедействительный или отсутствующий ключ APIУбедитесь, что заголовок APIKEY присутствует и значение корректно
9010SCAN_TEXT_ERRORТекстовый запрос не прошёл проверку контентаУдалите из запроса чувствительный или запрещённый контент
9038PROHIBITED_CONTENTСгенерированное выходное изображение содержит запрещенный контентОтрегулируйте промпт/стиль/входные данные и повторите попытку
9051COINS_NOT_ENOUGHНедостаточно монет / кредитовПополните кредиты на вашем аккаунте и повторите попытку. См. Справочник по списанию кредитов

📄 Для полного списка общих кодов ошибок API см. Справочник кодов ошибок.