انتقل إلى المحتوى
Wbiztool

API الوسائط

API عرض ملفات الوسائط

احصل على الملفات في مكتبة الوسائط في مساحة العمل الخاصة بك مع عناوين URL للتنزيل، من الأحدث إلى الأقدم. صفِّ حسب النوع أو ابحث بالاسم للعثور على ملف رفعته سابقًا وإعادة استخدام عنوانه في رسالة.

GEThttps://wbiztool.com/api/v1/media/list/

النص (Body): سلسلة استعلام، أو جسم JSON مع POST

تتضمن القائمة الملفات المرفوعة باستخدام API رفع الوسائط ومن صفحة دليل الوسائط. لا تُدرج الملفات المحذوفة.

مثال سريع#

curl -G https://wbiztool.com/api/v1/media/list/ \
  --data-urlencode client_id=12345 \
  --data-urlencode api_key=YOUR_API_KEY \
  --data-urlencode file_type=image \
  --data-urlencode page=1 \
  --data-urlencode limit=20

استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

معاملات الطلب#

أرسل المعاملات في سلسلة الاستعلام لطلب GET، أو كجسم JSON في طلب POST مع Content-Type: application/json. لا تخلط بين الطريقتين: إذا كان client_id في سلسلة الاستعلام، يُتجاهل جسم JSON. يعمل أيضًا طلب POST مرمّز كنموذج مع client_id وapi_key وfile_type وsearch، لكن page وlimit يُتجاهلان في حقول النموذج؛ أرسلهما في سلسلة الاستعلام أو في JSON.

المصادقة

client_idintegerمطلوب

معرّف العميل في API ‏(API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).

api_keystringمطلوب

مفتاح API الخاص بك من الصفحة نفسها.

التصفية والتقسيم إلى صفحات

pageintegerاختياري

رقم الصفحة، بدءًا من 1 (القيمة الافتراضية). القيم الأقل من 1 تُعامَل على أنها 1.

limitintegerاختياري

عدد الملفات في كل صفحة، من 1 إلى 100. القيمة الافتراضية 20. القيم الأكبر من 100 تُعامَل على أنها 100، والقيم الأقل من 1 على أنها 20.

file_typestringاختياري

‏image للصور فقط، أو file لكل ما عداها. أي قيمة أخرى تُتجاهل.

searchstringاختياري

يُرجع فقط الملفات التي يحتوي اسمها الأصلي أو اسمها المخزَّن على هذا النص. غير حساس لحالة الأحرف.

POST مع جسم JSONcURL
curl -X POST https://wbiztool.com/api/v1/media/list/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "search": "invoice",
    "page": 1,
    "limit": 50
  }'

الاستجابة#

{
  "status": 1,
  "message": "Media files retrieved successfully",
  "data": {
    "total_count": 1,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "media_files": [
      {
        "id": 5123,
        "file_name": "media_12345_17895806123456.jpg",
        "original_file_name": "diwali-sale.jpg",
        "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895806123456.jpg",
        "file_type": "image",
        "file_size": 524288,
        "file_size_display": "512.0 KB",
        "mime_type": "image/jpeg",
        "is_image": true,
        "file_extension": "jpg",
        "created_at": "2026-09-16T10:23:52.106447+00:00",
        "uploaded_by": "[email protected]"
      }
    ]
  }
}
الحقلالنوعالوصف
statusinteger‏1 عند النجاح، و0 إذا فشل الطلب.
messagestring‏Media files retrieved successfully، وإلا نص الخطأ.
data.total_countintegerعدد الملفات المطابقة لعوامل التصفية، عبر كل الصفحات.
data.pageintegerالصفحة المُرجَعة.
data.limitintegerحجم الصفحة المستخدم، بعد ضبطه ضمن النطاق من 1 إلى 100.
data.total_pagesintegerعدد الصفحات. يكون 0 عند عدم وجود ملفات.
data.has_nextboolean‏true إذا كانت توجد صفحة بعد هذه الصفحة.
data.has_previousboolean‏true إذا كانت page أكبر من 1.
data.media_filesarrayالملفات في هذه الصفحة، من الأحدث إلى الأقدم. تكون فارغة إذا كانت الصفحة بعد النهاية.

حقول ملف الوسائط#

الحقلالنوعالوصف
idintegerمعرّف ملف الوسائط. استخدمه مع جلب ملف وسائط.
file_namestringالاسم الذي خُزّن به الملف.
original_file_namestringاسم الملف عند رفعه.
file_urlstringعنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال.
file_typestring‏image أو file.
file_sizeintegerالحجم بالبايت.
file_size_displaystringحجم مقروء بمنزلة عشرية واحدة، مثل 512.0 KB.
mime_typestringنوع MIME، مثل image/jpeg.
is_imageboolean‏true عندما تكون قيمة file_type هي image.
file_extensionstringامتداد original_file_name بأحرف صغيرة، بدون النقطة.
created_atstringوقت الرفع، بصيغة ISO 8601 بتوقيت UTC مع الفرق +00:00.
uploaded_bystring or nullاسم مستخدم تسجيل الدخول (عادةً عنوان البريد الإلكتروني) لعضو الفريق الذي رفع الملف.

الأخطاء#

تُرجع الأخطاء أيضًا HTTP 200، مع status بقيمة 0:

{ "status": 0, "message": "Invalid API key" }
الرسالةطريقة الإصلاح
client_id is requiredأضف client_id. إذا كنت ترسل JSON، فتأكد من أن الجسم JSON صالح (يُبلَّغ عن خطأ التحليل بهذه الرسالة).
api_key is requiredأضف api_key.
client_id must be a valid integerأرسل client_id كرقم.
Invalid API keyتأكد من أن المفتاح موجود ولم يُحذف أو يُعطَّل.
Invalid client_id for this API keyالمفتاح ينتمي إلى client_id مختلف.
Error retrieving media files: …غالبًا لا تكون قيمة page أو limit في سلسلة الاستعلام أو حقول النموذج عددًا صحيحًا. أما في جسم JSON فلا يظهر خطأ: إذا لم تكن page عددًا صحيحًا، فتُتجاهل page وlimit وfile_type وsearch كلها، فتحصل على الصفحة 1 مع 20 ملفًا وبدون عوامل تصفية. وإذا كانت limit وحدها ليست عددًا صحيحًا، فتُتجاهل limit وfile_type وsearch.

قراءة كل الصفحات#

واصل طلب الصفحة التالية ما دامت قيمة data.has_next هي true.

جلب كل ملفات الوسائط
import requests

files, page = [], 1

while True:
    result = requests.get(
        "https://wbiztool.com/api/v1/media/list/",
        params={"client_id": 12345, "api_key": "YOUR_API_KEY", "page": page, "limit": 100},
        timeout=60,
    ).json()
    if result["status"] != 1:
        raise RuntimeError(result["message"])

    files += result["data"]["media_files"]
    if not result["data"]["has_next"]:
        break
    page += 1

print(len(files), "files")

نصائح#

  • استخدم معامل الإرسال الصحيح: عندما تكون قيمة is_image هي true، أرسل عنوان URL كقيمة img_url مع msg_type 1؛ وإلا فكقيمة file_url مع msg_type 2. راجع إرسال رسالة.
  • أبقِ مفتاح API خارج السجلات: كثيرًا ما تسجّل الوكلاء (proxies) والخوادم سلاسل الاستعلام. إذا كان ذلك يهمك، فاستخدم POST مع جسم JSON بدلًا من ذلك.