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

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

POST/uploads

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

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

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

curl -X POST "https://platform-api2.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:

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 для загрузки файла:

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 для загрузки медиафайлов

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

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

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

• file — произвольный файл

• image — изображение

• video — видео

• audio — аудио

Ответ:

{
    "url": "https:///upload.do?..."
}

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

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

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

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

Ответ:

{
    "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
}

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

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

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

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

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

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

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

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

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

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

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

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

Авторизация

Параметры

Результат

Коды ответов