

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

Метод возвращает URL для загрузки медиафайла и последующей отправки его во вложении к сообщению в чате или канале. После загрузки файлу присваивается токен, который нужно передать в запросе [POST /messages](/docs-api/methods/POST/messages) или [PUT /messages](/docs-api/methods/PUT/messages) в параметре `attachments.payload.token`

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

 > После загрузки файлы хранятся до тех пор, пока не будут удалены из чата или канала, в который были отправлены 

 Подробные сценарии и примеры загрузки разных типов медиа смотрите [в разделе «Отправка сообщений с медиафайлами»](/docs-api/use-cases/sending-messages/media) 

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

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

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

В ответ на текущий запрос `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`, которое вернулось [в ответе](/docs-api/methods/POST/uploads#Результат) на запрос `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`, которое вернулось [в ответе](/docs-api/methods/POST/uploads#Результат) на запрос `POST /uploads`

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

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

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

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

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

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

## Авторизация

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

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на [платформе](https://business.max.ru/self) в разделе **Чат-боты**. Выберите необходимого бота и нажмите **⋮** → **Настройки** → значок копирования справа от поля с токеном

Если вы верифицировали профиль и создали бота в [мини-приложении «MAX для бизнеса»](https://max.ru/business_bot?startapp), получить токен можно там же или в [боте «MAX для бизнеса»](https://max.ru/business_bot) с помощью команды **Получить токен**

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

## Параметры

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

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

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

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

## HTTP-коды ответов

| Код | Описание |
| --- | --- |
| `200` | Возвращает URL для загрузки вложения и токен для загрузки медиафайла |
| `401` | Ошибка авторизации. Токен `access_token` указан некорректно или недействителен |
| `500` | Внутренняя ошибка сервера |

Подробнее о форматах ответа и кодах ошибок — [на странице «Общее описание»](/docs-api/#Результат%20выполнения%20запроса)

## Результат

URL для загрузки медиафайла. Срок жизни ссылки не ограничен
Токен для отправки медиафайла во вложении к сообщению с помощью [POST /messages](/docs-api/methods/POST/messages) или [PUT /messages](/docs-api/methods/PUT/messages)

