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

Документация API замены текстур#

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


📖 Обзор#

API замены текстур позволяет заменять текстуру или материал выбранной области на изображении с помощью референсного изображения стиля. Вы предоставляете исходное изображение, референсное изображение стиля, определяющее целевую текстуру/материал, и изображение-маску, указывающее область для применения новой текстуры. ИИ естественно объединяет новую текстуру с исходной сценой. Рабочий процесс асинхронный и включает два шага:

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

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

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

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

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

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


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

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

ОперацияСписанные кредиты
Задача замены текстур3 кредита

🖼️ Формат маски#

Маска определяет область, в которой будет применена замена текстуры.

Правила маски:

ЦветЗначение
ЧерныйОбласть для применения новой текстуры (регион для замены)
БелыйОбласть для сохранения (фон, который остается неизменным)

⚠️ Маска должна иметь те же размеры, что и исходное изображение (imageUrl).

Пример маски:

Пример маски

Черная область в маске определяет, где будет применена новая текстура; белая область — это фон, который сохраняется.


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


1. Создание задачи замены текстур#

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

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

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

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

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

Тело запроса

ПолеТипОбязательностьОписание
imageUrlstring✅ ДаURL исходного изображения (комната/сцена, к которой применяется текстура)
styleImageUrlstring✅ ДаURL референсного изображения стиля, определяющего целевую текстуру или материал
maskUrlstring⚠️ Либо maskUrl, либо maskBase64URL маски. К чёрным областям применяется новая текстура, а белые области сохраняются
maskBase64string⚠️ Либо maskUrl, либо maskBase64Маска в кодировке Base64; рекомендуется формат PNG. Используется, когда невозможно предоставить URL размещённого изображения
promptstring❌ НеобязательноДополнительный текстовый промпт для дальнейшего управления генерацией текстуры

⚠️ Необходимо предоставить хотя бы один из maskUrl или maskBase64. Если указаны оба, приоритет отдается maskUrl.

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


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

cURL
bash
# Using maskUrl
curl -X POST "https://api.ideal.house/api/v1/textureReplacer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/marble-texture.jpg",
    "maskUrl": "https://example.com/mask.png"
  }'

# Using maskBase64 with optional prompt
curl -X POST "https://api.ideal.house/api/v1/textureReplacer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/wood-texture.jpg",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "prompt": "natural oak wood grain texture"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class TextureReplacerApiExample {

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

        // Option 1: Use maskUrl
        String requestBody = """
                {
                    "imageUrl": "https://example.com/room.jpg",
                    "styleImageUrl": "https://example.com/marble-texture.jpg",
                    "maskUrl": "https://example.com/mask.png"
                }
                """;

        // Option 2: Use maskBase64 (encode local mask file)
        // byte[] maskBytes = Files.readAllBytes(Path.of("/path/to/mask.png"));
        // String maskBase64 = Base64.getEncoder().encodeToString(maskBytes);
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "styleImageUrl": "https://example.com/marble-texture.jpg",
        //         "maskBase64": "%s",
        //         "prompt": "natural oak wood grain texture"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/textureReplacer/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
import base64

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Option 1: Use maskUrl
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "styleImageUrl": "https://example.com/marble-texture.jpg",
    "maskUrl": "https://example.com/mask.png"
}

# Option 2: Use maskBase64 with optional prompt
# with open("/path/to/mask.png", "rb") as f:
#     mask_base64 = base64.b64encode(f.read()).decode("utf-8")
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "styleImageUrl": "https://example.com/wood-texture.jpg",
#     "maskBase64": mask_base64,
#     "prompt": "natural oak wood grain texture"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/textureReplacer/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 fs = require('fs');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createTextureReplacerTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      styleImageUrl: 'https://example.com/marble-texture.jpg',
      maskUrl: 'https://example.com/mask.png'
    };

    // Option 2: Use maskBase64 with optional prompt
    // const maskBuffer = fs.readFileSync('/path/to/mask.png');
    // const maskBase64 = maskBuffer.toString('base64');
    // const payload = {
    //   imageUrl: 'https://example.com/room.jpg',
    //   styleImageUrl: 'https://example.com/wood-texture.jpg',
    //   maskBase64: maskBase64,
    //   prompt: 'natural oak wood grain texture'
    // };

    const response = await axios.post(
      `${BASE_URL}/api/v1/textureReplacer/generate`,
      payload,
      {
        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);
  }
}

createTextureReplacerTask();

📤 Ответ#

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

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

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

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

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

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

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

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

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

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

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

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

import java.io.IOException;

public class TextureReplacerResultExample {

    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/textureReplacer/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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/textureReplacer/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)  # Poll every 3 seconds

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/textureReplacer/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;
    }

    // Wait 3 seconds before next poll
    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/room.jpg",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png",
      "prompt": "natural marble texture with grey veining"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/texture_replacer_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/room.jpg",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png"
    },
    "output": null
  }
}

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "styleImageUrl": "https://example.com/marble-texture.jpg",
      "maskUrl": "https://example.com/mask.png"
    },
    "output": null
  }
}

Поля ответа

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

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