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

⚠️ До 19 июля 2026

Для корректной работы ваших чат-ботов и мини-приложений необходимо перенаправить HTTP-запросы с домена platform-api.max.ru на platform-api2.max.ru, а также добавить сертификат Минцифры в список доверенных.

POST/uploads

Метод возвращает URL для загрузки медиафайла и токен для передачи загруженного файла во вложении к сообщению в чате или канале. После загрузки файла токен передаётся в запросе POST /messages или PUT /messages в параметре attachments.payload.token

Для изображений вместо токена и текущего метода вы также можете использовать внешний URL для загрузки по прямой ссылке — подробнее смотрите параметры объекта attachments.payload.url в POST /messages. Для отправки остальных медиафайлов, потребуется получить токен: загрузить их через /uploads

Пример запроса для загрузки медиафайла

BASH

Скопировать

curl -X POST "https://platform-api.max.ru/uploads?type={type}" \
  -H "Authorization: {access_token}"

Типы медиафайлов и ограничения

Медиафайлы, которые можно загрузить через POST /uploads, должны быть одного из типов type:

• image — изображения
Доступные форматы: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC
Максимальный размер одного изображения: до 50 МБ или не более 7680 x 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 x 7600 px нельзя

• video — видеофайлы
Доступные форматы: MP4, MOV, MKV, WEBM
Максимальный размер одного видео: до 250 МБ

• audio — аудиофайлы
Доступные форматы: MP3, WAV, M4A и другие
Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя

• file — другие файлы
Максимальный размер одного файла: до 4 ГБ
Доступные форматы: TXT, DOC, PDF и другие распространённые форматы

Параметр type=photo больше не поддерживается. Если вы использовали type=photo в ранее созданных интеграциях — замените его на type=image

По URL-ссылке, которая вернётся в ответ на запрос, можно загрузить только один файл. Если вы хотите загрузить ещё файл, отправьте повторно запрос POST /uploads и используйте новую URL-ссылку

Способы загрузки медиафайлов

В ответ на текущий запрос POST /uploads в поле url вернётся URL для загрузки медиафайла — загрузить можно одним из двух способов:

Resumable upload — надёжный способ, если заголовок Content-Type не равен multipart/form-data. Этот способ позволяет загружать файл частями и возобновлять загрузку с последней успешно загруженной части в случае ошибок

Пример загрузки файла по URL:

BASH

Скопировать

curl -X POST "%UPLOAD_URL%" \
  -H "Authorization: {access_token}" \
  -F "data=@example.mp4"

где %UPLOAD_URL% — это значение поля url, которое вернулось в ответе на запрос POST /uploads

Multipart upload — более простой, но менее надёжный способ. В этом случае используется заголовок Content-Type: multipart/form-data. Файл отправляется целиком одним запросом. Если загрузка прервётся, невозможно её возобновить — придётся начать заново

Пример использования cURL для загрузки файла:

SHELL

Скопировать

curl -i -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "data=@movie.pdf" "%UPLOAD_URL%"

где %UPLOAD_URL% — это значение поля url, которое вернулось в ответе на запрос POST /uploads

Особенности загрузки разных типов медиафайлов

Видео и аудио:

Когда получаем ссылку на загрузку видео или аудио (POST /uploads с type = video или type = audio), вместе с url в ответе приходит token, который нужно использовать в сообщении (когда формируете body с attachments) в POST /messages
После загрузки видео или аудио (по url из шага выше) сервер возвращает retval
C этого момента можно использовать token, чтобы прикреплять вложение в сообщение бота

Изображения и файлы:

Дляtype = file: token возвращается в ответе на загрузку файла
Дляtype = image:
- token возвращается в ответе на загрузку файла
- token содержится в URL, возвращаемом в методе для загрузки файла

Прикрепление медиафайлов

Процесс прикрепления медиафайлов к сообщениям состоит из трёх шагов:

1. Получение URL для загрузки медиафайлов

Отправьте запрос:

BASH

Скопировать

curl -X POST "https://platform-api.max.ru/uploads?type={type}" \
  -H "Authorization: {access_token}"

где {type} — тип загружаемого файла:

file — произвольный файл
image — изображение
video / audio — видео или аудио

Ответ:

JSON

Скопировать

{
    "url": "https://<upload-host>/upload.do?..."
}

Обратите внимание: домен в url зависит от типа файла. Это ожидаемое поведение:
file → https://fu.oneme.ru
image → https://iu.oneme.ru
video / audio → https://vu.okcdn.ru

2. Загрузка медиафайла

Используйте полученный url без изменений:

BASH

Скопировать

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "data=@movie.mp4" \
  "{url}"

Ответ:

JSON

Скопировать

{
    "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
}

3. Создание вложения

После успешной загрузки получите JSON-объект в ответе. Используйте этот объект для создания вложения. Структура вложения:

type: тип медиа, например "video"
payload: JSON-объект, который вы получили.

Отправьте сообщение с вложением:

JSON

Скопировать

{
    "text": "Message with video",
    "attachments": [
        {
            "type": "video",
            "payload": {
                "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
            }
        }
    ]
}

Обработка медиафайлов

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

Для стабильной работы сервисов MAX убедитесь, что максимальное количество запросов в секунду на platform-api.max.ru — 30 rps

Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка:

JSON

Скопировать

{
  "code": "attachment.not.ready",
  "message": "Key: errors.process.attachment.file.not.processed"
}

Как избежать ошибки:

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

Авторизация

access_token
apiKey

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты → Перейти → Расширенные настройки → Настроить

Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы

Параметры

type
enum UploadType

Возможные значения в enum: "image" "video" "audio" "file"

Тип загружаемого медиафайла. Возможные значения и поддерживаемые форматы:

image — изображение (JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC)
Максимальный размер одного изображения: до 50 МБ или не более 7680 x 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 x 7600 px нельзя
video — видеофайл (MP4, MOV, MKV, WEBM)
Максимальный размер одного видео: до 250 МБ
audio — аудиофайл (MP3, WAV, M4A и другие)
Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя
file — файл, поддерживаются распространённые форматы (например, TXT, DOC и другие)
Максимальный размер одного файла: до 4 ГБ

При передаче неподдерживаемого типа файла вернётся ошибка File extension is forbidden

Значение photo больше не поддерживается. Если вы использовали type=photo в ранее созданных интеграциях — замените его на type=image

Результат

url
string

URL для загрузки медиафайла. Срок жизни ссылки не ограничен

token
string optional

Токен для отправки медиафайла во вложении к сообщению с помощью POST /messages или PUT /messages