Ideal House
ข้ามไปยังเนื้อหา

เอกสาร API เปลี่ยนพื้นผิว#

URLพื้นฐาน: https://api.ideal.house
เวอร์ชัน: v1
อัปเดต: 2026-03-25


📖 ภาพรวม#

API เปลี่ยนพื้นผิว ช่วยให้คุณเปลี่ยนพื้นผิวหรือวัสดุของพื้นที่ที่เลือกในภาพโดยใช้ภาพอ้างอิงสไตล์ คุณต้องส่งภาพต้นฉบับ ภาพ อ้างอิงสไตล์ ที่กำหนดพื้นผิว/วัสดุเป้าหมาย และ ภาพมาสก์ ที่ระบุพื้นที่ที่จะนำพื้นผิวใหม่ไปใช้ AI จะผสมผสานพื้นผิวใหม่เข้ากับ ฉากต้นฉบับอย่างแนบเนียน กระบวนการทำงานเป็นแบบไม่ซิงโครนัสและมีสองขั้นตอน:

  1. สร้างงาน — ส่งภาพต้นฉบับ ภาพสไตล์ มาสก์ และพารามิเตอร์ จากนั้นรับ taskId
  2. ตรวจสอบผลลัพธ์ — ใช้ taskId เพื่อตรวจสอบสถานะงานและดึงภาพผลลัพธ์

🔐 การรับรองความถูกต้อง#

คำขอ API ทั้งหมดต้องได้รับการยืนยันตัวตนโดยใช้ คีย์ API

รวมคีย์ API ของคุณในหัวข้อความขอ:

หัวข้อค่า
APIKEYyour_api_key_here

⚠️ รักษาความปลอดภัยคีย์ API ของคุณ อย่าเปิดเผยในโค้ดฝั่งไคลเอนต์หรือรีโพสิทอรีสาธารณะ


💰 การหักเครดิต#

[!WARNING] 🪙 3 เครดิต จะถูกหักเมื่อสร้างงานสำเร็จ หากงาน ล้มเหลว ในที่สุด เครดิตที่ถูกหักจะ ถูกคืนอัตโนมัติ เข้าบัญชีของคุณ
เครดิตไม่เพียงพอจะคืนรหัสข้อผิดพลาด 9051 📄 ดู อ้างอิงการหักเครดิต

การดำเนินการเครดิตที่ถูกหัก
งานเปลี่ยนพื้นผิว3 เครดิต

🖼️ รูปแบบภาพมาสก์#

ภาพมาสก์กำหนดพื้นที่ที่จะนำการเปลี่ยนพื้นผิวไปใช้

กฎของมาสก์:

สีความหมาย
ดำพื้นที่ที่จะนำ พื้นผิวใหม่ ไปใช้ (พื้นที่ที่จะเปลี่ยน)
ขาวพื้นที่ที่จะ รักษาไว้ (พื้นหลังที่จะไม่เปลี่ยนแปลง)

⚠️ ภาพมาสก์ต้อง มีขนาดเดียวกัน กับภาพต้นฉบับ (imageUrl)

ตัวอย่างมาสก์:

ตัวอย่างมาสก์

พื้นที่สีดำในมาสก์กำหนดตำแหน่งที่จะนำพื้นผิวใหม่ไปใช้ ส่วนพื้นที่สีขาวคือพื้นหลังที่จะ รักษาไว้


📌 เอนด์พอยต์ API#


1. สร้างงานเปลี่ยนพื้นผิว#

สร้างงานเปลี่ยนพื้นผิวด้วย AI ใหม่ และคืน 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 MB โดยมีขนาดภาพตั้งแต่ 128 × 128 px ถึง 6,000 × 6,000 px (รวมขอบเขต) ภาพที่มีขนาดพิกเซลเกินขีดจำกัดสูงสุดจะถูกย่อขนาดลงตามสัดส่วนให้อยู่ภายใน 6,000 × 6,000 px ก่อนการประมวลผล URLs ของภาพต้องเข้าถึงได้โดยตรงโดยเซิร์ฟเวอร์ 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✅ ใช่ID งานที่คืนจากจุดเชื่อมต่อสร้างงาน

📥 ตัวอย่างคำขอ#

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.imageUrlstringภาพต้นฉบับ URL
input.styleImageUrlstringภาพอ้างอิงสไตล์ URL
input.maskUrlstringภาพมาสก์ URL (ถ้าให้ผ่าน 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ข้อผิดพลาดพารามิเตอร์คำขอ — e.g., imageUrl, styleImageUrl, หรือมาสก์ขาดหายตรวจสอบให้แน่ใจว่าฟิลด์ที่จำเป็นทั้งหมดถูกให้มา
5002API_KEY_INVALIDAPI Key ไม่ถูกต้องหรือไม่พบตรวจสอบว่าหัว APIKEY มีอยู่และค่าถูกต้อง
9010SCAN_TEXT_ERRORคำสั่งข้อความไม่ผ่านการตรวจสอบเนื้อหาแก้ไขคำสั่งเพื่อลบเนื้อหาที่อ่อนไหวหรือต้องห้าม
9038PROHIBITED_CONTENTภาพผลลัพธ์ที่สร้างมามีเนื้อหาต้องห้ามปรับคำสั่ง/สไตล์/อินพุตแล้วลองใหม่
9051COINS_NOT_ENOUGHเหรียญ/เครดิตไม่เพียงพอเติมเครดิตในบัญชีของคุณแล้วลองใหม่

📄 สำหรับรายการรหัสข้อผิดพลาด API ทั่วไปทั้งหมด ดู อ้างอิงรหัสข้อผิดพลาด