واجهة برمجة التطبيقات API

المقدمة

مرحباً بك في توثيق واجهة برمجة تطبيقات OSUS.AI. تتيح لك هذه الواجهة الوصول إلى جميع خدماتنا برمجياً، بما في ذلك مكتبة الموديلات ثلاثية الأبعاد وأدوات الذكاء الاصطناعي.

                                Base URL
                            
                                https://api.osus.ai/v2

المصادقة

مفتاح API

جميع طلبات API تتطلب مفتاح API صالح. يمكنك الحصول على مفتاحك من إعدادات الحساب.

HTTP Header

Authorization: Bearer YOUR_API_KEY

مثال cURL

curl -X GET "https://api.osus.ai/v2/models" \
     -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
     -H "Content-Type: application/json"

حدود الاستخدام

لضمان جودة الخدمة لجميع المستخدمين، نطبق حدوداً على عدد الطلبات المسموح بها.

الخطة	الطلبات/دقيقة	الطلبات/يوم	AI الطلبات/يوم
مجاني	30	1,000	10
احترافي	100	10,000	100
مؤسسات	500	100,000	1,000

قائمة الموديلات

GET /models

استرجاع قائمة بجميع الموديلات ثلاثية الأبعاد المتاحة مع إمكانية التصفية والترتيب.

المعاملات

المعامل	النوع	الوصف
category	string	تصفية حسب الفئة (living-room, bedroom, kitchen, etc.)
style	string	تصفية حسب الأسلوب (modern, classic, arabic, etc.)
format	string	تصفية حسب صيغة الملف (3ds, fbx, obj, blend)
page	integer	رقم الصفحة (افتراضي: 1)
limit	integer	عدد النتائج لكل صفحة (افتراضي: 20، الحد الأقصى: 100)

طلب

GET /v2/models?category=living-room&style=modern&limit=10

استجابة ناجحة (200)

JSON

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "mdl_abc123",
        "name": "كنبة مودرن فاخرة",
        "name_en": "Luxury Modern Sofa",
        "category": "living-room",
        "style": "modern",
        "price": 450,
        "currency": "SAR",
        "formats": ["3ds", "fbx", "obj"],
        "polygons": 45000,
        "textures": "4K PBR",
        "preview_url": "https://cdn.osus.ai/previews/mdl_abc123.jpg",
        "designer": {
          "id": "usr_xyz789",
          "name": "أحمد الفاخري"
        },
        "rating": 4.8,
        "downloads": 1250,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 156,
      "pages": 16
    }
  }
}

تحسين الصور بالذكاء الاصطناعي

POST /ai/upscale

تحسين جودة الصور وزيادة دقتها حتى 4 أضعاف باستخدام الذكاء الاصطناعي.

المعاملات

المعامل	النوع	الوصف
مطلوب image	file/url	الصورة المراد تحسينها (ملف أو رابط URL)
scale	integer	نسبة التكبير: 2 أو 4 (افتراضي: 2)
format	string	صيغة الإخراج: png, jpg, webp (افتراضي: png)

cURL

curl -X POST "https://api.osus.ai/v2/ai/upscale" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -F "image=@/path/to/image.jpg" \
     -F "scale=4" \
     -F "format=png"

استجابة ناجحة (200)

                                            JSON
                                        

                                            {
  "success": true,
  "data": {
    "id": "job_upscale_123",
    "status": "completed",
    "original_size": "512x512",
    "output_size": "2048x2048",
    "output_url": "https://cdn.osus.ai/processed/upscale_123.png",
    "expires_at": "2024-01-16T10:30:00Z",
    "credits_used": 1
  }
}
                                        

مكتبات SDK

نوفر مكتبات SDK رسمية لتسهيل التكامل مع واجهة البرمجة.

JavaScript

npm install @osus/sdk

Python

pip install osus-sdk

PHP

composer require osus/sdk

JavaScript

import { OsusClient } from '@osus/sdk';

const client = new OsusClient('YOUR_API_KEY');

// جلب قائمة الموديلات
const models = await client.models.list({
  category: 'living-room',
  style: 'modern',
  limit: 10
});

// تحسين صورة
const result = await client.ai.upscale({
  image: './my-image.jpg',
  scale: 4
});

console.log(result.output_url);

Python

from osus import OsusClient

client = OsusClient('YOUR_API_KEY')

# جلب قائمة الموديلات
models = client.models.list(
    category='living-room',
    style='modern',
    limit=10
)

# تحسين صورة
result = client.ai.upscale(
    image='./my-image.jpg',
    scale=4
)

print(result.output_url)

معالجة الأخطاء

تستخدم الواجهة رموز HTTP القياسية للإشارة إلى نجاح أو فشل الطلب.

الرمز	الحالة	الوصف
200	OK	الطلب نجح
400	Bad Request	معاملات غير صالحة
401	Unauthorized	مفتاح API غير صالح
403	Forbidden	لا تملك صلاحية الوصول
404	Not Found	المورد غير موجود
429	Too Many Requests	تجاوزت حد الطلبات
500	Server Error	خطأ في الخادم

                                مثال خطأ
                            

                                {
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "مفتاح API غير صالح أو منتهي الصلاحية",
    "status": 401
  }
}
                            