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

توثيق API الديكور المنزلي#

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


📖 نظرة عامة#

تُولّد API الديكور المنزلي أفكار ديكورية لصور داخلية. تدعم إرشادات نصية اختيارية، وصورة مرجعية، واختيارات الأنماط، وأوضاع النموذج.

سير العمل غير متزامن:

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

🔐 المصادقة#

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

💰 خصم الرصيد#

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

النموذج (modelType)الرصيد المخصوم
Base3 رصيد
Pro10 رصيد

إذا لم يتم تقديم modelType، فسيتم استخدام Base افتراضياً.


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

يدعم هذا API معلمات نمط اختيارية تعيدها نقطة نهاية إعدادات نمط API.

الاستخدام:

نص عادي
GET /api/v1/style/home_decor_ideas/getStyles
مجموعة النمطحقل الطلبالوصف
spaceTypespaceStyleIdخيار نوع المساحة أو الغرفة
decorStylehomeDecorStyleIdخيار نمط الديكور

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


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

1. إنشاء مهمة ديكور منزلي#

نقطة النهاية

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

رؤوس الطلب

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

جسم الطلب

الحقلالنوعمطلوبالوصف
imageUrlstring✅ نعمURL للصورة الداخلية المصدر
referenceUrlstring❌ اختياريURL صورة مرجعية لتوجيه نمط الديكور
spaceStyleIdstring❌ اختياريمعرّف نوع المساحة من خيارات spaceType
homeDecorStyleIdstring❌ اختياريمعرّف نمط الديكور من خيارات decorStyle
promptstring❌ اختياريإرشادات نصية للنتيجة المطلوبة
modelTypestring❌ اختياريالقيم الممكنة: Base، Pro. الافتراضي Base

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

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

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

cURL
bash
curl -X POST "https://api.ideal.house/api/v1/homeDecor/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class HomeDecorApiExample {

    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/room.jpg",
                    "referenceUrl": "https://example.com/reference.jpg",
                    "spaceStyleId": "Indoor_Living Room",
                    "homeDecorStyleId": "Holidays_Cozy Christmas",
                    "prompt": "warm seasonal decor with natural textures",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/homeDecor/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/room.jpg",
    "referenceUrl": "https://example.com/reference.jpg",
    "spaceStyleId": "Indoor_Living Room",
    "homeDecorStyleId": "Holidays_Cozy Christmas",
    "prompt": "warm seasonal decor with natural textures",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/homeDecor/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 createHomeDecorTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/homeDecor/generate`,
      {
        imageUrl: 'https://example.com/room.jpg',
        referenceUrl: 'https://example.com/reference.jpg',
        spaceStyleId: 'Indoor_Living Room',
        homeDecorStyleId: 'Holidays_Cozy Christmas',
        prompt: 'warm seasonal decor with natural textures',
        modelType: 'Base'
      },
      {
        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);
  }
}

createHomeDecorTask();

📤 الاستجابة#

json
{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

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

نقطة النهاية

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

رؤوس الطلب

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

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

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

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

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

import java.io.IOException;

public class HomeDecorResultExample {

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

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

pollHomeDecorResult(1234567890123456789n);

📤 مثال الاستجابة#

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "refImageUrl": "https://example.com/reference.jpg",
      "spaceStyleId": "Indoor_Living Room",
      "homeDecorStyleId": "Holidays_Cozy Christmas",
      "prompt": "warm seasonal decor with natural textures",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/home_decor_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/room.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

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

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

📊 حالة المهمة#

الحالةالوصف
Unprocessedتم إنشاء المهمة وهي تنتظر في الطابور
Processingالمهمة قيد التشغيل حالياً
Successاكتملت المهمة بنجاح
Failedفشلت المهمة ولم يتم إنتاج أي مخرج

استعلم دورياً كل 3-5 ثوانٍ. انظر حد مهمة API.


❌ استجابات الخطأ#

الرمزالاسمالوصف
1011PARAM_ERRORخطأ في معامل الطلب
5002API_KEY_INVALIDمفتاح API غير صالح أو مفقود
9010SCAN_TEXT_ERRORفشل المطالبة في مراجعة المحتوى
9038PROHIBITED_CONTENTتحتوي الصورة المُنشأة على محتوى محظور
9051COINS_NOT_ENOUGHرصيد غير كافٍ

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