Smart Replace API Documentation

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

📖 Overview

The Smart Replace API allows you to intelligently replace a selected area in an image with AI-generated content based on your text prompt. You provide a source image, a mask image that defines the area to be replaced, and a text prompt describing what should fill that area. The AI will seamlessly blend the generated content into the original image. The workflow is asynchronous and involves two steps:

Create a task — Submit your image, mask, and prompt, 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 replaced in the source image.

Mask Rules:

Color	Meaning
⬛ Black	Area to be replaced (region where new content will be generated)
⬜ White	Area to be preserved (background to keep unchanged)

⚠️ 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 region to be replaced by AI; the white area is the background to preserve.

📌 API Endpoints

1. Create Smart Replace Task

Creates a new AI smart replace task and returns a unique taskId for polling.

Endpoint

POST /api/v1/smartReplace/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
`prompt`	`string`	✅ Yes	Text prompt describing the content to generate in the masked area (e.g., `"a modern armchair"`, `"marble flooring"`)
`maskUrl`	`string`	⚠️ Either `maskUrl` or `maskBase64`	URL of the mask image. Black areas will be replaced; white areas will be preserved
`maskBase64`	`string`	⚠️ Either `maskUrl` or `maskBase64`	Base64-encoded mask image (PNG format recommended). Used when you cannot provide a hosted URL

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

📥 Request Examples

cURL

# Using maskUrl
curl -X POST "https://api.ideal.house/api/v1/smartReplace/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "a modern velvet sofa in dark blue",
    "maskUrl": "https://example.com/mask.png"
  }'

# Using maskBase64
curl -X POST "https://api.ideal.house/api/v1/smartReplace/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "prompt": "a modern velvet sofa in dark blue",
    "maskBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }'

Java (OkHttp)

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

public class SmartReplaceApiExample {

    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",
                "prompt": "a modern velvet sofa in dark blue",
                "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",
        //         "prompt": "a modern velvet sofa in dark blue",
        //         "maskBase64": "%s"
        //     }
        //     """.formatted(maskBase64);

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/smartReplace/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",
    "prompt": "a modern velvet sofa in dark blue",
    "maskUrl": "https://example.com/mask.png"
}

# 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",
#     "prompt": "a modern velvet sofa in dark blue",
#     "maskBase64": mask_base64
# }

response = requests.post(
    f"{BASE_URL}/api/v1/smartReplace/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 createSmartReplaceTask() {
  try {
    // Option 1: Use maskUrl
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      prompt: 'a modern velvet sofa in dark blue',
      maskUrl: 'https://example.com/mask.png'
    };

    // 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',
    //   prompt: 'a modern velvet sofa in dark blue',
    //   maskBase64: maskBase64
    // };

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

createSmartReplaceTask();

📤 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 smart replace task.

Endpoint

GET /api/v1/smartReplace/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/smartReplace/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

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

public class SmartReplaceResultExample {

    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/smartReplace/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/smartReplace/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/smartReplace/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",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/smart_replace_result.jpg",
      "width": 1024,
      "height": 1024
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "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",
      "prompt": "a modern velvet sofa in dark blue",
      "maskUrl": "https://example.com/mask.png"
    },
    "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.prompt`	`string`	Text prompt describing the replacement content
`input.maskUrl`	`string`	Mask image URL (if provided via `maskUrl`)
`output`	`object`	Generation result (only available when `status` is `Success`)
`output.resultUrl`	`string`	URL to the smart-replaced 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

Poll every 3-5 seconds. See API Task Limit.

❌ 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., `prompt` or mask missing	Ensure both `prompt` and at least one mask field are provided
`5002`	`API_KEY_INVALID`	Invalid or missing API Key	Ensure the `APIKEY` header is present and the value is correct
`9010`	`SCAN_TEXT_ERROR`	Text prompt failed content review	Modify the prompt to remove any sensitive or prohibited content
`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.