Lewati ke konten

Dokumentasi API

Unggah file sekali, kirim ke host file pilihan Anda, dan dapatkan kembali satu tautan berbagi — dari kode Anda sendiri.

Diperbarui

REST API berversi: unggah file per bagian (chunk), kirim ke host pilihan Anda, dan setiap salinan dikumpulkan di satu halaman berbagi dengan status langsung.

URL dasar
https://api.mirroruploadx.com/api/v1
Autentikasi
x-api-key: mux_…
  1. 1Buka sesi

    POST /api/v1/upload-sessions

    filename + sizeBytes; dapatkan sessionId dan chunkSize

  2. 2Kirim chunk

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

    byte mentah secara berurutan; balasan yang melengkapi file berisi fileId

  3. 3Distribusikan

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; lalu lakukan polling pada pekerjaan

Buat kunci di halaman Kunci API. Panduan lengkap beserta kode ada di Unggah dan distribusikan.

Autentikasi

Buat kunci di halaman Kunci API pada dasbor Anda. Kunci lengkap (diawali mux_) hanya ditampilkan sekali, jadi segera simpan. Kirimkan di header x-api-key pada setiap permintaan; Authorization: Bearer mux_… juga diterima dengan cara yang sama untuk klien yang hanya mendukung bearer token.

Kunci memiliki lingkup: kunci hanya dapat menjangkau endpoint yang dicakup lingkupnya, dan panggilan dengan lingkup yang salah mengembalikan 403 INSUFFICIENT_SCOPE dengan lingkup yang diperlukan di dalam pesannya. Pengaturan akun, pengelolaan kunci, dan webhook sama sekali tidak dapat dijangkau dengan kunci API (API_KEY_NOT_ALLOWED).

LingkupMenjangkau
upload:writeSesi unggah (buat, chunk, selesaikan, batalkan), kuota unggah Anda, menahan atau mengubah distribusi otomatis sebuah unggahan (hold-distribution, distribution-intent), unggah dari URL, memulai distribusi
file:readDaftar file, detail file, status mirror dan pekerjaan
file:writePengaturan berbagi pada file
file:deleteMenghapus file beserta mirror-nya

Endpoint

Semua yang dapat dijangkau kunci API, ditambah endpoint publik yang tidak memerlukan kunci. Jika kolom lingkup mencantumkan dua lingkup, salah satunya sudah cukup. Skema permintaan dan respons masing-masing ada di referensi API.

MetodePathLingkupFungsinya
POST/api/v1/upload-sessionsupload:writeMembuka sesi unggah (opsional dengan rencana distribusi)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeMengirim chunk byte berikutnya
HEAD/api/v1/upload-sessions/{id}upload:writeTitik untuk melanjutkan: header Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readStatus sesi: byte yang diterima, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readBatas unggah, pemakaian, dan sesi Anda yang belum selesai
POST/api/v1/upload-sessions/{id}/completeupload:writeMenyelesaikan unggahan yang balasan terakhirnya hilang (aman untuk dicoba ulang)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeMencegah distribusi tertunda dimulai dengan sendirinya
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeMengganti rencana distribusi sebuah unggahan
DELETE/api/v1/upload-sessions/{id}upload:writeMembatalkan unggahan yang belum selesai dan mengosongkan slotnya
POST/api/v1/remote-uploadsupload:writeMengambil file dari URL http(s) ke akun Anda
POST/api/v1/mirror-tasks/startupload:writeMengirim file ke host pilihan Anda
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readStatus pekerjaan, setiap host, dan tautan berbagi (shareTakenDown menandai halaman yang diturunkan)
GET/api/v1/filesfile:readDaftar file Anda (paginasi kursor, pencarian, filter)
GET/api/v1/files/{id}file:readSatu file: ukuran, checksum, pekerjaan, pengaturan berbagi, statistik
GET/api/v1/files/{id}/mirrorsfile:readSetiap salinan file: host, tautan, kesehatan, klik
PATCH/api/v1/files/{id}/sharefile:writeKata sandi berbagi, masa berlaku, visibilitas
DELETE/api/v1/files/{id}file:deleteMenghapus file dan (secara bawaan) salinannya di host
GET/api/v1/platformtidak ada (publik)Batas saat ini: file terbesar, host per file, batas unggah URL
GET/api/v1/providerstidak ada (publik)Katalog host, dengan slug yang Anda kirim di providerSlugs
GET/api/v1/providers/statustidak ada (publik)Tingkat keberhasilan unggah terukur per host
GET/api/v1/stats/publictidak ada (publik)Total platform selama 30 hari terakhir: file, mirror aktif, tingkat keberhasilan

Unggah file dan distribusikan

  1. Buka sesi dengan POST /api/v1/upload-sessions. filename dan sizeBytes (panjang byte yang tepat) wajib diisi; mimeType dan idempotencyKey berupa UUID bersifat opsional — mengulang permintaan dengan kunci yang sama mengembalikan sesi yang sudah ada alih-alih membuka sesi kedua. Balasannya berisi data.sessionId (bukan id) dan data.chunkSize.
  2. Kirim byte-nya dengan PATCH /api/v1/upload-sessions/{id}/chunks: byte mentah, content type application/offset+octet-stream, dan posisi awal chunk di header upload-offset. Chunk dikirim berurutan, atau hingga maxChunksAhead chunk lebih dulu; jika mengirim berurutan, gunakan data.uploadedBytes dari setiap balasan sebagai offset berikutnya. Kirim chunk berukuran chunkSize byte; setiap chunk kecuali yang terakhir minimal 5 MiB, dan satu unggahan dapat memiliki paling banyak 10 000 chunk. Balasan yang melengkapi file berisi data.fileId. Untuk kecepatan lebih, Anda boleh mengirim 2–3 chunk dari file yang sama secara bersamaan. Kirim chunk pertama sendirian; balasannya memberikan nilai data.maxChunksAhead yang sebenarnya (4 jika chunk pertama berupa irisan chunkSize utuh, 0 = hanya berurutan). Jika chunk pertama berupa irisan chunkSize utuh, setiap chunk berikutnya juga harus demikian (berurutan maupun lebih dulu): dimulai pada kelipatan chunkSize dan berukuran tepat chunkSize byte (yang terakhir: sisa file). Chunk yang dikirim mendahului uploadedBytes harus berupa irisan semacam itu dan dimulai paling jauh data.maxChunksAhead chunk di depan; jika tidak, akan mendapat 409 CHUNK_MISALIGNED atau 409 CHUNK_OUT_OF_WINDOW. uploadedBytes hanya menghitung byte yang diterima tanpa celah, dan chunk mana pun yang melengkapi file akan mendapat balasan berisi fileId. Mengirim ulang chunk yang sudah sampai adalah keberhasilan yang tidak berbahaya.
  3. Distribusikan dengan POST /api/v1/mirror-tasks/start: fileId dan providerSlugs wajib diisi (slug berasal dari GET /api/v1/providers). Opsional: minSuccess (bawaan 1 — berapa host yang harus menerima file agar pekerjaan tidak gagal; statusnya completed hanya jika setiap host juga menerimanya, selain itu partially_completed. Host yang menolak jenis file ini tidak dihitung), sharePassword, expiresInDays atau expiresAt. Balasannya berisi uploadJobId, taskCount, shareSlug, alreadyStarted, dan skipped[] — host yang tidak dapat menerima file ini dilewati, bukan gagal, jadi baca skipped[] (alasannya tercantum di bawah). Saat ini satu file dapat dikirim ke paling banyak 50 host.
  4. Pantau hingga selesai dengan GET /api/v1/mirror-tasks/{uploadJobId} setiap beberapa detik sampai data.terminal bernilai true. Balasannya mencantumkan setiap host di tasks[] (providerSlug, status, mirrorUrl, errorCode) dan tautan berbagi di data.shareUrl. data.shareTakenDown bernilai true jika halaman berbagi tersebut diturunkan dan tidak lagi dapat dibuka.

File terbesar yang diterima saat ini adalah 5,00 GB.

bash, perlu 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

Contoh respons

Membuka sesi menjawab 201. Setiap chunk kecuali yang terakhir menjawab { uploadedBytes, completed: false, expiresAt }; yang terakhir membawa file. distribution hanya ada jika Anda menyertakan rencana saat membuka sesi (lihat di bawah).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (melengkapi file) → 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 pertama yang berhasil menjawab 202; memanggilnya lagi untuk pekerjaan yang sudah berjalan menjawab 200 dengan alreadyStarted: true. Jika tautan sebuah host dirahasiakan sesuai kebijakan, mirrorUrl bernilai null dan mirrorHidden bernilai true — halaman berbagi tetap mencantumkannya.

Lewati panggilan kedua

Sertakan distribution saat membuka sesi dan server mulai mendistribusikan begitu file lengkap. Periksa data.distribution di balasan yang melengkapi file: started: true berarti pekerjaan sudah masuk antrean (uploadJobId, shareSlug). Dengan started: false dan deferred: true, memang belum ada yang masuk antrean secara sengaja — lihat di bawah. Dengan started: false tanpa deferred, unggahan tetap berhasil tetapi distribusi tidak dapat dimulai (error menjelaskan alasannya): panggil POST /api/v1/mirror-tasks/start dengan fileId. error bersama deferred: true berarti kegagalan sementara (misalnya, semua host sedang sibuk atau dalam pemeliharaan): jangan panggil start atau mengunggah file lagi — server akan mencoba memulai distribusi sendiri sejak autoStartAt (hingga 5 percobaan). Panggil hold-distribution untuk menghentikannya.

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": "…" } }

Tambahkan deferred: true ke distribution untuk masa tenggang: balasan terakhir berupa { started: false, deferred: true, autoStartAt } dan server memulai distribusi sendiri pada autoStartAt (sekitar 2 menit kemudian) kecuali Anda memanggil start lebih dulu. Untuk menghentikan mulai otomatis, panggil POST /api/v1/upload-sessions/{id}/hold-distribution (tanpa body; autoStartAt menjadi null dan Anda memulainya sendiri). Untuk mengubah rencana, panggil PUT /api/v1/upload-sessions/{id}/distribution-intent dengan field yang sama seperti distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): panggilan ini mengganti rencana dan mencabut penahanan, dan setelah unggahan selesai, mulai otomatis bergeser ke paling cepat 2 menit setelah panggilan. Jika distribusi sudah dimulai, keduanya menjawab 200 dan distribution-intent menyatakan alreadyStarted: true.

Mulai dalam 30 menit. Jika unggahan selesai dan tidak ada distribusi yang dimulai, salinan file kami dihapus setelah 30 menit (jika masih ada rencana distribusi yang menunggu host tersedia, paling lama setelah 72 jam; unggahan dari URL tidak terpengaruh). Setelah itu, start dan distribution-intent menjawab 409 SOURCE_GONE dan file harus diunggah lagi.

Jika balasan terakhir hilang

Panggil GET /api/v1/upload-sessions/{id}: adanya fileId berarti file sudah ada; finalizable: true berarti semua byte sudah sampai dan POST /api/v1/upload-sessions/{id}/complete akan menyelesaikannya. Panggilan itu aman untuk dicoba ulang dan tidak pernah membuat file kedua. Offset yang tidak cocok mendapat 409 CHUNK_OFFSET_CONFLICT — kirim HEAD ke sesi dan lanjutkan dari header Upload-Offset-nya. Memanggil start lagi untuk pekerjaan yang sedang berjalan bukanlah error: Anda mendapat 200 dengan alreadyStarted: true.

Unggah dari URL

POST /api/v1/remote-uploads menerima { "urls": [...] } dan mengambil setiap file untuk Anda (lingkup upload:write). Hanya tautan http dan https yang diambil, alamat jaringan privat ditolak, dan hanya sejumlah terbatas pengalihan yang diikuti. Satu permintaan memuat paling banyak 10 URL (dikembalikan oleh GET /api/v1/platform); pecah daftar yang lebih panjang.

Batas ukuran per file bergantung pada sumbernya. Jika sumber melaporkan ukuran file, setiap file dapat berukuran hingga 5,00 GB (limits.remoteUploadPassthroughMaxBytes); jika tidak, hingga 100,0 MB (limits.remoteUploadMaxBytes). Nama file diambil dari header Content-Disposition sumber jika dikirimkan; nama tanpa ekstensi akan diberi ekstensi berdasarkan jenis file.

Permintaan menunggu selama file diunduh. Jika koneksi terputus lebih dulu, file tetap masuk ke akun Anda — temukan dengan GET /api/v1/files. Setiap fileId kemudian didistribusikan dengan POST /api/v1/mirror-tasks/start, seperti di atas.

Jika penyimpanan sementara penuh, seluruh permintaan mendapat 503 TEMPORARILY_UNAVAILABLE dengan details.reason: "staging_full" dan header Retry-After. Jika hanya satu URL yang tidak muat, entri tersebut di results[] memiliki ok: false dan kode yang sama; hasil per URL tidak memiliki header, jadi lama menunggu dalam detik ada di 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.

Kelola file

File Anda tetap berada di akun setelah diunggah. Tampilkan daftarnya dengan GET /api/v1/files (limit hingga 100; kirim nextCursor dari balasan sebagai cursor untuk halaman berikutnya, q mencari berdasarkan nama). GET /api/v1/files/{id} mengembalikan satu file beserta pekerjaan, pengaturan berbagi, dan statistik tayangannya; GET /api/v1/files/{id}/mirrors mencantumkan setiap salinan beserta tautan, kesehatan, dan kliknya.

PATCH /api/v1/files/{id}/share (lingkup file:write) mengubah halaman berbagi: password (4–128 karakter, null menghapusnya — tidak pernah dikembalikan, hanya passwordProtected), expiresAt (tanggal ISO, null untuk tanpa batas waktu), visibility, dan hideDownloadCount. Kirim hanya field yang ingin Anda ubah. DELETE /api/v1/files/{id} (lingkup file:delete) menghapus file dan memasukkan salinannya di host ke antrean penghapusan; tambahkan ?keepMirrors=true untuk mempertahankannya. Sebagian host tidak mendukung penghapusan, jadi salinan mungkin tetap ada di sana.

bash, perlu jq; atur 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."
  }
}

Webhook

Tambahkan endpoint di halaman Webhook. URL harus memakai https://; rahasia penandatanganannya (whsec_…) ditampilkan sekali, saat Anda membuatnya. Endpoint tanpa peristiwa yang dipilih menerima semuanya.

PeristiwaKapan
upload.completedSetiap host menerima file, dan setidaknya minSuccess host menerimanya — host yang menolak file ini (rejected) atau dibatalkan tidak dihitung
upload.partially_completedSetidaknya minSuccess host menerima file, tetapi setidaknya satu host lain gagal
upload.failedKurang dari minSuccess host yang menerima file (minSuccess 0 dihitung sebagai 1)
upload.quarantinedPemindaian malware menandai file (hanya jika pemindaian diaktifkan)
provider.upload_succeededSatu host menerima file — dikirim sekali per host
provider.upload_failedSatu host menyerah terhadap file — dikirim sekali per host
webhook.testAnda menekan Uji di halaman Webhook

Setiap pengiriman berupa satu POST dengan body JSON serta header X-MUX-Event dan X-MUX-Signature. Jawaban 2xx apa pun dalam 10 detik dianggap terkirim; pengalihan tidak diikuti. Pengiriman yang gagal (error jaringan, batas waktu habis, 408, 425, 429, atau 5xx) dicoba ulang setelah 1, 5, dan 30 menit dengan body yang sama; 4xx lainnya dan pengalihan tidak dicoba ulang. Setiap percobaan membawa X-MUX-Delivery-Attempt (1–4) dan tanda tangan baru, jadi hilangkan duplikat berdasarkan body. Urutan pengiriman tidak dijamin (peristiwa yang dicoba ulang dapat tiba setelah yang lebih baru); bandingkan data dan createdAt sebelum menindaklanjutinya. Gunakan GET /api/v1/mirror-tasks/{uploadJobId} untuk menyusul. Setelah 15 pengiriman berturut-turut yang percobaan terakhirnya gagal, atau satu jam kegagalan tanpa satu pun keberhasilan, endpoint dijeda; mengaktifkannya kembali mereset hitungan. Pengiriman webhook.test (tombol Uji) dikirim sekali, dengan X-MUX-Delivery-Attempt: 1, dan tidak pernah dicoba ulang.

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

Peristiwa upload.* membawa uploadJobId, fileId, dan status; provider.upload_failed membawa errorCode sebagai pengganti mirrorUrl.

Memverifikasi tanda tangan

Header-nya berbentuk t=1727265600,v1=5f2b…: t adalah waktu penandatanganan dalam detik Unix, v1 adalah HMAC-SHA256 heksadesimal dari <t>.<raw body> dengan kunci berupa rahasia endpoint Anda. Hitung hash dari byte mentah persis seperti yang diterima, bandingkan dalam waktu konstan, dan tolak stempel waktu yang lebih lama dari 5 menit.

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);

Batas laju

Batas dihitung per kunci API, bukan per alamat IP. Setiap respons pada endpoint yang dibatasi membawa X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset (detik epoch). Melewati batas mengembalikan 429 RATE_LIMITED dengan header Retry-After — tunggu selama jumlah detik tersebut. Unggahan chunk mendapat jatah yang longgar; batas yang ketat ada pada pembukaan sesi dan memulai distribusi.

KelompokEndpointPer kunciRentang
Memulai unggahanPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 menit
Mengunggah chunkPATCH /api/v1/upload-sessions/{id}/chunks6001 menit
Polling progresGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 menit
Pengaturan distribusi unggahanPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 menit
Memulai distribusiPOST /api/v1/mirror-tasks/start301 menit
Unggah jarak jauh (URL)POST /api/v1/remote-uploads2010 menit
Membaca fileGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 menit
Mengubah filePATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 menit
Katalog publikGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 menit

Ini adalah angka bawaan. Operator dapat mengubahnya, jadi header di atas selalu menjadi acuan yang benar. Angka pasti untuk kunci Anda, dan berapa banyak yang sudah Anda pakai saat ini, ada di halaman Kunci API. Permintaan tanpa kunci dihitung per alamat IP dan mendapat jatah lebih kecil untuk memulai unggahan (10 alih-alih 60), mengunggah chunk (300 alih-alih 600), polling progres (300 alih-alih 600), pengaturan distribusi unggahan (60 alih-alih 300), memulai distribusi (10 alih-alih 30), serta jatah yang sama untuk unggah jarak jauh (URL) dan katalog publik. Membaca file dan mengubah file selalu memerlukan kunci.

Error

Balasan yang berhasil berbentuk { "success": true, "data": … }. Error memakai satu bentuk, di samping status HTTP. code bersifat stabil — jadikan dasar percabangan; message ditujukan untuk manusia dan dapat berubah. details ditambahkan jika ada konteks lebih lanjut, retryable menyatakan apakah mencoba ulang permintaan yang sama dapat membantu, dan requestId membantu kami menemukan permintaan Anda jika Anda menghubungi dukungan.

Error
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
KodeHTTPCoba ulang?Arti
NO_TOKEN401TidakTidak ada kunci API yang dikirim
INVALID_API_KEY401TidakKunci salah atau sudah dicabut
INSUFFICIENT_SCOPE403TidakKunci tidak memiliki lingkup yang diperlukan endpoint ini
API_KEY_NOT_ALLOWED403TidakEndpoint ini tidak dapat digunakan dengan kunci API
EMAIL_NOT_VERIFIED403TidakVerifikasi email akun terlebih dahulu; sesi yang terbuka tetap berfungsi
SESSION_REVOKED401TidakSesi masuk telah diakhiri (reset atau penggantian kata sandi, keluar); masuk lagi
ACCOUNT_INACTIVE403TidakAkun ditangguhkan atau dijadwalkan untuk dihapus
ACCOUNT_DISABLED401 / 409TidakAkun ditangguhkan: 401 pada pemeriksaan kunci, 409 jika berubah saat permintaan sedang berjalan
ACCOUNT_PENDING_DELETION409TidakAkun dijadwalkan untuk dihapus saat permintaan sedang berjalan; tidak ada hal baru yang dimulai
VALIDATION_ERROR400TidakBody atau parameter tidak valid; lihat details
FILE_REJECTED400TidakJenis atau ukuran file tidak diizinkan; details.reason menyebutkan yang mana
TOO_MANY_MIRRORS400TidakJumlah host melebihi yang diizinkan untuk satu file
NO_CONNECTED_PROVIDERS400TidakSetiap host terpilih memerlukan akun Anda sendiri dan tidak ada yang terhubung
PROVIDER_REJECTS_FILE400TidakTidak ada host terpilih yang menerima jenis atau ukuran file ini
NO_AVAILABLE_PROVIDERS400TidakTidak ada host terpilih yang menerima unggahan saat ini; pilih host lain atau coba lagi nanti. `details.waiting` mencantumkan host yang hanya dijeda (misalnya batas harian, dibuka dalam 24 jam): untuk host itu mencoba lagi nanti berhasil meskipun `retryable` bernilai false
NO_VALID_PROVIDERS400TidakTidak ada nilai providerSlugs yang cocok dengan host yang aktif; lihat GET /api/v1/providers
INVALID_JOB_STATE400TidakPekerjaan tidak dapat dimulai dalam statusnya saat ini
JOB_NOT_READY400TidakFile belum memiliki pekerjaan distribusi
FILE_TOO_LARGE_FOR_UPLOAD400TidakFile tidak muat dalam 10 000 chunk dengan ukuran chunk sesi; details.limitBytes
MISSING_OFFSET400TidakChunk dikirim tanpa header upload-offset berupa angka
RAW_BODY_REQUIRED400TidakBody chunk harus berupa byte mentah dengan content-type application/offset+octet-stream
TOO_MANY_URLS400TidakJumlah URL dalam satu permintaan remote-uploads melebihi batas
FILE_NOT_FOUND404TidakFile tersebut tidak ada di akun Anda (atau sudah dihapus)
JOB_NOT_FOUND404TidakPekerjaan distribusi tersebut tidak ada di akun Anda
SESSION_NOT_FOUND404TidakSesi unggah tersebut tidak ada di akun Anda
SHARE_NOT_FOUND404TidakFile belum memiliki halaman berbagi
QUOTA_EXCEEDED409TidakBatas unggah harian atau serentak; details.retryAt menyebutkan kapan kembali tersedia
CHUNK_OFFSET_CONFLICT409Tidakupload-offset tidak cocok dengan byte yang diterima; lanjutkan dari HEAD
CHUNK_TOO_SMALL409TidakChunk selain yang terakhir berukuran di bawah 5 MiB
CHUNK_TOO_MANY_PARTS409TidakLebih dari 10 000 chunk; kirim chunk yang lebih besar
CHUNK_MISALIGNED409TidakChunk bukan irisan chunkSize utuh yang dimulai pada kelipatan chunkSize: wajib untuk chunk yang dikirim lebih dulu dan, jika chunk pertama berupa irisan chunkSize utuh, juga untuk setiap chunk berikutnya (berurutan maupun lebih dulu); atau chunk dikirim lebih dulu dalam sesi yang hanya menerima chunk secara berurutan
CHUNK_OUT_OF_WINDOW409TidakChunk dimulai lebih dari maxChunksAhead chunk setelah uploadedBytes, atau melewatinya sama sekali sebelum chunk pertama diterima; kirim lagi setelah chunk sebelumnya
CHUNK_EXCEEDS_DECLARED_SIZE409TidakChunk melewati ukuran file yang dinyatakan saat sesi dibuat
CHUNK_EMPTY409TidakChunk tidak berisi byte
CHUNK_NOT_RECEIVABLE409TidakSesi tidak lagi menerima data (sudah selesai, dibatalkan, atau kedaluwarsa); buka sesi baru
SESSION_EXPIRED409TidakSesi unggah sudah kedaluwarsa; buka sesi baru
SESSION_NOT_RECEIVABLE409TidakSesi sudah dibatalkan atau kedaluwarsa dan tidak menerima perubahan lagi
SESSION_COMPLETED409TidakUnggahan sudah selesai; hapus file sebagai gantinya
UPLOAD_INCOMPLETE409TidakBelum semua byte sampai; kirim chunk yang tersisa terlebih dahulu (details berisi jumlahnya)
IDEMPOTENCY_KEY_CONFLICT409TidakidempotencyKey ini sudah dipakai oleh unggahan lain; gunakan kunci unik untuk setiap unggahan
SOURCE_GONE409TidakSalinan file kami sudah dihapus, jadi file tidak dapat dikirim ke host yang belum pernah dicoba; unggah lagi untuk host tersebut. Salinan kami dihapus segera setelah pekerjaan distribusi selesai (selesai, selesai sebagian, atau gagal), dan unggahan yang distribusinya tidak pernah dimulai dihapus 30 menit setelah selesai (hingga 72 jam jika rencana distribusinya masih menunggu host; kecuali unggahan dari URL). Memanggil mirror-tasks/start lagi untuk pekerjaan yang sudah selesai hanya dengan host yang sudah pernah dicoba hanya menerapkan pengaturan berbagi (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409TidakPekerjaan gagal, dibatalkan, atau berada dalam status yang tidak dapat didistribusikan lagi
SHARE_TAKEN_DOWN409TidakHalaman berbagi file telah diturunkan, jadi file tidak dapat dikirim ke host lain
FINALIZING409YaPermintaan lain sedang merakit file; tanyakan lagi dalam beberapa detik
CONFLICT409YaBertabrakan dengan perubahan lain yang sedang berlangsung; coba ulang permintaan yang sama
TEMPORARILY_UNAVAILABLE503Ya, setelah Retry-AfterServer sedang sibuk; coba lagi setelah jeda Retry-After. details.reason "staging_full": penyimpanan sementara penuh, tidak ada unggahan baru yang diterima (Retry-After sekitar 10 menit); unggahan yang sedang berjalan tetap berfungsi
PAYLOAD_TOO_LARGE413TidakBody permintaan (atau satu chunk) lebih besar dari yang diterima server
REMOTE_TOO_LARGEper URLTidakDalam hasil remote-uploads: file melebihi batas unggah URL
RATE_LIMITED429Ya, setelah Retry-AfterTerlalu banyak permintaan untuk kelompok ini
INTERNAL_ERROR500YaError server; detail dicatat di log, tidak pernah dikembalikan
MAINTENANCE503Ya, setelah Retry-AfterUnggahan baru sedang dijeda; pembacaan tetap berfungsi
UPLOADS_TEMPORARILY_UNAVAILABLE503Ya, setelah Retry-AfterPenghitung unggahan kami tidak dapat dibaca; tidak ada sesi yang dibuka
SHUTTING_DOWN503Ya, setelah Retry-AfterServer sedang dimulai ulang (Retry-After 5 detik); tunggu lalu kirim permintaan yang sama lagi — belum ada yang diproses

Mengapa sebuah host dilewati

Ini bukan error: alasan ini muncul di skipped[].reason dari start yang berhasil (dan dari distribution di balasan yang melengkapi file). Host lainnya tetap menerima file. Panggilan baru gagal hanya jika tidak ada host terpilih yang dapat menerimanya: PROVIDER_REJECTS_FILE (tidak ada yang menerima file ini), NO_CONNECTED_PROVIDERS (semuanya memerlukan akun Anda sendiri), NO_AVAILABLE_PROVIDERS (tidak ada yang menerima unggahan saat ini), atau NO_VALID_PROVIDERS (tidak ada slug yang cocok dengan host yang aktif).

AlasanArti
UNKNOWN_PROVIDERTidak ada host dengan slug ini — periksa ejaannya dengan GET /api/v1/providers
PROVIDER_DISABLEDHost sedang dinonaktifkan atau dalam pemeliharaan
ACCOUNT_REQUIREDHost hanya menerima unggahan ke akun Anda sendiri — hubungkan di halaman Koneksi
GUEST_UPLOAD_OFFHost sedang tidak menerima unggahan dan tidak dapat dihubungkan ke akun
DAILY_LIMIT_REACHEDBatas harian host untuk unggahan tanpa akun sudah habis untuk sementara (hingga 24 jam) — hubungkan akun Anda sendiri agar tetap dapat mengunggah
FILE_TOO_LARGEFile melebihi batas ukuran host ini
MIME_NOT_ALLOWEDHost tidak menerima jenis file ini
ALREADY_ATTEMPTEDHost ini sudah dicoba untuk file ini, jadi file tidak dikirim lagi ke sana

Referensi API mencantumkan kode yang dapat dikembalikan setiap endpoint.