Начать загрузку по частям

POST/api/v1/uploads/resumable

Доступ: Ключ API
Право: content:write

Фиксирует размер файла, хеши его частей по 2 МБ и отпечаток. У аккаунта может быть до 10 незавершённых загрузок, каждая живёт 24 часа. Повтор с тем же Idempotency-Key и теми же байтами возвращает ту же загрузку.

Пример запроса

curl -X POST "https://lac.pics/api/v1/uploads/resumable" \
  -H "Authorization: Bearer lac_api_YOUR_KEY" \
  -H "Idempotency-Key: 6c1e0f7a-3b2d-4e8f-9a01-5d4c3b2a1f0e" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "cmf8a1x2k0000q7lh3v9w2e4d",
  "filename": "recording.mp4",
  "size": 4194304,
  "chunkSize": 2097152,
  "chunkHashes": [
    "9d1e6b0c7a52f3e84b1c0d9a7e6f5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a",
    "0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"
  ],
  "fingerprint": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
}'

Параметры

Заголовки

X-Lacuna-Accountstring
Необязательно: id аккаунта, которому должна принадлежать загрузка. Другой аккаунт — 409 до чтения состояния и данных.
Idempotency-Keystring · uuidобязательный
UUID, один на файл: повтор с тем же ключом и теми же байтами вернёт ту же загрузку.

Тело запроса

application/jsonобязательный

accountIdstringобязательный
id аккаунта (user.id из GET /account), к которому привязана загрузка.
длина 1–128
filenamestringобязательный
Имя файла. Хранится без управляющих символов и разделителей пути, до 180 символов с сохранением расширения.
длина 1–1 024
sizeinteger · int64обязательный
Размер файла в байтах, не больше limits.maxUploadBytes (413 UPLOAD_TOO_LARGE): самый большой лимит тарифа или предел сервера 4 ГБ, если у тарифа лимита на файл нет (params.ceiling = server). Первая часть показывает тип: другой формат (400 UPLOAD_FORMAT_UNSUPPORTED) или файл больше лимита своего типа (413 IMAGE_TOO_LARGE / VIDEO_TOO_LARGE) сразу отменяет загрузку.
1–4 294 967 296
chunkSizeintegerобязательный
Размер части: 2 097 152 байта (2 МБ).
значения: 2097152
chunkHashesмассив stringобязательный
SHA-256 каждой части по порядку, в шестнадцатеричном виде.
1–2 048 элементов
fingerprintstringобязательный
SHA-256 строки UTF-8 lacuna-resumable-v1\n{size}\n2097152\n{хеши частей через \n}\n. Имя файла и дата изменения в отпечаток не входят.
шаблон ^[a-f0-9]{64}$

Ответы

200ГотовоResumableUpload
- idstring · uuidобязательный
  id загрузки.
- statestringобязательный
  Состояние: UPLOADING, COMPLETING, COMPLETED, CANCELLED или EXPIRED.
  значения: "UPLOADING" "COMPLETING" "COMPLETED" "CANCELLED" "EXPIRED"
- filenamestringобязательный
  Имя файла. Хранится без управляющих символов и разделителей пути, до 180 символов с сохранением расширения.
- sizeinteger · int64обязательный
  Размер в байтах.
  1–4 294 967 296
- chunkSizeintegerобязательный
  Размер части: 2 097 152 байта (2 МБ).
  значения: 2097152
- chunkCountintegerобязательный
  Число частей.
  1–50
- fingerprintstringобязательный
  SHA-256 строки UTF-8 lacuna-resumable-v1\n{size}\n2097152\n{хеши частей через \n}\n. Имя файла и дата изменения в отпечаток не входят.
  шаблон ^[a-f0-9]{64}$
- receivedмассив integerобязательный
  Номера подтверждённых частей.
  без повторов
- receivedBytesinteger · int64обязательный
  Подтверждено байт.
  0–4 294 967 296
- expiresAtstring · date-timeобязательный
  Когда незавершённая загрузка истечёт.
- contentContentобязательныйили null
  Готовый файл после завершения; иначе null.
  Content 40 полей
  - idstringобязательный
    id файла.
  - titlestringобязательный
    Название.
  - tagsмассив stringобязательный
    Теги.
    до 10 элементов · без повторов
  - originalNamestring
    Исходное имя файла.
  - typestringобязательный
    IMAGE, VIDEO, PASTE или FOLDER — папка с кодом.
    значения: "IMAGE" "VIDEO" "PASTE" "FOLDER"
  - mimestringобязательный
    MIME-тип сохранённого файла.
  - pasteFormatstringили null
    Формат заметки.
    значения: "plain" "markdown" "code"
  - pasteLanguagestringили null
    Язык подсветки заметки.
  - folderFilesintegerили null
    У папки с кодом — сколько в ней файлов; у остального null.
    от 1
  - revisionintegerобязательный
    Ревизия текста заметки для правки.
    от 1
  - accessVersionintegerобязательный
    Share access version: 1 for a new file, raised by every change of visibility, password or one-time. From 2 on, url carries it as ?v= so messengers build a fresh link card instead of the one they kept for the previous access.
    от 1
  - sizeinteger · int64обязательный
    Размер в байтах.
  - visibilitystringобязательный
    Доступ: private, unlisted или public.
    значения: "private" "unlisted" "public"
  - allowDownloadbooleanобязательный
    Показывается ли кнопка скачивания.
  - passwordProtectedbooleanобязательный
    Есть ли пароль.
  - oneTimebooleanобязательный
    Одноразовая ли ссылка.
  - consumedAtstring · date-timeили null
    Когда одноразовая ссылка была открыта.
  - readExpiresAtstring · date-timeили null
    До какого момента открывший одноразовую ссылку может смотреть файл.
  - readMaxExpiresAtstring · date-timeили null
    Самый поздний конец доступа по одноразовой ссылке.
  - hasVideoTextboolean
    Есть ли у видео субтитры или расшифровка.
  - videoTextRevisioninteger
    Ревизия текста видео.
    0–2 147 483 647
  - viewsintegerобязательный
    Засчитанные открытия гостями, без повторов в пределах доступа зрителя (обычно сутки). Просмотры владельца не считаются.
    от 0
  - viewLimitintegerили null
    Лимит просмотров (Pro) или null.
    1–1 000 000
  - viewLimitReachedAtstring · date-timeили null
    Когда лимит просмотров исчерпан; null, пока просмотры есть или лимита нет.
  - mediaStatusstring
    Обработка: PROCESSING — идёт, READY — готово, FAILED — не удалась. Воспроизведение и превью — после READY; оригинал владелец может скачать и раньше, с ?download=1.
    значения: "PROCESSING" "READY" "FAILED"
  - mediaErrorstringили null
    Причина, если обработка не удалась.
  - widthintegerили null
    Ширина в пикселях.
  - heightintegerили null
    Высота в пикселях.
  - durationMsintegerили null
    Длительность видео в миллисекундах.
  - videoCodecstringили null
    Кодек видео.
  - hasAudioboolean
    Есть ли звук.
  - previewUrlstringили null
    Адрес зашифрованного превью; доступ — как у самого файла.
  - expiresAtstring · date-timeили null
    Когда файл и ссылка перестанут работать; null — без срока.
  - createdAtstring · date-timeобязательный
    Когда создан.
  - urlstring · uriобязательный
    Ссылка на страницу файла.
  - mediaUrlstringобязательный
    Адрес самого файла.
  - moderationHoldstringили null
    Автопроверка: review — скрыт до решения модератора, blocked — скрыт модератором. Другие видят такой файл как приватный.
    значения: "review" "blocked"
  - favoriteboolean
    В избранном (в списках).
  - ownedboolean
    Свой файл (в списках).
  - authorobject
    Автор.
    3 поля
    idstring
    id автора.
    usernamestring
    Никнейм.
    namestring
    Имя.
400Некорректный запросUPLOAD_FORMAT_UNSUPPORTED
401Нужен действующий ключ
403Нет права или функции тарифа
404Не найдено
408Тело запроса перестало приходить
409Конфликт
410Файл удалён или истёк
413Слишком большой файл или нет местаIMAGE_TOO_LARGE UPLOAD_TOO_LARGE VIDEO_TOO_LARGE
429Слишком много запросов
500Сбой на сервере
503Сервис занят или недоступен

Пример ответа

200 · application/json

{
  "id": "Xq3u9RkT0bLmA7cV2pWz1eFy",
  "state": "COMPLETED",
  "filename": "recording.mp4",
  "size": 4194304,
  "chunkSize": 2097152,
  "chunkCount": 2,
  "fingerprint": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "received": [
    0,
    1
  ],
  "receivedBytes": 4194304,
  "expiresAt": "2026-09-28T09:30:00.000Z",
  "content": {
    "id": "Xq3u9RkT0bLmA7cV2pWz1eFy",
    "title": "capture",
    "tags": [
      "release"
    ],
    "originalName": "capture.png",
    "type": "IMAGE",
    "mime": "image/png",
    "pasteFormat": null,
    "pasteLanguage": null,
    "folderFiles": 1,
    "revision": 1,
    "accessVersion": 1,
    "size": 482133,
    "visibility": "unlisted",
    "allowDownload": true,
    "passwordProtected": false,
    "oneTime": false,
    "consumedAt": null,
    "readExpiresAt": null,
    "readMaxExpiresAt": null,
    "hasVideoText": false,
    "videoTextRevision": 0,
    "views": 3,
    "viewLimit": null,
    "viewLimitReachedAt": null,
    "mediaStatus": "READY",
    "mediaError": null,
    "width": 1920,
    "height": 1080,
    "durationMs": null,
    "videoCodec": null,
    "hasAudio": false,
    "previewUrl": null,
    "expiresAt": null,
    "createdAt": "2026-09-27T09:30:00.000Z",
    "url": "https://lac.pics/s/Xq3u9RkT0bLmA7cV2pWz1eFy",
    "mediaUrl": "/api/media/Xq3u9RkT0bLmA7cV2pWz1eFy",
    "moderationHold": null,
    "favorite": false,
    "owned": true,
    "author": {
      "id": "cmf8a1x2k0000q7lh3v9w2e4d",
      "username": "alex",
      "name": "Alex"
    }
  }
}

Коды ошибок

Код	Статус	Текст
`UPLOAD_FORMAT_UNSUPPORTED`	400	Поддерживаются статичные PNG, JPEG, WebP, AVIF, а также MP4 и WebM. Изображение — до 40 мегапикселей.
`IMAGE_TOO_LARGE`	413	Изображение больше допустимого размера. Сожми его или уменьши разрешение.
`UPLOAD_TOO_LARGE`	413	Файл больше допустимого размера.
`VIDEO_TOO_LARGE`	413	Видео больше допустимого размера. Сожми его в «Сжатии» — в кабинете lacuna или в приложении для Windows.

Ответы любого метода с ключом — неверный или истёкший ключ, нет права, частые запросы — в разделе Ошибки.