Object Remover API Documentation

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-03-06

📖 Overview

The Object Remover API allows you to remove unwanted objects or furniture from interior images using AI. It supports two modes:

single_furniture — Remove a specific piece of furniture by providing a mask image that marks the target area. The AI intelligently fills the removed area to produce a clean, natural-looking result.
whole_house — Automatically remove all furniture from the entire room without requiring a mask.

The workflow is asynchronous and involves two steps:

Create a task — Submit your source image, mask, and parameters, then receive a taskId.
Poll for results — Use the taskId to query task status and retrieve the result image.

🔐 Authentication

All API requests must be authenticated using an API Key.

Include your API Key in the request header:

Header	Value
`APIKEY`	`your_api_key_here`

⚠️ Keep your API Key secure. Do not expose it in client-side code or public repositories.

💰 Credits Deduction

[!WARNING] 🪙 Each task deducts 1 credit from your account upon successful task creation. If the task ultimately fails, the deducted credits will be automatically refunded to your account.
Insufficient credits will return error code 9051. 📄 See Credits Deduction Reference.

🖼️ Mask Image Format

The mask image defines the area to be removed from the source image.

Mask Rules:

Color	Meaning
⬛ Black	Area to be removed (object / region to erase)
⬜ White	Area to be preserved (background to keep)

⚠️ The mask image must match the same dimensions as the source image (imageUrl).

Mask Example:

Mask Example

The black area in the mask marks the furniture to be removed; the white area is the background to preserve.

📌 API Endpoints

1. Create Object Remover Task

Creates a new AI object removal task and returns a unique taskId for polling.

Endpoint

POST /api/v1/objectRemover/generate

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key
`Content-Type`	✅ Yes	`application/json`

Request Body

Field	Type	Required	Description
`imageUrl`	`string`	✅ Yes	URL of the source image
`emptyType`	`string`	✅ Yes	Removal mode. Enum: `whole_house`, `single_furniture`. Controls how the AI fills the removed area
`maskUrl`	`string`	⚠️ Required when `emptyType=single_furniture`	URL of the mask image. Black areas will be removed; white areas will be preserved. Only takes effect in `single_furniture` mode
`maskBase64`	`string`	⚠️ Required when `emptyType=single_furniture`	Base64-encoded mask image (PNG format recommended). Alternative to `maskUrl`. Only takes effect in `single_furniture` mode

⚠️ Mask requirement by mode:

single_furniture — At least one of maskUrl or maskBase64 must be provided. If both are given, maskUrl takes precedence.

whole_house — Mask fields are ignored. The AI removes all furniture from the entire room automatically.

Empty Type Options

Value	Mask Required	Description
`single_furniture`	✅ Yes	Removes a specific piece of furniture defined by the mask and fills the area naturally
`whole_house`	❌ No	Removes all furniture from the entire room automatically — no mask needed

📥 Request Examples

cURL

# single_furniture mode — mask required (using maskUrl)
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "single_furniture",
    "maskUrl": "https://example.com/mask.png"
  }'

# single_furniture mode — mask required (using maskBase64)
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "single_furniture",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }'

# whole_house mode — no mask needed
curl -X POST "https://api.ideal.house/api/v1/objectRemover/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "emptyType": "whole_house"
  }'

Java (OkHttp)

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

public class ObjectRemoverApiExample {

    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",
                "maskUrl": "https://example.com/mask.png",
                "emptyType": "single_furniture"
            }
            """;

        // 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",
        //         "maskBase64": "%s",
        //         "emptyType": "single_furniture"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/objectRemover/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
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",
    "maskUrl": "https://example.com/mask.png",
    "emptyType": "single_furniture"
}

# Option 2: Use maskBase64 (encode local mask file)
# 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",
#     "maskBase64": mask_base64,
#     "emptyType": "single_furniture"
# }

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

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

async function createObjectRemoverTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      maskUrl: 'https://example.com/mask.png',
      emptyType: 'single_furniture'
    };

    // Option 2: Use maskBase64 (encode local mask file)
    // const maskBuffer = fs.readFileSync('/path/to/mask.png');
    // const maskBase64 = maskBuffer.toString('base64');
    // const payload = {
    //   imageUrl: 'https://example.com/room.jpg',
    //   maskBase64: maskBase64,
    //   emptyType: 'single_furniture'
    // };

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

createObjectRemoverTask();

📤 Response

Success Response

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

Field	Type	Description
`code`	`integer`	`0` indicates success
`message`	`string`	Response message
`data`	`long`	The unique task ID for polling results

2. Get Task Result

Retrieves the current status and output of a previously created object removal task.

Endpoint

GET /api/v1/objectRemover/result

Request Headers

Header	Required	Description
`APIKEY`	✅ Yes	Your API authentication key

Query Parameters

Parameter	Type	Required	Description
`taskId`	`long`	✅ Yes	The task ID returned from the create task endpoint

📥 Request Examples

cURL

curl -X GET "https://api.ideal.house/api/v1/objectRemover/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class ObjectRemoverResultExample {

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

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/objectRemover/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 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 pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

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

    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

📤 Response

Success Response (Task Completed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "maskUrl": "https://example.com/mask.png",
      "emptyType": "single_furniture"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/object_remover_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 50,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "maskUrl": "https://example.com/mask.png",
      "emptyType": "single_furniture"
    },
    "output": null
  }
}

Response (Task Failed)

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

Response Fields

Field	Type	Description
`id`	`long`	Task unique identifier
`status`	`string`	Current task status (see Task Status)
`waitNumber`	`integer`	Number of tasks ahead in the queue (`0` means currently processing)
`percentage`	`integer`	Task completion percentage (`0–100`)
`input`	`object`	The original input parameters of the task
`input.imageUrl`	`string`	Source image URL
`input.maskUrl`	`string`	Mask image URL (if provided via `maskUrl`)
`input.emptyType`	`string`	Removal mode used (`single_furniture` or `whole_house`)
`output`	`object`	Generation result (only available when `status` is `Success`)
`output.resultUrl`	`string`	URL to the object-removed result image
`output.width`	`integer`	Output width in pixels
`output.height`	`integer`	Output height in pixels

📊 Task Status

Status	Description
`Unprocessed`	Task has been created but not yet started
`Processing`	Task is currently being processed
`Success`	Task completed successfully — output is available
`Failed`	Task failed due to an error

💡 Polling Recommendation: Poll the result endpoint every 3–5 seconds. Avoid polling too frequently to prevent rate limiting.

❌ Error Responses

All error responses share the same JSON structure:

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

Error Code Reference

Code	Name	Description	Suggested Action
`1001`	`FAILED`	Request failed (generic error)	Check the `message` field for specific error details
`1003`	`INTERNAL_ERROR`	Internal server error	Retry after a short delay; contact support if it persists
`1011`	`PARAM_ERROR`	Request parameter error — e.g., both `maskUrl` and `maskBase64` missing	Ensure at least one mask field is provided
`5002`	`API_KEY_INVALID`	Invalid or missing API Key	Ensure the `APIKEY` header is present and the value is correct
`9038`	`PROHIBITED_CONTENT`	Generated output image contains prohibited content	Adjust prompt/style/inputs and retry
`9051`	`COINS_NOT_ENOUGH`	Insufficient coins / credits	Top up your account credits and retry

📄 For the complete list of common API error codes, refer to the Error Code Reference.

🔄 Recommended Integration Flow

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Prepare:                                               │
│    - Source image URL (imageUrl) [required]             │
│    - emptyType [required]:                              │
│      → "single_furniture": mask required                │
│         (maskUrl or maskBase64, black=remove)           │
│      → "whole_house": no mask needed                    │
│                                                         │
│  1. POST /api/v1/objectRemover/generate                 │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 3–5 seconds                                    │
│                                                         │
│  3. GET /api/v1/objectRemover/result?taskId={taskId}    │
│     → Check status field                               │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Unprocessed" or "Processing"       │   │
│     │   → waitNumber: position in queue             │   │
│     │   → percentage: current progress              │   │
│     │   → Repeat step 2 & 3                         │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Success"                           │   │
│     │   → output.resultUrl: object-removed image    │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed"                           │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘