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

เอกสาร API ปรับปรุงภายนอก#

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


📖 ภาพรวม#

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

เวิร์กโฟลว์เป็นแบบอสังโครนัสและประกอบด้วยสองขั้นตอน:

  1. สร้างงาน — ส่งภาพภายนอกของคุณและคำแนะนำตัวเลือก จากนั้นรับ taskId
  2. ตรวจสอบผลลัพธ์ — ใช้ taskId เพื่อสอบถามสถานะงานและดึงภาพที่สร้าง

🔐 การยืนยันตัวตน#

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

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

หัวข้อค่า
APIKEYyour_api_key_here

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


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

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

การดำเนินการเครดิตที่ถูกหัก
งานปรับปรุงภายนอกเครดิต 1

สำหรับกฎเครดิตโดยละเอียด ดู อ้างอิงการหักเครดิต


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


1. สร้างงานปรับปรุงภายนอก#

สร้างงานปรับปรุงภายนอกใหม่และคืน taskId ที่ไม่ซ้ำสำหรับการตรวจสอบสถานะ

เอนด์พอยต์

ข้อความธรรมดา
POST /api/v1/exteriorRenovator/generate

หัวข้อความขอ

หัวข้อจำเป็นคำอธิบาย
APIKEY✅ ใช่คีย์การยืนยันตัวตน API ของคุณ
Content-Type✅ ใช่application/json

เนื้อหาข้อความขอ

ฟิลด์ประเภทจำเป็นคำอธิบาย
imageUrlstring✅ ใช่URL ของภาพภายนอกต้นฉบับที่จะปรับปรุง
promptstring❌ ไม่บังคับคำแนะนำข้อความแบบไม่บังคับสำหรับผลลัพธ์การปรับปรุง
referenceUrlstring❌ ไม่บังคับURL ของภาพอ้างอิงแบบไม่บังคับเพื่อแนะนำสไตล์ภาพ
buildingStyleIdstring❌ ไม่บังคับID สไตล์อาคารแบบไม่บังคับ
environmentIdstring❌ ไม่บังคับID สไตล์สภาพแวดล้อมหรือฉากแบบไม่บังคับ รองรับหลาย ID ที่เชื่อมด้วยเครื่องหมายจุลภาค เช่น id1,id2

⚠️ เฉพาะ imageUrl เท่านั้นที่จำเป็น ฟิลด์เนื้อหาข้อความขออื่นทั้งหมดเป็นตัวเลือก

🖼️ ข้อกำหนดของภาพ: ภาพต้นฉบับและภาพอ้างอิงทั้งหมดต้องเป็น JPG/JPEG, PNG หรือ WebP แต่ละภาพต้องไม่เกิน 20 MB โดยมีขนาดตั้งแต่ 128 × 128 px ถึง 6,000 × 6,000 px (รวมขอบเขต) ภาพที่เกินขนาดพิกเซลสูงสุดจะถูกย่อสัดส่วนอัตโนมัติให้พอดีกับ 6,000 × 6,000 px ก่อนการประมวลผล URLs ของภาพต้องเข้าถึงได้โดยตรงโดยเซิร์ฟเวอร์ API


🎨 ตัวเลือกสไตล์#

buildingStyleId และ environmentId สามารถเลือกได้จากเอนด์พอยต์ API การตั้งค่าสไตล์

การใช้งาน:

ข้อความธรรมดา
GET /api/v1/style/exterior_renovator/getStyles
กลุ่มสไตล์ฟิลด์คำขอคำอธิบาย
buildingStylebuildingStyleIdตัวเลือกสไตล์อาคาร
environmentenvironmentIdตัวเลือกสภาพแวดล้อมหรือฉาก รองรับหลายตัวเลือก ID ที่เชื่อมด้วยเครื่องหมายจุลภาค เช่น id1,id2

แต่ละตัวเลือกประกอบด้วย name, id และ url ส่ง id ของตัวเลือกไปยังฟิลด์คำขอที่สอดคล้องกัน


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

cURL
bash
# Minimal request
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg"
  }'

# Request with optional guidance
curl -X POST "https://api.ideal.house/api/v1/exteriorRenovator/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class ExteriorRenovatorApiExample {

    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/exterior.jpg",
                    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
                    "referenceUrl": "https://example.com/reference-house.jpg",
                    "buildingStyleId": "modern-farmhouse",
                    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/exteriorRenovator/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/exterior.jpg",
    "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
    "referenceUrl": "https://example.com/reference-house.jpg",
    "buildingStyleId": "modern-farmhouse",
    "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
}

response = requests.post(
    f"{BASE_URL}/api/v1/exteriorRenovator/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 createExteriorRenovatorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/exteriorRenovator/generate`,
      {
        imageUrl: 'https://example.com/exterior.jpg',
        prompt: 'Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping',
        referenceUrl: 'https://example.com/reference-house.jpg',
        buildingStyleId: 'modern-farmhouse',
        environmentId: 'Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day'
      },
      {
        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);
  }
}

createExteriorRenovatorTask();

📤 คำตอบ#

คำตอบสำเร็จ

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
ฟิลด์ประเภทคำอธิบาย
codeinteger0 บ่งชี้ว่าสำเร็จ
messagestringข้อความตอบกลับ
datalongID งานเฉพาะสำหรับการตรวจสอบสถานะผลลัพธ์

2. รับผลลัพธ์งาน#

ดึงสถานะปัจจุบันและผลลัพธ์ของงานปรับปรุงภายนอกที่สร้างไว้ก่อนหน้า

เอนด์พอยต์

ข้อความธรรมดา
GET /api/v1/exteriorRenovator/result

หัวข้อความขอ

หัวข้อจำเป็นคำอธิบาย
APIKEY✅ ใช่คีย์การยืนยันตัวตน API ของคุณ

พารามิเตอร์ควอรี

พารามิเตอร์ประเภทจำเป็นคำอธิบาย
taskIdlong✅ ใช่ID งานที่ส่งกลับจากเอนด์พอยต์สร้างงาน

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

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

import java.io.IOException;

public class ExteriorRenovatorResultExample {

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

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789);

📤 คำตอบ#

คำตอบสำเร็จ (งานเสร็จสมบูรณ์)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/exterior.jpg",
      "prompt": "Modern farmhouse exterior with warm wood accents, black window frames, and clean landscaping",
      "refImageUrl": "https://example.com/reference-house.jpg",
      "buildingStyleId": "modern-farmhouse",
      "environmentId": "Architecture_Enviroment_Time_Night,Architecture_Enviroment_Time_Day"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/exterior_renovator_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/exterior.jpg"
    },
    "output": null
  }
}

คำตอบ (งานล้มเหลว)

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

ฟิลด์คำตอบ

ฟิลด์ประเภทคำอธิบาย
idlongตัวระบุเฉพาะของงาน
statusstringสถานะงานปัจจุบัน (ดู สถานะงาน)
waitNumberintegerจำนวนงานที่อยู่ข้างหน้าในคิว (0 หมายถึงกำลังดำเนินการอยู่)
percentageintegerร้อยละความคืบหน้าของงาน (0–100)
inputobjectพารามิเตอร์อินพุตต้นฉบับของงาน
input.imageUrlstringURL ของภาพภายนอกต้นฉบับ
input.promptstringคำแนะนำข้อความแบบไม่บังคับ หากมีการระบุ
input.refImageUrlstringURL ของภาพอ้างอิงแบบไม่บังคับ หากมีการระบุ
input.buildingStyleIdstringID สไตล์อาคารแบบไม่บังคับ หากมีการระบุ
input.environmentIdstringID สไตล์สภาพแวดล้อมหรือฉากแบบไม่บังคับ หากมีการระบุ อาจมีหลาย ID ที่เชื่อมด้วยเครื่องหมายจุลภาค
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ข้อผิดพลาดพารามิเตอร์คำขอตรวจสอบให้แน่ใจว่าพารามิเตอร์คำขอมีรูปแบบถูกต้อง
5002API_KEY_INVALIDคีย์ API ไม่ถูกต้องหรือไม่พบตรวจสอบว่าเฮดเดอร์ APIKEY มีอยู่และค่าถูกต้อง
9010SCAN_TEXT_ERRORพรอมต์ข้อความไม่ผ่านการตรวจสอบเนื้อหาแก้ไขพรอมต์เพื่อลบเนื้อหาอ่อนไหวหรือต้องห้าม
9038PROHIBITED_CONTENTภาพผลลัพธ์ที่สร้างมามีเนื้อหาต้องห้ามปรับพรอมต์/สไตล์/อินพุตแล้วลองใหม่
9051COINS_NOT_ENOUGHเหรียญ/เครดิตไม่เพียงพอเติมเครดิตในบัญชีของคุณแล้วลองใหม่ ดู อ้างอิงการหักเครดิต

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