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)الرصيد المخصوم
Flash1 رصيد
Base3 رصيد
Pro10 رصيد

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


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

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

الاستخدام:

نص عادي
GET /api/v1/style/landscaping/getStyles
مجموعة النمطحقل الطلبالوصف
gardenStylesceneIdخيار نمط الحديقة أو المناظر الطبيعية
elementssceneElementIdخيار عنصر المناظر الطبيعية. يدعم عدة معرفات خيارات مفصولة بفاصلة، مثل id1,id2

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


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

1. إنشاء مهمة تنسيق حدائق#

نقطة النهاية

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

رؤوس الطلب

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

جسم الطلب

الحقلالنوعمطلوبالوصف
imageUrlstring✅ نعمURL صورة المصدر للمناظر الطبيعية
promptstring❌ اختياريإرشاد نصي للنتيجة المطلوبة
sceneIdstring❌ اختياريمعرف نمط الحديقة من خيارات gardenStyle
sceneElementIdstring❌ اختياريمعرف عنصر المناظر الطبيعية من خيارات elements. يدعم عدة معرفات مفصولة بفاصلة، مثل id1,id2
modelTypestring❌ اختياريتعداد: Flash، 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/landscaping/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
  }'
Java (OkHttp)
java
import okhttp3.*;

import java.io.IOException;

public class LandscapingApiExample {

    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/backyard.jpg",
                    "prompt": "lush modern garden with clean stone paths",
                    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
                    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
                    "modelType": "Base"
                }
                """;

        Request request = new Request.Builder()
                .url(BASE_URL + "/api/v1/landscaping/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/backyard.jpg",
    "prompt": "lush modern garden with clean stone paths",
    "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
    "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
    "modelType": "Base"
}

response = requests.post(
    f"{BASE_URL}/api/v1/landscaping/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 createLandscapingTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/landscaping/generate`,
      {
        imageUrl: 'https://example.com/backyard.jpg',
        prompt: 'lush modern garden with clean stone paths',
        sceneId: 'Landscape Design_Landscape Style_Mid-Century Modern Pool',
        sceneElementId: 'Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover',
        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);
  }
}

createLandscapingTask();

📤 الاستجابة#

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

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

نقطة النهاية

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

رؤوس الطلب

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

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

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

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

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

import java.io.IOException;

public class LandscapingResultExample {

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

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

pollLandscapingResult(1234567890123456789n);

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/backyard.jpg",
      "prompt": "lush modern garden with clean stone paths",
      "sceneId": "Landscape Design_Landscape Style_Mid-Century Modern Pool",
      "sceneElementId": "Landscape Design_Scene Elements_Natural Elements_Flower,Landscape Design_Scene Elements_Natural Elements_Ground Cover",
      "modelType": "Base"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/landscaping_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/backyard.jpg",
      "modelType": "Base"
    },
    "output": null
  }
}

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

json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/backyard.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رصيد غير كافٍ

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