API למדיה
ממשק API לרשימת קובצי מדיה
קבלו את הקבצים בספריית המדיה של סביבת העבודה שלכם עם כתובות ה-URL להורדה שלהם, מהחדש לישן. סננו לפי סוג או חפשו לפי שם כדי למצוא קובץ שהעליתם קודם, והשתמשו שוב בכתובת שלו בהודעה.
https://wbiztool.com/api/v1/media/list/גוף הבקשה: query string, או גוף JSON עם POST
הרשימה כוללת קבצים שהועלו עם ה-API להעלאת מדיה ובדף Media Directory (ספריית מדיה). קבצים שנמחקו לא כלולים.
דוגמה מהירה#
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 בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.
פרמטרי הבקשה#
שלחו את הפרמטרים ב-query string של בקשת GET, או כגוף JSON בבקשת POST עם Content-Type: application/json. אל תשלבו בין השניים: אם client_id נמצא ב-query string, המערכת מתעלמת מגוף ה-JSON. גם POST עם קידוד טופס (form-encoded) עובד עבור client_id, api_key, file_type ו-search, אבל המערכת מתעלמת מ-page ומ-limit בשדות טופס; שלחו אותם ב-query string או ב-JSON.
אימות
client_idintegerחובהמזהה הלקוח שלכם ל-API (API Client ID) מהדף Settings → API keys.
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, שלחו את הכתובת בתורimg_urlעםmsg_type1; אחרת בתורfile_urlעםmsg_type2. ראו שליחת הודעה. - הרחיקו את מפתח ה-API מהלוגים: פרוקסי ושרתים שומרים לעיתים קרובות query strings בלוגים. אם זה חשוב לכם, השתמשו במקום זאת ב-
POSTעם גוף JSON.
