Ideal House
콘텐츠로 이동

가구 교체 API 문서#

기본 URL: https://api.ideal.house
버전: v1
갱신일: 2026-05-21


📖 개요#

가구 교체 API는 실내 이미지의 가구 스타일을 바꾸거나 가구를 교체합니다. 원본 이미지와 선택적 스타일 지침을 제출한 다음 작업 결과를 비동기로 폴링하세요.

  1. 작업 생성imageUrl과 선택적 지침을 제출하고 taskId를 받습니다.
  2. 결과 폴링taskId로 작업 상태와 출력 이미지를 조회합니다.

🔐 인증#

모든 API 요청은 요청 헤더에 API 키를 포함해야 합니다.

헤더
APIKEYyour_api_key_here

💰 크레딧 차감#

[!WARNING] 🪙 작업이 성공적으로 생성되면 1크레딧이 차감됩니다. 작업이 최종적으로 실패하면 차감된 크레딧은 자동 환불됩니다.
크레딧이 부족하면 오류 코드 9051을 반환합니다. 크레딧 차감 참조를 참고하세요.

작업차감 크레딧
가구 교체 작업1크레딧

🎨 스타일 옵션#

이 API는 API 스타일 설정 엔드포인트가 반환하는 선택적 스타일 매개변수를 지원합니다.

사용 항목:

일반 텍스트
GET /api/v1/style/change_furniture/getStyles
스타일 그룹요청 필드설명
roomTypeindoorTypeId공간 유형 옵션
styleindoorStyleId인테리어 스타일 옵션
elementsindoorElemId공간 요소 옵션입니다. id1,id2처럼 여러 옵션 ID를 쉼표로 구분하여 사용할 수 있습니다.

각 옵션에는 다음이 포함됩니다.

필드설명
name다국어 옵션 이름
id요청 필드에 전달할 값
url옵션 미리보기 이미지

📌 API 엔드포인트#

1. 가구 교체 작업 생성#

엔드포인트

일반 텍스트
POST /api/v1/changeFurniture/generate

요청 헤더

헤더필수 여부설명
APIKEY✅ 예API 인증 키
Content-Type✅ 예application/json

요청 본문

필드유형필수 여부설명
imageUrlstring✅ 예원본 실내 이미지 URL
promptstring❌ 선택원하는 결과에 대한 텍스트 지침
indoorTypeIdstring❌ 선택roomType 스타일 옵션의 공간 유형 ID
indoorStyleIdstring❌ 선택style 스타일 옵션의 인테리어 스타일 ID
indoorElemIdstring❌ 선택elements 스타일 옵션의 공간 요소 ID입니다. id1,id2처럼 여러 ID를 쉼표로 구분하여 사용할 수 있습니다.

imageUrl만 필수입니다. 나머지 필드는 모두 선택 사항입니다.

🖼️ 이미지 요건: JPG/JPEG, PNG 또는 WebP를 사용하세요. 각 이미지는 20 MB 이하여야 하며 크기는 128 × 128 px부터 6,000 × 6,000 px까지 허용됩니다(경계값 포함). 최대 픽셀 크기를 초과하는 이미지는 처리 전에 6,000 × 6,000 px 안에 들어오도록 비율을 유지하여 자동 축소됩니다. 이미지 URL은 API 서버에서 직접 접근할 수 있어야 합니다.

📥 요청 예제#

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/changeFurniture/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "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 ChangeFurnitureApiExample {

    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/living-room.jpg",
                    "prompt": "replace the sofa with a modern warm neutral sofa",
                    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
                    "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/changeFurniture/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/living-room.jpg",
    "prompt": "replace the sofa with a modern warm neutral sofa",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Modern Country",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/changeFurniture/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 createChangeFurnitureTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/changeFurniture/generate`,
      {
        imageUrl: 'https://example.com/living-room.jpg',
        prompt: 'replace the sofa with a modern warm neutral sofa',
        indoorTypeId: 'Interior Design_Interior Scene_Living Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Modern Country',
        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);
  }
}

createChangeFurnitureTask();

📤 응답#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
필드유형설명
codeinteger0은 성공을 의미함
messagestring응답 메시지
datalong결과 폴링용 작업 ID

2. 작업 결과 조회#

엔드포인트

일반 텍스트
GET /api/v1/changeFurniture/result

요청 헤더

헤더필수 여부설명
APIKEY✅ 예API 인증 키

쿼리 매개변수

매개변수유형필수 여부설명
taskIdlong✅ 예생성 엔드포인트가 반환한 작업 ID

📥 요청 예제#

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

import java.io.IOException;

public class ChangeFurnitureResultExample {

    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/changeFurniture/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/changeFurniture/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 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 pollChangeFurnitureResult(taskId) {
  const headers = { APIKEY: API_KEY };

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

pollChangeFurnitureResult(1234567890123456789n);

📤 응답 예제#

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

응답 (작업 처리 중 / 대기열에 있음)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 45,
    "input": {
      "imageUrl": "https://example.com/living-room.jpg",
      "prompt": "replace the sofa with a modern warm neutral sofa"
    },
    "output": null
  }
}

응답 (작업 실패)

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

📊 작업 상태#

상태설명
Unprocessed작업이 생성되어 대기열에서 기다리는 중
Processing작업이 현재 실행 중
Success작업이 성공적으로 완료됨
Failed작업이 실패하여 출력이 생성되지 않음

3-5초마다 폴링하세요. API 작업 제한을 참고하세요.


❌ 오류 응답#

코드이름설명
1011PARAM_ERROR요청 매개변수 오류
5002API_KEY_INVALID유효하지 않거나 누락된 API 키
9010SCAN_TEXT_ERROR프롬프트가 콘텐츠 검토를 통과하지 못함
9038PROHIBITED_CONTENT생성된 이미지에 금지된 콘텐츠가 포함됨
9051COINS_NOT_ENOUGH크레딧 부족

전체 공통 오류 정의는 오류 코드 참조를 참고하세요.