Ideal House
تخطّي إلى المحتوى

توثيق API التأثيث الافتراضي#

URL الأساسي: https://api.ideal.house
الإصدار: v1
آخر تحديث: 2026-04-13


📖 نظرة عامة#

يُتيح لك API للتدبير الافتراضي إعادة تصميم غرفة فارغة أو جزئية التجهيز باستخدام الذكاء الاصطناعي.
تقدّم URL صورة الغرفة ومطالبة نصية اختيارية، ثم تسترجع النتيجة المُولَّدة بشكل غير متزامن.

  1. إنشاء مهمة — أرسل imageUrl، وأرسل prompt اختياريًا، ثم احصل على taskId.
  2. الاستعلام عن النتائج — استخدم taskId للاستعلام عن حالة المهمة والحصول على صورة الإخراج.

🔐 المصادقة#

يجب مصادقة جميع طلبات API باستخدام مفتاح API.

تضمّن مفتاح API في رأس الطلب:

الرأسالقيمة
APIKEYyour_api_key_here

⚠️ احفظ مفتاح API بأمان. لا تعرضه في كود الواجهة الأمامية أو المستودعات العامة.


💰 خصم الرصيد#

[!WARNING] 🪙 يُخصم 1 رصيد عند إنشاء المهمة بنجاح.
إذا فشلت المهمة في النهاية، يُعاد الرصيد المخصوم تلقائيًا.
سيعيد نقص الرصيد رمز الخطأ 9051. 📄 اطّلِع على مرجع خصم الرصيد.

العمليةالرصيد المخصوم
مهمة التأثيث الافتراضي1 رصيد

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


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

يُنشئ مهمة تأثيث افتراضي جديدة ويعيد taskId فريدًا للاستعلام.

نقطة النهاية

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

رؤوس الطلب

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

جسم الطلب

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

🖼️ متطلبات الصور: استخدم JPG/JPEG أو PNG أو WebP. ألا يتجاوز حجم كل صورة 20 ميجابايت، وأن تكون الأبعاد من 128 × 128 بكسل إلى 6,000 × 6,000 بكسل (شاملًا). يتم تصغير الصور التي تتجاوز أبعاد البكسل القصوى تلقائيًا بشكل متناسب لتناسب 6,000 × 6,000 بكسل قبل المعالجة. يجب أن تكون URL الصورة مباشرةً قابلة للوصول من قبل خوادم API.


🎨 خيارات النمط#

يمكن اختيار indoorTypeId وindoorStyleId وindoorElemId من نقطة نهاية إعدادات نمط API.

الاستخدام:

نص عادي
GET /api/v1/style/virtual_staging/getStyles
مجموعة النمطحقل الطلبالوصف
roomTypeindoorTypeIdخيار نوع الغرفة
styleindoorStyleIdخيار نمط الديكور الداخلي
elementsindoorElemIdخيار عنصر الغرفة. يدعم عدة معرفات خيارات مفصولة بفاصلة، مثل id1,id2

يحتوي كل خيار على name وid وurl. مرر id الخيار إلى حقل الطلب المقابل.


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

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/virtualStaging/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/empty-living-room.jpg",
    "prompt": "Warm and modern living room styling",
    "indoorTypeId": "Interior Design_Interior Scene_Living Room",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Farmhouse",
    "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 VirtualStagingApiExample {

    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/empty-bedroom.jpg",
                    "prompt": "Cozy contemporary bedroom",
                    "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
                    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm",
                    "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/virtualStaging/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/empty-home-office.jpg",
    "prompt": "Minimal modern home office",
    "indoorTypeId": "Interior Design_Interior Scene_Home Office",
    "indoorStyleId": "Interior_Interior Style_Popular_Vs_Modern Minimal",
    "indoorElemId": "Interior Design_Scene Elements_Living Room_Shelving,Interior Design_Scene Elements_Living Room_Coffee Table"
}

response = requests.post(
    f"{BASE_URL}/api/v1/virtualStaging/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 createVirtualStagingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/virtualStaging/generate`,
      {
        imageUrl: 'https://example.com/empty-dining-room.jpg',
        prompt: 'Modern luxury dining room',
        indoorTypeId: 'Interior Design_Interior Scene_Dining Room',
        indoorStyleId: 'Interior_Interior Style_Popular_Vs_Modern Luxury',
        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);
  }
}

createVirtualStagingTask();

📤 الاستجابة#

استجابة النجاح

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
الحقلالنوعالوصف
codeintegerيشير 0 إلى النجاح
messagestringرسالة الاستجابة
datalongمعرف المهمة الفريد للاستعلام عن النتائج

2. استرداد نتيجة المهمة#

يسترجع الحالة الحالية وإخراج مهمة تأثيث افتراضي تم إنشاؤها سابقًا.

نقطة النهاية

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

رؤوس الطلب

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

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

المعاملالنوعمطلوبالوصف
taskIdlong✅ نعممعرف المهمة الذي تم إعادته من نقطة النهاية لإنشاء المهمة

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

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

import java.io.IOException;

public class VirtualStagingResultExample {

    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/virtualStaging/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/virtualStaging/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":
    output = result["output"]
    print("Result URL:", output["resultUrl"])
    print("Size:", output["width"], "x", output["height"])
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 pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

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

pollResult(1234567890123456789n);

📤 الاستجابة#

استجابة النجاح (اكتمال المهمة)

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

استجابة (معالجة المهمة / في الطابور)

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 1,
    "percentage": 46,
    "input": {
      "imageUrl": "https://example.com/empty-room.jpg",
      "prompt": "coastal bedroom with soft light and natural textures",
      "indoorTypeId": "Interior Design_Interior Scene_Bed Room",
      "indoorStyleId": "Interior_Interior Style_Popular_Vs_Contemporary Warm"
    },
    "output": null
  }
}

استجابة (فشل المهمة)

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

حقول الاستجابة

الحقلالنوعالوصف
idlongمعرّف المهمة الفريد
statusstringحالة المهمة الحالية (اطّلِع على حالة المهمة)
waitNumberintegerعدد المهام التي تسبق هذه المهمة في الطابور (يعني 0 المعالجة حاليًا)
percentageintegerنسبة اكتمال المهمة (0-100)
errorReasonstringسبب الفشل عندما يكون status هو Failed
inputobjectمعاملات الإدخال الأصلية التي تم إرسالها لهذه المهمة
input.imageUrlstringURL صورة المصدر للغرفة
input.promptstringمطالبة المستخدم (إذا تم تقديمها)
input.indoorTypeIdstringنوع الغرفة المُعدّ مسبقًا المستخدم (إذا تم تقديمه)
input.indoorStyleIdstringنمط الديكور الداخلي المُعدّ مسبقًا المستخدم (إذا تم تقديمه)
input.indoorElemIdstringعنصر الغرفة المُعدّ مسبقًا المستخدم (إذا تم تقديمه). قد يحتوي على عدة معرفات مفصولة بفاصلة
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خطأ في معلمة الطلب (على سبيل المثال، فقدان imageUrl)تأكد من توفير imageUrl وأنه URL صالح
5002API_KEY_INVALIDمفتاح API غير صالح أو مفقودتأكد من وجود رأس APIKEY وصحة قيمته
9010SCAN_TEXT_ERRORفشل المطالبة في مراجعة المحتوىقم بمراجعة المطالبة لإزالة أي محتوى حساس أو محظور
9038PROHIBITED_CONTENTتحتوي صورة الإخراج المُولَّدة على محتوى محظورعدّل التوجيه النصي/النمط/الإدخالات وأعد المحاولة
9051COINS_NOT_ENOUGHرصيد غير كافٍقم بتعبئة الرصيد وأعد المحاولة

📄 للمزيد من تعريفات الأخطاء الشائعة، اطّلِع على مرجع رموز الخطأ.