API الوسائط
API عرض ملفات الوسائط
احصل على الملفات في مكتبة الوسائط في مساحة العمل الخاصة بك مع عناوين URL للتنزيل، من الأحدث إلى الأقدم. صفِّ حسب النوع أو ابحث بالاسم للعثور على ملف رفعته سابقًا وإعادة استخدام عنوانه في رسالة.
https://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=20import requests
response = requests.get(
"https://wbiztool.com/api/v1/media/list/",
params={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"file_type": "image",
"page": 1,
"limit": 20,
},
timeout=60,
)
result = response.json()
if result["status"] == 1:
data = result["data"]
print(f"Page {data['page']} of {data['total_pages']} ({data['total_count']} files)")
for media in data["media_files"]:
print(media["id"], media["original_file_name"], media["file_url"])
else:
print("Failed:", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({
client_id: "12345",
api_key: "YOUR_API_KEY",
file_type: "image",
page: "1",
limit: "20",
});
const response = await fetch(url);
const result = await response.json();
if (result.status === 1) {
const { data } = result;
console.log(`Page ${data.page} of ${data.total_pages} (${data.total_count} files)`);
for (const media of data.media_files) {
console.log(media.id, media.original_file_name, media.file_url);
}
} else {
console.error("Failed:", result.message);
}<?php
$query = http_build_query([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'file_type' => 'image',
'page' => 1,
'limit' => 20,
]);
$ch = curl_init('https://wbiztool.com/api/v1/media/list/?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
foreach ($result['data']['media_files'] as $media) {
echo $media['id'] . ' ' . $media['original_file_name'] . ' ' . $media['file_url'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}استبدل 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اختيارييُرجع فقط الملفات التي يحتوي اسمها الأصلي أو اسمها المخزَّن على هذا النص. غير حساس لحالة الأحرف.
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]"
}
]
}
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 عند النجاح، و0 إذا فشل الطلب. |
message | string | Media files retrieved successfully، وإلا نص الخطأ. |
data.total_count | integer | عدد الملفات المطابقة لعوامل التصفية، عبر كل الصفحات. |
data.page | integer | الصفحة المُرجَعة. |
data.limit | integer | حجم الصفحة المستخدم، بعد ضبطه ضمن النطاق من 1 إلى 100. |
data.total_pages | integer | عدد الصفحات. يكون 0 عند عدم وجود ملفات. |
data.has_next | boolean | true إذا كانت توجد صفحة بعد هذه الصفحة. |
data.has_previous | boolean | true إذا كانت page أكبر من 1. |
data.media_files | array | الملفات في هذه الصفحة، من الأحدث إلى الأقدم. تكون فارغة إذا كانت الصفحة بعد النهاية. |
حقول ملف الوسائط#
| الحقل | النوع | الوصف |
|---|---|---|
id | integer | معرّف ملف الوسائط. استخدمه مع جلب ملف وسائط. |
file_name | string | الاسم الذي خُزّن به الملف. |
original_file_name | string | اسم الملف عند رفعه. |
file_url | string | عنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال. |
file_type | string | image أو file. |
file_size | integer | الحجم بالبايت. |
file_size_display | string | حجم مقروء بمنزلة عشرية واحدة، مثل 512.0 KB. |
mime_type | string | نوع MIME، مثل image/jpeg. |
is_image | boolean | true عندما تكون قيمة file_type هي image. |
file_extension | string | امتداد original_file_name بأحرف صغيرة، بدون النقطة. |
created_at | string | وقت الرفع، بصيغة ISO 8601 بتوقيت UTC مع الفرق +00:00. |
uploaded_by | string 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")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const files = [];
let page = 1;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/media/list/");
url.search = new URLSearchParams({ client_id: "12345", api_key: "YOUR_API_KEY", page: String(page), limit: "100" });
const result = await (await fetch(url)).json();
if (result.status !== 1) throw new Error(result.message);
files.push(...result.data.media_files);
if (!result.data.has_next) break;
page += 1;
}
console.log(files.length, "files");نصائح#
- استخدم معامل الإرسال الصحيح: عندما تكون قيمة
is_imageهيtrue، أرسل عنوان URL كقيمةimg_urlمعmsg_type1؛ وإلا فكقيمةfile_urlمعmsg_type2. راجع إرسال رسالة. - أبقِ مفتاح API خارج السجلات: كثيرًا ما تسجّل الوكلاء (proxies) والخوادم سلاسل الاستعلام. إذا كان ذلك يهمك، فاستخدم
POSTمع جسم JSON بدلًا من ذلك.
