RUEN
API · s5w

Загрузка частями

Для больших файлов: содержимое уходит частями по 4–16 МиБ, а после обрыва связи загрузка продолжается с того места, где остановилась.

Путь /v1/uploadsДоступ FULLЧасть 4–16 МиБЖивёт 24 ч с последней части

Как это работает

  1. Начать загрузку — POST /v1/uploads

    Сообщите имя и размер. Сервер проверит квоту и место на диске заранее и вернёт id загрузки и рекомендуемый размер части chunkSize.

  2. Отправить части — PATCH /v1/uploads/{id}

    Тело запроса — байты части, заголовок Upload-Offset — с какого байта она начинается.

  3. Завершить — POST /v1/uploads/{id}/complete

    Сервер проверяет хеш, обрабатывает картинку, если просили, и создаёт файл.

POST /v1/uploads

json
{
  "name": "video.mp4",
  "size": 734003200,
  "folder": "media",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
Поле Описание
name Обязательно. Имя файла.
size Обязательно. Размер в байтах.
folder Имя папки. Проверяется сразу, а не после загрузки: если её нет — 422.
sha256 Хеш содержимого, 64 hex-символа. Включает дедупликацию и проверку целостности.
format, quality, maxWidth, maxHeight Обработка картинки, как в POST /v1/files.

Возвращает 201:

json
{
  "id": "9c10a01c-a293-438c-88ba-b48181b9cd67",
  "name": "video.mp4",
  "size": 734003200,
  "offset": 0,
  "chunkSize": 8388608,
  "expiresAt": "2026-11-08T17:10:44+00:00",
  "file": null
}

Дедупликация по sha256

Если sha256 передан и такое содержимое в бакете уже есть, загружать ничего не нужно: файл создаётся сразу, в ответе chunkSize: 0 и готовый file с deduplicated: true.

Хеш и обработка картинки

Хеш считается от исходных байтов, а при опциях обработки хранится результат. Поэтому с format, quality, maxWidth или maxHeight поиск по хешу не выполняется: загрузка идёт обычным путём, а хеш проверяется при завершении.

PATCH /v1/uploads/{id}

Добавляет часть. Тело — байты, Upload-Offset — смещение начала части.

bash
curl -X PATCH -H "Authorization: Bearer <токен>" \
  -H "Upload-Offset: 0" \
  -H "Content-Type: application/offset+octet-stream" \
  --data-binary @part-0 \
  http://<хост>:9090/v1/uploads/<id>

Возвращает загрузку с новым offset.

  • Часть — от 4 до 16 МиБ. Меньше можно только последнюю.
  • Upload-Offset не совпал с тем, что уже получено, — 409. Узнайте настоящее смещение через GET и продолжите с него.
  • Часть выходит за объявленный size — 413.

GET /v1/uploads/{id}

Состояние загрузки: сколько байт уже получено (offset). С этого запроса начинается продолжение после обрыва.

POST /v1/uploads/{id}/complete

Завершает загрузку и создаёт файл. Возвращает 201 и файл.

  • Получено не всё — 409 с числом полученных байт.
  • Хеш не совпал с sha256 — 422.
  • Любая ошибка завершения удаляет загрузку — хеш не совпал, квота кончилась (413), папку удалили, картинку нельзя обработать (422, 501): загружать придётся заново. Исключение — 409 «получено не всё»: загрузка остаётся, её можно дослать.

DELETE /v1/uploads/{id}

Отменяет загрузку и удаляет полученное. Возвращает 204.

Брошенные загрузки

Незавершённая загрузка истекает через 24 часа после последней принятой части (expiresAt; каждая часть продлевает срок), и уборщик удаляет её в течение часа. Отменять вручную нужно, только чтобы сразу освободить место.