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

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

API загрузки медиафайлов

Загрузите изображение, документ, аудио- или видеофайл в Медиакаталог вашего рабочего пространства и получите ссылку для скачивания. Передайте эту ссылку в API отправки сообщений или в API создания напоминаний как img_url, если у вас нет собственного хостинга файлов.

POSThttps://wbiztool.com/api/v1/media/upload/

Тело запроса: multipart/form-data

Файл сохраняется сразу, а ответ содержит его file_url. Загруженные файлы также появляются на странице Медиакаталог в вашей панели управления.

Быстрый пример#

curl -X POST https://wbiztool.com/api/v1/media/upload/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F media_file=@./invoice-4821.pdf

Замените 12345 и YOUR_API_KEY своими значениями. Где их найти, описано в разделе Аутентификация.

Параметры запроса#

Отправляйте запрос как multipart/form-data. Тело JSON и параметры в строке запроса этот endpoint не читает.

client_idintegerобязательно

Ваш API Client ID из раздела Настройки → API ключи.

api_keystringобязательно

Ваш API-ключ с той же страницы.

media_filefileобязательно

Загружаемый файл размером до 64 МБ; он должен помещаться в хранилище медиафайлов рабочего пространства. Его тип определяется по расширению в имени файла, поэтому имя должно заканчиваться одним из поддерживаемых расширений.

Поддерживаемые типы файлов#

КатегорияРасширения
Изображения.jpg, .jpeg, .png, .gif, .webp, .bmp
Документы.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv
Аудио.mp3, .m4a, .wav, .ogg, .aac
Видео.mp4, .mov, .avi
Архивы.zip, .rar

Изображения сохраняются с file_type, равным image; всё остальное — file.

Хранилище рабочего пространства#

Все файлы в Медиакаталоге рабочего пространства делят один лимит хранилища, который задаётся тарифом рабочего пространства. Учитываются и файлы, загруженные через этот API, и загруженные на странице Медиакаталога, а удаление файла освобождает его место.

ТарифХранилище медиафайлов
Пробный период250 МБ
Lite1 ГБ
Standard2 ГБ
Advanced5 ГБ
Enterprise10 ГБ
AppSumo Plan 1 и Plan 21 ГБ
AppSumo Plan 32 ГБ
AppSumo Plan 43 ГБ
AppSumo Plan 55 ГБ

У старых тарифов и у рабочего пространства без активного тарифа — 1 ГБ. Загрузка, которая не помещается, отклоняется с ошибкой Storage full: … (см. Ошибки). Рабочее пространство, которое уже превысило лимит, сохраняет свои файлы, но не может добавлять новые, пока для них не появится место.

Ответ#

Успешный запрос возвращает HTTP 200:

{
  "status": 1,
  "message": "File uploaded successfully",
  "data": {
    "id": 5122,
    "file_name": "media_12345_17895804001234_3f9a1c7e.pdf",
    "original_file_name": "invoice-4821.pdf",
    "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf",
    "file_type": "file",
    "file_size": 248312,
    "file_size_display": "242.5 KB",
    "mime_type": "application/pdf",
    "is_image": false,
    "file_extension": "pdf",
    "created_at": "2026-09-16T10:20:31.512934+00:00"
  }
}
ПолеТипОписание
statusinteger1, если файл загружен, 0, если запрос не выполнен.
messagestringFile uploaded successfully, иначе текст ошибки.
data.idintegerID медиафайла. Используйте его в API получения медиафайла.
data.file_namestringИмя, под которым хранится файл; генерируется WbizTool: media_, ID вашего рабочего пространства, время загрузки и случайная часть, с расширением файла.
data.original_file_namestringИмя загруженного вами файла.
data.file_urlstringПрямая ссылка для скачивания. Используйте её как img_url или file_url при отправке. Она публичная и не истекает, но перестаёт работать после удаления файла. Она может быть на media.wbiztool.com (наш CDN) или на wbiztool-static.s3.ap-southeast-1.amazonaws.com; оба адреса отдают один и тот же файл, поэтому сохраняйте ссылку как есть и не составляйте такие URL сами.
data.file_typestringimage или file.
data.file_sizeintegerРазмер в байтах.
data.file_size_displaystringРазмер в удобном для чтения виде с одним знаком после запятой, например 242.5 KB.
data.mime_typestringMIME-тип, определённый по расширению, например application/pdf.
data.is_imagebooleantrue, если file_type равен image.
data.file_extensionstringРасширение original_file_name в нижнем регистре, без точки.
data.created_atstringВремя загрузки в формате ISO 8601 в UTC со смещением +00:00.

Ошибки#

Ошибки тоже возвращаются с HTTP 200 и status, равным 0:

{ "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }
СообщениеКак исправить
Only POST method is supportedОтправьте запрос POST.
client_id is requiredДобавьте client_id как поле формы. Проверьте, что тело запроса — multipart/form-data, а не JSON.
api_key is requiredДобавьте api_key как поле формы.
media_file is requiredПередайте файл в поле с именем media_file.
client_id must be a valid integerПередайте client_id числом.
Invalid API keyПроверьте, что ключ существует, не удалён и не отключён.
Invalid client_id for this API keyКлюч принадлежит другому client_id.
File is too large. Maximum size is 64MB. Your file: …MBЗагрузите файл размером не более 64 МБ.
File type not supported. Type detected: …Используйте одно из поддерживаемых расширений.
Storage full: this workspace uses … of its … of media storage, and this file is …. Delete files you no longer need in the Media directory, or contact us if you need more space.Файл не помещается в хранилище медиафайлов рабочего пространства. Удалите ненужные файлы на странице Медиакаталог или свяжитесь с нами, чтобы получить больше места.
Error uploading file: …Не удалось завершить загрузку. Повторите попытку. Эта ошибка также возвращается, если API-ключ не привязан к рабочему пространству; создайте новый ключ в нужном рабочем пространстве.

Загрузка и отправка#

Загрузите файл, затем передайте file_url в API отправки сообщений: для изображений — как img_url с msg_type 1, для остальных файлов — как file_url с msg_type 2.

Загрузка PDF и его отправка
import requests

BASE = "https://wbiztool.com/api/v1"
AUTH = {"client_id": 12345, "api_key": "YOUR_API_KEY"}

with open("invoice-4821.pdf", "rb") as f:
    upload = requests.post(f"{BASE}/media/upload/", data=AUTH, files={"media_file": f}, timeout=120).json()
if upload["status"] != 1:
    raise SystemExit("Upload failed: " + upload["message"])

media = upload["data"]
message = {
    **AUTH,
    "whatsapp_client": 678,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Your invoice for order #4821 is attached.",
}
if media["is_image"]:
    message.update(msg_type=1, img_url=media["file_url"])
else:
    message.update(msg_type=2, file_url=media["file_url"], file_name=media["original_file_name"])

sent = requests.post(f"{BASE}/send_msg/", json=message, timeout=60).json()
print(sent)

Каждый тип файлов, который принимает этот API, сохраняет своё расширение при отправке с msg_type 2, например brochure.doc или catalogue.zip. Аудио WAV и OGG приходит как документ, а не как воспроизводимое аудио, а при отправке как изображение (msg_type 1) завершается ошибкой File type not supported. MP3, M4A и AAC приходят как аудио, которое воспроизводится в чате, а текст идёт отдельным сообщением. См. раздел Отправка изображений и файлов. Имя отправляется в нижнем регистре (Invoice-4821.PDF приходит как invoice-4821.pdf).

Изображения, отправляемые с msg_type 1, должны быть не больше 16 МБ. Более крупные изображения здесь загружаются без проблем, но не отправляются с ошибкой File exceeds WhatsApp size limit (16MB max). Сначала сожмите их или отправьте как файл с msg_type 2.

Советы#

  • Используйте загрузки повторно. Сохраните id или file_url и отправляйте один и тот же файл многократно, не загружая его заново.
  • Давайте файлам понятные исходные имена. original_file_name отображается в панели управления и хорошо подходит в качестве file_name при отправке.
  • Ранее загруженные файлы можно найти через API списка медиафайлов.