API медиафайлов
API списка медиафайлов
Получите файлы из медиатеки вашего рабочего пространства со ссылками для скачивания, начиная с самых новых. Фильтруйте по типу или ищите по имени, чтобы найти ранее загруженный файл и повторно использовать его ссылку в сообщении.
https://wbiztool.com/api/v1/media/list/Тело запроса: Строка запроса или тело 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 Client ID из раздела Настройки → 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 | ID медиафайла. Используйте его в API получения медиафайла. |
file_name | string | Имя, под которым хранится файл. |
original_file_name | string | Имя файла на момент загрузки. |
file_url | string | Прямая ссылка для скачивания. Используйте её как 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 отправки сообщений. - Не допускайте попадания API-ключа в журналы: строки запроса часто записываются в журналы прокси и серверов. Если это для вас важно, используйте
POSTс телом JSON.
