Перейти к содержимому
Wbiztool

API медиафайлов

API списка медиафайлов

Получите файлы из медиатеки вашего рабочего пространства со ссылками для скачивания, начиная с самых новых. Фильтруйте по типу или ищите по имени, чтобы найти ранее загруженный файл и повторно использовать его ссылку в сообщении.

GEThttps://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=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 Client ID из раздела Настройки → 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]"
      }
    ]
  }
}
ПолеТипОписание
statusinteger1 при успехе, 0, если запрос не выполнен.
messagestringMedia files retrieved successfully, иначе текст ошибки.
data.total_countintegerЧисло файлов, подходящих под фильтры, на всех страницах.
data.pageintegerВозвращённая страница.
data.limitintegerИспользованный размер страницы после приведения к диапазону от 1 до 100.
data.total_pagesintegerЧисло страниц. 0, если файлов нет.
data.has_nextbooleantrue, если после этой страницы есть ещё одна.
data.has_previousbooleantrue, если page больше 1.
data.media_filesarrayФайлы на этой странице, начиная с самых новых. Пустой, если страница за пределами списка.

Поля медиафайла#

ПолеТипОписание
idintegerID медиафайла. Используйте его в API получения медиафайла.
file_namestringИмя, под которым хранится файл.
original_file_namestringИмя файла на момент загрузки.
file_urlstringПрямая ссылка для скачивания. Используйте её как img_url или file_url при отправке.
file_typestringimage или file.
file_sizeintegerРазмер в байтах.
file_size_displaystringРазмер в удобном для чтения виде с одним знаком после запятой, например 512.0 KB.
mime_typestringMIME-тип, например image/jpeg.
is_imagebooleantrue, если 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 отправки сообщений.
  • Не допускайте попадания API-ключа в журналы: строки запроса часто записываются в журналы прокси и серверов. Если это для вас важно, используйте POST с телом JSON.