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

يحتوي كل خيار على:

الحقلالوصف
nameاسم الخيار متعدد اللغات
idالقيمة المراد تمريرها في حقل الطلب
urlصورة معاينة للخيار

📌 API نقاط النهاية#

1. إنشاء مهمة تغيير الأثاث#

نقطة النهاية

نص عادي
POST /api/v1/changeFurniture/generate

رؤوس الطلب

الرأسمطلوبالوصف
APIKEY✅ نعممفتاح مصادقة API الخاص بك
Content-Type✅ نعمapplication/json

جسم الطلب

الحقلالنوعمطلوبالوصف
imageUrlstring✅ نعمURL للصورة الداخلية المصدر
promptstring❌ اختياريتوجيه نصي للنتيجة المطلوبة
indoorTypeIdstring❌ اختياريمعرف نوع الغرفة من خيارات roomType
indoorStyleIdstring❌ اختياريمعرف النمط الداخلي من خيارات style
indoorElemIdstring❌ اختياريمعرف عنصر الغرفة من خيارات elements. يدعم عدة معرفات مفصولة بفاصلة، على سبيل المثال id1,id2

فقط imageUrl مطلوب. جميع الحقول الأخرى اختيارية.

🖼️ متطلبات الصور: استخدم JPG/JPEG، أو PNG، أو WebP. يجب ألا يتجاوز حجم كل صورة 20 ميجابايت، مع أبعاد تتراوح من 128 × 128 بكسل إلى 6,000 × 6,000 بكسل (شامل). تتم عملية تصغير الصور التي تتجاوز الأبعاد البكسلية القصوى تلقائيًا بشكل متناسب لتناسب 6,000 × 6,000 بكسل قبل المعالجة. يجب أن تكون 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
}
الحقلالنوعالوصف
codeintegerيشير 0 إلى النجاح
messagestringرسالة الاستجابة
datalongمعرف المهمة للاستعلام الدوري عن النتائج

2. الحصول على نتيجة المهمة#

نقطة النهاية

نص عادي
GET /api/v1/changeFurniture/result

رؤوس الطلب

الرأسمطلوبالوصف
APIKEY✅ نعممفتاح مصادقة API الخاص بك

معاملات الاستعلام

المعاملالنوعمطلوبالوصف
taskIdlong✅ نعممعرف المهمة المُرجع بواسطة نقطة نهاية الإنشاء

📥 أمثلة الطلب#

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رصيد غير كافٍ

للتعريفات الكاملة للأخطاء الشائعة، انظر مرجع رموز الأخطاء.