Перейти к содержимому

Документация API

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

Обновлено

Версионируемый REST API: загрузите файл частями, отправьте его на выбранные хостинги — и все копии соберутся на одной странице с живым статусом.

Базовый URL
https://api.mirroruploadx.com/api/v1
Аутентификация
x-api-key: mux_…
  1. 1Откройте сеанс

    POST /api/v1/upload-sessions

    filename + sizeBytes; получите sessionId и chunkSize

  2. 2Отправьте части

    PATCH /api/v1/upload-sessions/{id}/chunks

    сырые байты по порядку; ответ, завершающий файл, содержит fileId

  3. 3Распределите

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; затем опрашивайте задачу

Создайте ключ на странице API-ключи. Полное пошаговое описание с кодом — в разделе Загрузка и распределение.

Аутентификация

Создайте ключ на странице API-ключи в своей панели. Полный ключ (он начинается с mux_) показывается только один раз, поэтому сразу сохраните его. Передавайте его в заголовке x-api-key в каждом запросе; Authorization: Bearer mux_… принимается точно так же — для клиентов, которые умеют работать только с bearer-токенами.

У ключей есть права (scopes): ключ даёт доступ только к эндпоинтам, которые покрывают его права, а вызов с неподходящими правами возвращает 403 INSUFFICIENT_SCOPE с указанием нужного права в сообщении. Настройки аккаунта, управление ключами и вебхуки с API-ключом недоступны вовсе (API_KEY_NOT_ALLOWED).

ПравоДоступ
upload:writeСеансы загрузки (создание, части, завершение, отмена), ваша квота загрузок, приостановка или изменение автоматического распределения загрузки (hold-distribution, distribution-intent), загрузка по URL, запуск распределения
file:readСписок файлов, сведения о файле, статус зеркал и задач
file:writeНастройки доступа к файлу
file:deleteУдаление файла и его зеркал

Эндпоинты

Всё, к чему есть доступ у API-ключа, плюс публичные эндпоинты, которым ключ не нужен. Если в столбце прав указаны два права, достаточно любого из них. Схемы запросов и ответов для каждого — в справочнике API.

МетодПутьПравоЧто делает
POST/api/v1/upload-sessionsupload:writeОткрыть сеанс загрузки (при желании — с планом распределения)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeОтправить следующую часть байтов
HEAD/api/v1/upload-sessions/{id}upload:writeС какого места продолжить: заголовок Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readСтатус сеанса: получено байтов, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readВаши лимиты загрузок, расход и незавершённые сеансы
POST/api/v1/upload-sessions/{id}/completeupload:writeЗавершить загрузку, финальный ответ на которую потерялся (безопасно повторять)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeНе дать отложенному распределению запуститься самостоятельно
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeЗаменить план распределения загрузки
DELETE/api/v1/upload-sessions/{id}upload:writeОтменить незавершённую загрузку и освободить её место
POST/api/v1/remote-uploadsupload:writeЗагрузить файлы по ссылкам http(s) в ваш аккаунт
POST/api/v1/mirror-tasks/startupload:writeОтправить файл на выбранные хостинги
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readСтатус задачи, каждый хостинг и ссылка на файл (shareTakenDown отмечает удалённую страницу)
GET/api/v1/filesfile:readСписок ваших файлов (пагинация курсором, поиск, фильтры)
GET/api/v1/files/{id}file:readОдин файл: размер, контрольная сумма, задача, настройки доступа, статистика
GET/api/v1/files/{id}/mirrorsfile:readВсе копии файла: хостинг, ссылка, состояние, клики
PATCH/api/v1/files/{id}/sharefile:writeПароль ссылки, срок действия, видимость
DELETE/api/v1/files/{id}file:deleteУдалить файл и (по умолчанию) его копии на хостингах
GET/api/v1/platformнет (публичный)Текущие лимиты: максимальный файл, хостингов на файл, ограничения загрузки по URL
GET/api/v1/providersнет (публичный)Каталог хостингов со слагами, которые передаются в providerSlugs
GET/api/v1/providers/statusнет (публичный)Измеренная доля успешных загрузок по каждому хостингу
GET/api/v1/stats/publicнет (публичный)Итоги платформы за последние 30 дней: файлы, работающие зеркала, доля успеха

Загрузка файла и его распределение

  1. Откройте сеанс с помощью POST /api/v1/upload-sessions. Поля filename и sizeBytes (точная длина в байтах) обязательны; mimeType и UUID idempotencyKey необязательны — повтор запроса с тем же ключом возвращает существующий сеанс, а не открывает второй. Ответ содержит data.sessionId (не id) и data.chunkSize.
  2. Отправьте байты с помощью PATCH /api/v1/upload-sessions/{id}/chunks: сырые байты, тип содержимого application/offset+octet-stream, начальная позиция части — в заголовке upload-offset. Части отправляются по порядку или с опережением не более чем на maxChunksAhead частей; при отправке по порядку используйте data.uploadedBytes из каждого ответа как следующее смещение. Отправляйте части по chunkSize байтов; каждая часть, кроме последней, должна быть не меньше 5 MiB, а у загрузки может быть не более 10 000 частей. Ответ, завершающий файл, содержит data.fileId. Для большей скорости можно держать в полёте 2–3 части одного файла. Первую часть отправьте отдельно; её ответ сообщает реальное значение data.maxChunksAhead (4, если первая часть была целым срезом размером chunkSize; 0 — только по порядку). Если первая часть была целым срезом chunkSize, каждая следующая часть тоже должна им быть (по порядку или с опережением): она начинается с позиции, кратной chunkSize, и имеет размер ровно chunkSize байтов (последняя — остаток файла). Часть, отправленная с опережением относительно uploadedBytes, должна быть таким срезом и начинаться не дальше чем на data.maxChunksAhead частей вперёд, иначе она получит 409 CHUNK_MISALIGNED или 409 CHUNK_OUT_OF_WINDOW. uploadedBytes учитывает только байты, полученные без пропусков, а ответ с fileId получает та часть, которая завершает файл. Повторная отправка уже полученной части — безвредный успех.
  3. Распределите с помощью POST /api/v1/mirror-tasks/start: поля fileId и providerSlugs обязательны (слаги берутся из GET /api/v1/providers). Необязательные: minSuccess (по умолчанию 1 — сколько хостингов должны принять файл, чтобы задача не завершилась ошибкой; статус completed ставится, только если файл приняли и все остальные хостинги, иначе — partially_completed. Хостинги, отклоняющие этот тип файла, не учитываются), sharePassword, expiresInDays или expiresAt. Ответ содержит uploadJobId, taskCount, shareSlug, alreadyStarted и skipped[] — хостинг, который не может принять этот файл, пропускается, а не считается ошибкой, поэтому читайте skipped[] (причины перечислены ниже). Сейчас максимум хостингов на один файл — 50.
  4. Дождитесь завершения, опрашивая GET /api/v1/mirror-tasks/{uploadJobId} раз в несколько секунд, пока data.terminal не станет true. В ответе перечислены все хостинги в tasks[] (providerSlug, status, mirrorUrl, errorCode) и ссылка на файл в data.shareUrl. data.shareTakenDown равно true, если страница файла была удалена и больше не открывается.

Сейчас максимальный принимаемый размер файла — 5,00 GB.

bash, нужен jq

set -euo pipefail
API=https://api.mirroruploadx.com
FILE=clip.mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')

# 1. Open an upload session
SESSION_JSON=$(curl -sS --fail-with-body -X POST "$API/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"filename":"clip.mp4","sizeBytes":'"$SIZE"',"mimeType":"video/mp4"}')
SESSION=$(echo "$SESSION_JSON" | jq -r .data.sessionId)
CHUNK=$(echo "$SESSION_JSON" | jq -r .data.chunkSize)

# 2. Send the bytes in order, one chunk per request
OFFSET=0
while [ "$OFFSET" -lt "$SIZE" ]; do
  dd if="$FILE" of=part.bin bs="$CHUNK" skip=$((OFFSET / CHUNK)) count=1 status=none
  REPLY=$(curl -sS --fail-with-body -X PATCH "$API/api/v1/upload-sessions/$SESSION/chunks" \
    -H "x-api-key: $MUX_API_KEY" \
    -H "upload-offset: $OFFSET" \
    -H "content-type: application/offset+octet-stream" \
    --data-binary @part.bin)
  OFFSET=$(echo "$REPLY" | jq -r .data.uploadedBytes)
done
FILE_ID=$(echo "$REPLY" | jq -r .data.fileId)

# 3. Distribute to the hosts you pick
JOB=$(curl -sS --fail-with-body -X POST "$API/api/v1/mirror-tasks/start" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"fileId":"'"$FILE_ID"'","providerSlugs":["gofile","pixeldrain"],"minSuccess":1}' \
  | jq -r .data.uploadJobId)

# 4. Poll until the job is terminal, then print the share link
until curl -sS --fail-with-body "$API/api/v1/mirror-tasks/$JOB" \
        -H "x-api-key: $MUX_API_KEY" > job.json \
      && [ "$(jq -r .data.terminal job.json)" = "true" ]; do
  sleep 5
done
jq -r '.data.status, .data.shareUrl' job.json

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

Открытие сеанса отвечает 201. Каждая часть, кроме последней, отвечает { uploadedBytes, completed: false, expiresAt }; последняя возвращает файл. distribution присутствует, только если вы передали план при открытии сеанса (см. ниже).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (завершает файл) → 200
{
  "success": true,
  "data": {
    "uploadedBytes": 10485760,
    "completed": true,
    "fileId": "…",
    "scan": "skipped",
    "distributable": true,
    "distribution": {
      "started": true,
      "uploadJobId": "…",
      "taskCount": 2,
      "shareSlug": "…",
      "skipped": []
    }
  }
}
POST /mirror-tasks/start → 202
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "taskCount": 2,
    "shareSlug": "…",
    "skipped": [],
    "alreadyStarted": false
  }
}
GET /mirror-tasks/{uploadJobId} → 200
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "status": "completed",
    "terminal": true,
    "shareSlug": "…",
    "shareUrl": "https://mirroruploadx.com/f/…",
    "shareTakenDown": false,
    "minSuccess": 1,
    "scan": "skipped",
    "tasks": [
      {
        "provider": "Gofile",
        "providerSlug": "gofile",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://gofile.io/d/…",
        "mirrorHidden": false
      },
      {
        "provider": "Pixeldrain",
        "providerSlug": "pixeldrain",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://pixeldrain.com/u/…",
        "mirrorHidden": false
      }
    ]
  }
}

Первый успешный вызов start отвечает 202; повторный вызов для уже идущей задачи отвечает 200 с alreadyStarted: true. Если ссылка хостинга по правилам скрыта, mirrorUrl равно null, а mirrorHidden — true; страница файла всё равно его показывает.

Обойдитесь без второго вызова

Передайте distribution при открытии сеанса — и сервер начнёт распределение, как только файл будет загружен целиком. Проверьте data.distribution в ответе, завершающем файл: started: true означает, что задача поставлена в очередь (uploadJobId, shareSlug). При started: false и deferred: true в очередь пока намеренно ничего не поставлено — см. ниже. При started: false без deferred загрузка всё равно прошла успешно, но распределение не удалось запустить (причина — в error): вызовите POST /api/v1/mirror-tasks/start с fileId. error вместе с deferred: true означает временный сбой (например, все хостинги перегружены или на обслуживании): не вызывайте start и не загружайте файл заново — сервер сам повторит запуск распределения начиная с autoStartAt (до 5 попыток). Чтобы остановить это, вызовите hold-distribution.

curl
curl -sS -X POST "https://api.mirroruploadx.com/api/v1/upload-sessions" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "sizeBytes": 10485760,
    "mimeType": "video/mp4",
    "distribution": { "providerSlugs": ["gofile", "pixeldrain"], "minSuccess": 1 }
  }'
# The reply to the final chunk then carries data.distribution:
#   { "started": true, "uploadJobId": "…", "taskCount": 2, "shareSlug": "…", "skipped": [] }
#   or { "started": false, "error": { "code": "…", "message": "…" } }

Добавьте deferred: true в distribution, чтобы получить отсрочку: финальный ответ — { started: false, deferred: true, autoStartAt }, и сервер сам запустит распределение в autoStartAt (примерно через 2 минуты), если вы не вызовете start раньше. Чтобы остановить автоматический запуск, вызовите POST /api/v1/upload-sessions/{id}/hold-distribution (без тела; autoStartAt становится null, и вы запускаете распределение сами). Чтобы вместо этого изменить план, вызовите PUT /api/v1/upload-sessions/{id}/distribution-intent с теми же полями, что и в distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): он заменяет план и снимает приостановку, а если загрузка уже завершена, автоматический запуск переносится не ранее чем на 2 минуты после вызова. Если распределение уже началось, оба вызова отвечают 200, а distribution-intent возвращает alreadyStarted: true.

Запустите в течение 30 минут. Если загрузка завершена, а распределение не запущено, наша копия файла удаляется через 30 минут (если план распределения ещё ждёт, пока хостинги станут доступны, — не позднее чем через 72 часа; на загрузки по URL это не распространяется). После этого start и distribution-intent отвечают 409 SOURCE_GONE, и файл придётся загрузить заново.

Если финальный ответ потерялся

Вызовите GET /api/v1/upload-sessions/{id}: наличие fileId означает, что файл существует; finalizable: true означает, что все байты дошли и POST /api/v1/upload-sessions/{id}/complete завершит загрузку. Этот вызов безопасно повторять, и он никогда не создаёт второй файл. Несовпадающее смещение получает 409 CHUNK_OFFSET_CONFLICT — отправьте HEAD на сеанс и продолжите с его заголовка Upload-Offset. Повторный вызов start для идущей задачи не является ошибкой: вы получите 200 с alreadyStarted: true.

Загрузка по URL

POST /api/v1/remote-uploads принимает { "urls": [...] } и сам скачивает каждый файл (право upload:write). Загружаются только ссылки http и https, адреса частных сетей отклоняются, а число переходов по редиректам ограничено. Один запрос содержит не более 10 URL (значение возвращает GET /api/v1/platform); более длинные списки разбивайте.

Лимит размера на файл зависит от источника. Если источник сообщает размер файла, каждый файл может весить до 5,00 GB (limits.remoteUploadPassthroughMaxBytes); если нет — до 100,0 MB (limits.remoteUploadMaxBytes). Имя файла берётся из заголовка Content-Disposition источника, если он его отправляет; имени без расширения расширение добавляется по типу файла.

Запрос ждёт, пока файлы скачиваются. Если соединение оборвётся раньше, файл всё равно попадёт в ваш аккаунт — найдите его через GET /api/v1/files. Затем каждый fileId распределяется через POST /api/v1/mirror-tasks/start, как описано выше.

Если временное хранилище заполнено, весь запрос получает 503 TEMPORARILY_UNAVAILABLE с details.reason: "staging_full" и заголовком Retry-After. Если не поместился только один URL, соответствующая запись в results[] содержит ok: false и тот же код; у результата по отдельному URL заголовка нет, поэтому время ожидания в секундах указано в details.retryAfter.

curl -sS -X POST "https://api.mirroruploadx.com/api/v1/remote-uploads" \
  -H "x-api-key: $MUX_API_KEY" -H "content-type: application/json" \
  -d '{"urls":["https://example.com/files/archive.zip"]}'

# One result per URL, in order. A failed URL does not fail the batch:
# {"success":true,"data":{"results":[
#   {"url":"https://example.com/files/archive.zip","ok":true,
#    "fileId":"…","scan":…,"distributable":true}
# ]}}
# or {"url":"…","ok":false,"code":"REMOTE_TOO_LARGE","error":"…"}
#
# Then distribute each fileId with POST /api/v1/mirror-tasks/start.

Управление файлами

После загрузки файлы остаются в вашем аккаунте. Получите их список через GET /api/v1/files (limit до 100; для следующей страницы передайте nextCursor из ответа как cursor, q ищет по имени). GET /api/v1/files/{id} возвращает один файл с его задачей, настройками доступа и статистикой просмотров; GET /api/v1/files/{id}/mirrors перечисляет все копии с их ссылками, состоянием и кликами.

PATCH /api/v1/files/{id}/share (право file:write) меняет страницу файла: password (4–128 символов, null удаляет пароль — он никогда не возвращается, только passwordProtected), expiresAt (дата ISO, null — бессрочно), visibility и hideDownloadCount. Передавайте только те поля, которые хотите изменить. DELETE /api/v1/files/{id} (право file:delete) удаляет файл и ставит его копии на хостингах в очередь на удаление; добавьте ?keepMirrors=true, чтобы их сохранить. Некоторые хостинги не поддерживают удаление, поэтому копия может там остаться.

bash, нужен jq; задайте FILE_ID

API=https://api.mirroruploadx.com
H="x-api-key: $MUX_API_KEY"

# List your files, newest first (20 per page; pass ?cursor=<nextCursor> for more)
curl -sS "$API/api/v1/files?limit=20" -H "$H" | jq '.data.items[] | {id, name, mirrorCount, shareSlug}'

# One file, then every copy of it
curl -sS "$API/api/v1/files/$FILE_ID" -H "$H"
curl -sS "$API/api/v1/files/$FILE_ID/mirrors" -H "$H" | jq '.data.mirrors[] | {providerSlug, status, url}'

# Share settings: a password and an expiry date (null removes either)
curl -sS -X PATCH "$API/api/v1/files/$FILE_ID/share" -H "$H" -H "content-type: application/json" \
  -d '{"password":"correct-horse","expiresAt":"2026-12-31T23:59:59Z"}'

# Delete the file and its copies on hosts (?keepMirrors=true keeps the copies)
curl -sS -X DELETE "$API/api/v1/files/$FILE_ID" -H "$H"
DELETE /files/{id} → 200
{
  "success": true,
  "data": {
    "stagingDeleted": true,
    "mirrorsQueued": true,
    "mirrorsPurgeDeferred": false,
    "note": "File removed. Copies on providers are being deleted; some may remain on providers that do not support deletion."
  }
}

Вебхуки

Добавьте эндпоинт на странице Вебхуки. URL должен использовать https://; его секрет подписи (whsec_…) показывается один раз, при создании. Эндпоинт без выбранных событий получает все события.

СобытиеКогда
upload.completedФайл приняли все хостинги, и не меньше minSuccess — хостинги, отклонившие этот файл (rejected) или отменённые, не учитываются
upload.partially_completedФайл приняли не менее minSuccess хостингов, но хотя бы один другой хостинг завершился ошибкой
upload.failedФайл приняли меньше minSuccess хостингов (minSuccess 0 считается как 1)
upload.quarantinedАнтивирусная проверка пометила файл (только если проверка включена)
provider.upload_succeededОдин хостинг принял файл — отправляется один раз для каждого хостинга
provider.upload_failedОдин хостинг сдался — отправляется один раз для каждого хостинга
webhook.testВы нажали «Проверить» на странице «Вебхуки»

Каждая доставка — это один POST с телом JSON и заголовками X-MUX-Event и X-MUX-Signature. Любой ответ 2xx в течение 10 секунд считается доставкой; редиректы не выполняются. Неудачная доставка (сетевая ошибка, тайм-аут, 408, 425, 429 или 5xx) повторяется через 1, 5 и 30 минут с тем же телом; другие 4xx и редиректы не повторяются. Каждая попытка содержит X-MUX-Delivery-Attempt (1–4) и новую подпись, поэтому убирайте дубли по телу. Порядок доставки не гарантируется (повторённое событие может прийти после более нового); прежде чем действовать, сравнивайте data и createdAt. Чтобы наверстать пропущенное, используйте GET /api/v1/mirror-tasks/{uploadJobId}. После 15 доставок подряд, последняя попытка которых не удалась, или часа сбоев без единого успеха эндпоинт приостанавливается; его повторное включение сбрасывает счётчик. Доставка webhook.test (кнопка «Проверить») отправляется один раз, с X-MUX-Delivery-Attempt: 1, и никогда не повторяется.

Тело
{
  "event": "provider.upload_succeeded",
  "createdAt": "2026-09-25T12:00:00.000Z",
  "data": {
    "uploadJobId": "…",
    "fileId": "…",
    "provider": "gofile",
    "providerName": "Gofile",
    "status": "succeeded",
    "mirrorUrl": "https://…"
  }
}

События upload.* содержат uploadJobId, fileId и status; provider.upload_failed содержит errorCode вместо mirrorUrl.

Проверка подписи

Заголовок выглядит так: t=1727265600,v1=5f2b…: t — время подписи в секундах Unix, v1 — шестнадцатеричный HMAC-SHA256 от <t>.<raw body> с ключом — секретом вашего эндпоинта. Хешируйте сырые байты ровно в том виде, в каком они получены, сравнивайте за постоянное время и отклоняйте метки времени старше 5 минут.

Express

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((kv) => {
      const i = kv.indexOf('=');
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // too old: replay
  const expected = createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest();
  const got = Buffer.from(parts.v1, 'hex');
  return got.length === expected.length && timingSafeEqual(got, expected);
}

const app = express();
// Raw bytes, not parsed JSON: the signature covers the body exactly as sent.
app.post('/hooks/mirroruploadx', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('x-mux-signature') ?? '', process.env.MUX_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const { event, data } = JSON.parse(req.body);
  console.log(event, data.uploadJobId);
  res.sendStatus(204); // any 2xx counts as delivered
});
app.listen(3000);

Лимиты запросов

Лимиты считаются по API-ключу, а не по IP-адресу. Каждый ответ ограниченного эндпоинта содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунды epoch). При превышении возвращается 429 RATE_LIMITED с заголовком Retry-After — подождите указанное число секунд. На загрузку частей выделен широкий лимит; узкие лимиты — на открытие сеансов и запуск распределения.

ГруппаЭндпоинтыНа ключОкно
Запуск загрузокPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 минута
Приём частейPATCH /api/v1/upload-sessions/{id}/chunks6001 минута
Опрос прогрессаGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 минута
Настройки распределения загрузкиPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 минута
Запуск распределенияPOST /api/v1/mirror-tasks/start301 минута
Загрузки по URLPOST /api/v1/remote-uploads2010 минут
Чтение файловGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 минута
Изменение файловPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 минута
Публичный каталогGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 минута

Это значения по умолчанию. Оператор может их изменить, поэтому источником истины всегда служат заголовки выше. Точные значения для ваших ключей и текущий расход по каждому показаны на странице API-ключи. Запросы без ключа считаются по IP-адресу и получают меньшие лимиты на запуск загрузок (10 вместо 60), приём частей (300 вместо 600), опрос прогресса (300 вместо 600), настройки распределения загрузки (60 вместо 300), запуск распределения (10 вместо 30), а те же лимиты на загрузки по URL и публичный каталог. Чтение файлов и изменение файлов — только с ключом.

Ошибки

Успешные ответы имеют вид { "success": true, "data": … }. Ошибки имеют единую форму и сопровождаются HTTP-статусом. code стабилен — ветвитесь по нему; message предназначен для людей и может меняться. details добавляется, когда есть дополнительный контекст, retryable сообщает, поможет ли повтор того же запроса, а requestId поможет нам найти ваш запрос, если вы обратитесь в поддержку.

Ошибка
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
КодHTTPПовтор?Значение
NO_TOKEN401НетAPI-ключ не передан
INVALID_API_KEY401НетКлюч неверный или отозван
INSUFFICIENT_SCOPE403НетУ ключа нет права, необходимого для этого эндпоинта
API_KEY_NOT_ALLOWED403НетЭтот эндпоинт нельзя использовать с API-ключом
EMAIL_NOT_VERIFIED403НетСначала подтвердите эл. почту аккаунта; открытые сеансы продолжают работать
SESSION_REVOKED401НетСеанс входа завершён (сброс или смена пароля, выход); войдите снова
ACCOUNT_INACTIVE403НетАккаунт заблокирован или запланирован к удалению
ACCOUNT_DISABLED401 / 409НетАккаунт заблокирован: 401 при проверке ключа, 409, если это изменилось во время выполнения запроса
ACCOUNT_PENDING_DELETION409НетАккаунт был запланирован к удалению во время выполнения запроса; ничего нового не запускается
VALIDATION_ERROR400НетТело или параметр некорректны; см. details
FILE_REJECTED400НетТип или размер файла недопустим; details.reason уточняет, что именно
TOO_MANY_MIRRORS400НетБольше хостингов, чем допускается для одного файла
NO_CONNECTED_PROVIDERS400НетКаждому выбранному хостингу нужен ваш собственный аккаунт, и ни один не подключён
PROVIDER_REJECTS_FILE400НетНи один выбранный хостинг не принимает файл такого типа или размера
NO_AVAILABLE_PROVIDERS400НетНи один из выбранных хостингов сейчас не принимает загрузки; выберите другие или попробуйте позже. `details.waiting` перечисляет хостинги, которые лишь приостановлены (например, дневной лимит, снимаемый в течение 24 часов): для них повторная попытка позже сработает, хотя `retryable` равно false
NO_VALID_PROVIDERS400НетНи одно значение providerSlugs не соответствует включённому хостингу; см. GET /api/v1/providers
INVALID_JOB_STATE400НетЗадачу нельзя запустить в её текущем состоянии
JOB_NOT_READY400НетУ файла ещё нет задачи распределения
FILE_TOO_LARGE_FOR_UPLOAD400НетФайл не помещается в 10 000 частей размера, заданного для сеанса; details.limitBytes
MISSING_OFFSET400НетЧасть отправлена без числового заголовка upload-offset
RAW_BODY_REQUIRED400НетТело части должно состоять из сырых байтов с content-type application/offset+octet-stream
TOO_MANY_URLS400НетВ одном запросе remote-uploads больше URL, чем разрешено
FILE_NOT_FOUND404НетТакого файла в вашем аккаунте нет (или он удалён)
JOB_NOT_FOUND404НетТакой задачи распределения в вашем аккаунте нет
SESSION_NOT_FOUND404НетТакого сеанса загрузки в вашем аккаунте нет
SHARE_NOT_FOUND404НетУ файла ещё нет страницы
QUOTA_EXCEEDED409НетДневной лимит или лимит одновременных загрузок; details.retryAt сообщает, когда он освободится
CHUNK_OFFSET_CONFLICT409Нетupload-offset не совпадает с полученными байтами; продолжите с HEAD
CHUNK_TOO_SMALL409НетЧасть, кроме последней, меньше 5 MiB
CHUNK_TOO_MANY_PARTS409НетБольше 10 000 частей; отправляйте части крупнее
CHUNK_MISALIGNED409НетЧасть не является целым срезом chunkSize, начинающимся с позиции, кратной chunkSize: это обязательно для части, отправленной с опережением, а если первая часть была целым срезом chunkSize, то и для каждой следующей части (по порядку или с опережением); либо часть отправлена с опережением в сеансе, который принимает части только по порядку
CHUNK_OUT_OF_WINDOW409НетЧасть начинается дальше чем на maxChunksAhead частей после uploadedBytes или вообще после него до того, как принята первая часть; отправьте её снова после предыдущих
CHUNK_EXCEEDS_DECLARED_SIZE409НетЧасть выходит за размер файла, заявленный при создании сеанса
CHUNK_EMPTY409НетВ части нет байтов
CHUNK_NOT_RECEIVABLE409НетСеанс больше не принимает данные (он завершён, отменён или истёк); откройте новый
SESSION_EXPIRED409НетСеанс загрузки истёк; откройте новый
SESSION_NOT_RECEIVABLE409НетСеанс отменён или истёк и больше не принимает изменения
SESSION_COMPLETED409НетЗагрузка уже завершена; вместо этого удалите файл
UPLOAD_INCOMPLETE409НетДошли не все байты; сначала отправьте оставшиеся части (счётчики — в details)
IDEMPOTENCY_KEY_CONFLICT409НетЭтот idempotencyKey уже используется другой загрузкой; используйте уникальный ключ для каждой загрузки
SOURCE_GONE409НетНаша копия файла уже удалена, поэтому его нельзя отправить на хостинги, на которых он ещё не пробовался; для них загрузите файл заново. Наша копия удаляется сразу после завершения задачи распределения (завершена, частично завершена или ошибка), а загрузка, распределение которой так и не запущено, удаляется через 30 минут после завершения (до 72 часов, если её план распределения ещё ждёт хостинги; кроме загрузок по URL). Повторный вызов mirror-tasks/start для завершённой задачи только с уже опробованными хостингами просто применяет настройки доступа (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409НетЗадача завершилась ошибкой, отменена или находится в состоянии, в котором распределение больше невозможно
SHARE_TAKEN_DOWN409НетСтраница файла удалена, поэтому его нельзя отправить на другие хостинги
FINALIZING409ДаДругой запрос собирает файл; повторите через несколько секунд
CONFLICT409ДаКонфликт с другим изменением, которое выполняется сейчас; повторите тот же запрос
TEMPORARILY_UNAVAILABLE503Да, после Retry-AfterСервер сейчас перегружен; повторите после задержки Retry-After. details.reason "staging_full": временное хранилище заполнено, новая загрузка не принята (Retry-After примерно 10 минут); уже идущие загрузки продолжают работать
PAYLOAD_TOO_LARGE413НетТело запроса (или одна часть) больше, чем принимает сервер
REMOTE_TOO_LARGEпо URLНетВ результате remote-uploads: файл превышает лимит загрузки по URL
RATE_LIMITED429Да, после Retry-AfterСлишком много запросов для этой группы
INTERNAL_ERROR500ДаОшибка сервера; подробности записываются в журнал и никогда не возвращаются
MAINTENANCE503Да, после Retry-AfterНовые загрузки пока приостановлены; чтение продолжает работать
UPLOADS_TEMPORARILY_UNAVAILABLE503Да, после Retry-AfterНе удалось прочитать наш счётчик загрузок; сеанс не открыт
SHUTTING_DOWN503Да, после Retry-AfterСервер перезапускается (Retry-After 5 секунд); подождите и отправьте тот же запрос снова — ничего не было обработано

Почему хостинг пропущен

Это не ошибки: они приходят в skipped[].reason успешного вызова start (и в distribution ответа, завершающего файл). Остальные хостинги всё равно получают файл. Вызов завершается ошибкой, только если ни один выбранный хостинг не может принять файл: PROVIDER_REJECTS_FILE (ни один не принимает этот файл), NO_CONNECTED_PROVIDERS (каждому нужен ваш собственный аккаунт), NO_AVAILABLE_PROVIDERS (ни один сейчас не принимает загрузки) или NO_VALID_PROVIDERS (ни один слаг не соответствует включённому хостингу).

ПричинаЗначение
UNKNOWN_PROVIDERХостинга с таким слагом нет — сверьте написание с GET /api/v1/providers
PROVIDER_DISABLEDХостинг сейчас отключён или на обслуживании
ACCOUNT_REQUIREDХостинг принимает загрузки только в ваш собственный аккаунт — подключите его на странице «Подключения»
GUEST_UPLOAD_OFFХостинг сейчас не принимает загрузки, и его нельзя подключить к аккаунту
DAILY_LIMIT_REACHEDДневной лимит хостинга для загрузок без аккаунта пока исчерпан (до 24 ч) — подключите собственный аккаунт, чтобы загружать всё равно
FILE_TOO_LARGEФайл превышает лимит размера этого хостинга
MIME_NOT_ALLOWEDХостинг не принимает этот тип файла
ALREADY_ATTEMPTEDЭтот хостинг уже пробовали для этого файла, поэтому повторно файл туда не отправляется

В справочнике API перечислены коды, которые может вернуть каждый эндпоинт.