Chuyển đến nội dung

Tài liệu API

Tải tệp lên một lần, gửi đến các host lưu trữ tệp bạn chọn và nhận lại một liên kết chia sẻ — từ mã của riêng bạn.

Cập nhật

REST API có phiên bản: tải tệp lên theo từng phần, gửi đến các host bạn chọn, và mọi bản sao được gom vào một trang chia sẻ với trạng thái trực tiếp.

URL gốc
https://api.mirroruploadx.com/api/v1
Xác thực
x-api-key: mux_…
  1. 1Mở phiên

    POST /api/v1/upload-sessions

    filename + sizeBytes; nhận sessionId và chunkSize

  2. 2Gửi các phần

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

    byte thô theo thứ tự; phản hồi hoàn tất tệp có fileId

  3. 3Phân phối

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; sau đó thăm dò tác vụ

Tạo khóa ở trang Khóa API. Hướng dẫn đầy đủ kèm mã có tại Tải lên và phân phối.

Xác thực

Tạo khóa ở trang Khóa API trong bảng điều khiển. Khóa đầy đủ (bắt đầu bằng mux_) chỉ hiển thị một lần, nên hãy lưu ngay. Gửi khóa trong header x-api-key ở mọi yêu cầu; Authorization: Bearer mux_… cũng được chấp nhận tương tự cho các client chỉ dùng bearer token.

Khóa có phạm vi: một khóa chỉ truy cập được các endpoint mà phạm vi của nó bao gồm, và lệnh gọi với phạm vi sai sẽ trả về 403 INSUFFICIENT_SCOPE kèm phạm vi cần thiết trong thông báo. Cài đặt tài khoản, quản lý khóa và webhook hoàn toàn không truy cập được bằng khóa API (API_KEY_NOT_ALLOWED).

Phạm viTruy cập được
upload:writePhiên tải lên (tạo, gửi phần, hoàn tất, hủy), hạn mức tải lên của bạn, giữ hoặc thay đổi việc tự động phân phối của một lượt tải lên (hold-distribution, distribution-intent), tải lên từ URL, bắt đầu phân phối
file:readLiệt kê tệp, chi tiết tệp, trạng thái bản sao và tác vụ
file:writeCài đặt chia sẻ của tệp
file:deleteXóa tệp và các bản sao của nó

Endpoint

Mọi thứ khóa API có thể truy cập, cùng các endpoint công khai không cần khóa. Khi cột phạm vi liệt kê hai phạm vi, chỉ cần một trong hai là đủ. Lược đồ yêu cầu và phản hồi của từng endpoint có trong tài liệu tham chiếu API.

Phương thứcĐường dẫnPhạm viChức năng
POST/api/v1/upload-sessionsupload:writeMở phiên tải lên (có thể kèm kế hoạch phân phối)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeGửi phần byte tiếp theo
HEAD/api/v1/upload-sessions/{id}upload:writeVị trí để tiếp tục: header Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readTrạng thái phiên: số byte đã nhận, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readGiới hạn tải lên, mức sử dụng và các phiên chưa hoàn tất của bạn
POST/api/v1/upload-sessions/{id}/completeupload:writeHoàn tất lượt tải lên bị mất phản hồi cuối (an toàn khi thử lại)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeNgăn việc phân phối hoãn lại tự bắt đầu
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeThay kế hoạch phân phối của một lượt tải lên
DELETE/api/v1/upload-sessions/{id}upload:writeHủy lượt tải lên chưa hoàn tất và giải phóng chỗ
POST/api/v1/remote-uploadsupload:writeLấy tệp từ URL http(s) vào tài khoản của bạn
POST/api/v1/mirror-tasks/startupload:writeGửi tệp đến các host bạn chọn
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readTrạng thái tác vụ, từng host và liên kết chia sẻ (shareTakenDown đánh dấu trang đã bị gỡ)
GET/api/v1/filesfile:readLiệt kê tệp của bạn (phân trang bằng cursor, tìm kiếm, bộ lọc)
GET/api/v1/files/{id}file:readMột tệp: kích thước, checksum, tác vụ, cài đặt chia sẻ, thống kê
GET/api/v1/files/{id}/mirrorsfile:readMọi bản sao của tệp: host, liên kết, tình trạng, lượt nhấp
PATCH/api/v1/files/{id}/sharefile:writeMật khẩu chia sẻ, thời hạn, chế độ hiển thị
DELETE/api/v1/files/{id}file:deleteXóa tệp và (mặc định) các bản sao của nó trên host
GET/api/v1/platformkhông (công khai)Giới hạn hiện tại: tệp lớn nhất, số host mỗi tệp, giới hạn tải lên từ URL
GET/api/v1/providerskhông (công khai)Danh mục host, kèm các slug bạn gửi trong providerSlugs
GET/api/v1/providers/statuskhông (công khai)Tỷ lệ tải lên thành công đo được theo từng host
GET/api/v1/stats/publickhông (công khai)Tổng số liệu nền tảng trong 30 ngày qua: tệp, bản sao đang hoạt động, tỷ lệ thành công

Tải tệp lên và phân phối

  1. Mở phiên bằng POST /api/v1/upload-sessions. filename và sizeBytes (độ dài chính xác tính bằng byte) là bắt buộc; mimeType và idempotencyKey dạng UUID là tùy chọn — lặp lại yêu cầu với cùng khóa sẽ trả về phiên hiện có thay vì mở phiên thứ hai. Phản hồi chứa data.sessionId (không phải id) và data.chunkSize.
  2. Gửi các byte bằng PATCH /api/v1/upload-sessions/{id}/chunks: byte thô, content type application/offset+octet-stream, và vị trí bắt đầu của phần trong header upload-offset. Các phần được gửi theo thứ tự, hoặc vượt trước tối đa maxChunksAhead phần; khi gửi theo thứ tự, hãy dùng data.uploadedBytes từ mỗi phản hồi làm offset tiếp theo. Gửi các phần có kích thước chunkSize byte; mọi phần trừ phần cuối phải có ít nhất 5 MiB, và một lượt tải lên có tối đa 10 000 phần. Phản hồi hoàn tất tệp chứa data.fileId. Để nhanh hơn, bạn có thể gửi đồng thời 2–3 phần của cùng một tệp. Hãy gửi phần đầu tiên riêng; phản hồi của nó cho biết data.maxChunksAhead thực tế (4 nếu phần đầu là một lát chunkSize trọn vẹn, 0 = chỉ theo thứ tự). Nếu phần đầu là một lát chunkSize trọn vẹn, mọi phần sau cũng phải như vậy (theo thứ tự hay vượt trước): bắt đầu tại bội số của chunkSize và dài đúng chunkSize byte (phần cuối: phần còn lại của tệp). Phần được gửi vượt trước uploadedBytes phải là một lát như vậy và bắt đầu không quá data.maxChunksAhead phần phía trước, nếu không sẽ nhận 409 CHUNK_MISALIGNED hoặc 409 CHUNK_OUT_OF_WINDOW. uploadedBytes chỉ tính các byte nhận được liên tục không có khoảng trống, và phần nào hoàn tất tệp sẽ nhận phản hồi có fileId. Gửi lại một phần đã đến là thao tác thành công vô hại.
  3. Phân phối bằng POST /api/v1/mirror-tasks/start: fileId và providerSlugs là bắt buộc (slug lấy từ GET /api/v1/providers). Tùy chọn: minSuccess (mặc định 1 — số host phải nhận tệp để tác vụ không thất bại; tác vụ chỉ completed khi mọi host cũng đã nhận, nếu không là partially_completed. Host từ chối loại tệp này không được tính), sharePassword, expiresInDays hoặc expiresAt. Phản hồi có uploadJobId, taskCount, shareSlug, alreadyStarted và skipped[] — host không thể nhận tệp này bị bỏ qua chứ không bị tính là thất bại, nên hãy đọc skipped[] (các lý do được liệt kê bên dưới). Hiện một tệp có thể được gửi đến tối đa 50 host.
  4. Theo dõi đến khi xong bằng GET /api/v1/mirror-tasks/{uploadJobId} mỗi vài giây cho đến khi data.terminal là true. Phản hồi liệt kê mọi host trong tasks[] (providerSlug, status, mirrorUrl, errorCode) và liên kết chia sẻ trong data.shareUrl. data.shareTakenDown là true khi trang chia sẻ đó đã bị gỡ và không còn mở được.

Tệp lớn nhất hiện được chấp nhận là 5,00 GB.

bash, cần 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

Ví dụ phản hồi

Mở phiên trả về 201. Mọi phần trừ phần cuối trả về { uploadedBytes, completed: false, expiresAt }; phần cuối mang theo tệp. distribution chỉ có khi bạn đã truyền kế hoạch lúc mở phiên (xem bên dưới).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (hoàn tất tệp) → 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
      }
    ]
  }
}

Lệnh start đầu tiên thành công trả về 202; gọi lại cho tác vụ đang chạy sẽ trả về 200 kèm alreadyStarted: true. Khi liên kết của một host được giữ kín theo chính sách, mirrorUrl là null và mirrorHidden là true — trang chia sẻ vẫn liệt kê host đó.

Bỏ qua lệnh gọi thứ hai

Truyền distribution khi mở phiên và máy chủ sẽ bắt đầu phân phối ngay khi tệp hoàn tất. Hãy kiểm tra data.distribution trong phản hồi hoàn tất tệp: started: true nghĩa là tác vụ đã vào hàng đợi (uploadJobId, shareSlug). Với started: false và deferred: true, chưa có gì vào hàng đợi một cách có chủ ý — xem bên dưới. Với started: false và không có deferred, việc tải lên vẫn thành công nhưng không thể bắt đầu phân phối (error cho biết lý do): hãy gọi POST /api/v1/mirror-tasks/start với fileId. error đi cùng deferred: true nghĩa là lỗi tạm thời (ví dụ, mọi host đều bận hoặc đang bảo trì): đừng gọi start hay tải tệp lên lại — máy chủ sẽ tự thử bắt đầu phân phối lại từ autoStartAt (tối đa 5 lần). Gọi hold-distribution để dừng việc đó.

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

Thêm deferred: true vào distribution để có thời gian chờ: phản hồi cuối là { started: false, deferred: true, autoStartAt } và máy chủ tự bắt đầu phân phối tại autoStartAt (khoảng 2 phút sau) trừ khi bạn gọi start trước. Để dừng việc tự động bắt đầu, gọi POST /api/v1/upload-sessions/{id}/hold-distribution (không có body; autoStartAt trở thành null và bạn tự bắt đầu). Để thay đổi kế hoạch, gọi PUT /api/v1/upload-sessions/{id}/distribution-intent với các trường giống distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): lệnh này thay kế hoạch và gỡ trạng thái giữ, và khi lượt tải lên đã xong, thời điểm tự động bắt đầu được dời đến ít nhất 2 phút sau lệnh gọi. Nếu việc phân phối đã bắt đầu, cả hai đều trả về 200 và distribution-intent báo alreadyStarted: true.

Hãy bắt đầu trong vòng 30 phút. Khi một lượt tải lên hoàn tất mà không có phân phối nào được bắt đầu, bản sao tệp của chúng tôi sẽ bị xóa sau 30 phút (nếu kế hoạch phân phối vẫn đang chờ host khả dụng thì sau tối đa 72 giờ; tải lên từ URL không bị ảnh hưởng). Sau đó, start và distribution-intent trả về 409 SOURCE_GONE và tệp phải được tải lên lại.

Nếu phản hồi cuối bị mất

Gọi GET /api/v1/upload-sessions/{id}: có fileId nghĩa là tệp đã tồn tại; finalizable: true nghĩa là mọi byte đã đến và POST /api/v1/upload-sessions/{id}/complete sẽ hoàn tất nó. Lệnh gọi đó an toàn khi thử lại và không bao giờ tạo tệp thứ hai. Offset không khớp sẽ nhận 409 CHUNK_OFFSET_CONFLICT — hãy gửi HEAD cho phiên và tiếp tục từ header Upload-Offset của nó. Gọi lại start cho tác vụ đang chạy không phải là lỗi: bạn nhận 200 kèm alreadyStarted: true.

Tải lên từ URL

POST /api/v1/remote-uploads nhận { "urls": [...] } và lấy từng tệp giúp bạn (phạm vi upload:write). Chỉ liên kết http và https được lấy, địa chỉ mạng riêng bị từ chối, và chỉ một số lần chuyển hướng giới hạn được theo. Một yêu cầu chứa tối đa 10 URL (trả về bởi GET /api/v1/platform); hãy chia nhỏ danh sách dài hơn.

Giới hạn dung lượng mỗi tệp tùy thuộc vào nguồn. Khi nguồn cho biết kích thước tệp, mỗi tệp có thể đến 5,00 GB (limits.remoteUploadPassthroughMaxBytes); khi không, đến 100,0 MB (limits.remoteUploadMaxBytes). Tên tệp lấy từ header Content-Disposition của nguồn nếu có; tên không có phần mở rộng sẽ được thêm phần mở rộng theo loại tệp.

Yêu cầu sẽ chờ trong lúc tải tệp về. Nếu kết nối bị ngắt trước, tệp vẫn vào tài khoản của bạn — tìm nó bằng GET /api/v1/files. Sau đó mỗi fileId được phân phối bằng POST /api/v1/mirror-tasks/start, như ở trên.

Khi bộ nhớ tạm đầy, toàn bộ yêu cầu nhận 503 TEMPORARILY_UNAVAILABLE với details.reason: "staging_full" và header Retry-After. Nếu chỉ một URL không vừa, mục đó trong results[] có ok: false và cùng mã lỗi; kết quả theo từng URL không có header, nên thời gian chờ tính bằng giây nằm trong 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.

Quản lý tệp

Tệp của bạn vẫn nằm trong tài khoản sau khi tải lên. Liệt kê chúng bằng GET /api/v1/files (limit tối đa 100; truyền nextCursor của phản hồi làm cursor để lấy trang tiếp theo, q tìm theo tên). GET /api/v1/files/{id} trả về một tệp kèm tác vụ, cài đặt chia sẻ và thống kê lượt xem; GET /api/v1/files/{id}/mirrors liệt kê mọi bản sao kèm liên kết, tình trạng và lượt nhấp.

PATCH /api/v1/files/{id}/share (phạm vi file:write) thay đổi trang chia sẻ: password (4–128 ký tự, null để xóa — không bao giờ được trả về, chỉ có passwordProtected), expiresAt (ngày ISO, null nếu không hết hạn), visibility và hideDownloadCount. Chỉ gửi các trường bạn muốn thay đổi. DELETE /api/v1/files/{id} (phạm vi file:delete) xóa tệp và đưa các bản sao trên host vào hàng đợi xóa; thêm ?keepMirrors=true để giữ chúng. Một số host không hỗ trợ xóa, nên bản sao có thể vẫn còn ở đó.

bash, cần jq; đặt 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

Thêm endpoint ở trang Webhook. URL phải dùng https://; khóa bí mật để ký (whsec_…) chỉ hiển thị một lần, khi bạn tạo. Endpoint không chọn sự kiện nào sẽ nhận tất cả.

Sự kiệnKhi nào
upload.completedMọi host đã nhận tệp, và ít nhất minSuccess host đã nhận — host từ chối tệp này (rejected) hoặc bị hủy không được tính
upload.partially_completedÍt nhất minSuccess host đã nhận tệp, nhưng có ít nhất một host khác thất bại
upload.failedÍt hơn minSuccess host nhận tệp (minSuccess 0 được tính là 1)
upload.quarantinedTrình quét phần mềm độc hại đã gắn cờ tệp (chỉ khi bật quét)
provider.upload_succeededMột host đã nhận tệp — gửi một lần cho mỗi host
provider.upload_failedMột host đã bỏ cuộc với tệp — gửi một lần cho mỗi host
webhook.testBạn đã nhấn Kiểm thử ở trang Webhook

Mỗi lần gửi là một POST với body JSON và các header X-MUX-Event và X-MUX-Signature. Mọi phản hồi 2xx trong vòng 10 giây được tính là đã gửi thành công; chuyển hướng không được theo. Lần gửi thất bại (lỗi mạng, hết thời gian chờ, 408, 425, 429 hoặc 5xx) được thử lại sau 1, 5 và 30 phút với cùng body; các mã 4xx khác và chuyển hướng thì không. Mỗi lần thử mang X-MUX-Delivery-Attempt (1–4) và chữ ký mới, nên hãy loại trùng dựa trên body. Thứ tự gửi không được bảo đảm (sự kiện được thử lại có thể đến sau sự kiện mới hơn); hãy so sánh data và createdAt trước khi xử lý. Dùng GET /api/v1/mirror-tasks/{uploadJobId} để cập nhật lại. Sau 15 lần gửi liên tiếp mà lần thử cuối đều thất bại, hoặc một giờ thất bại không có lần nào thành công, endpoint sẽ bị tạm dừng; bật lại sẽ đặt lại bộ đếm. Lần gửi webhook.test (nút Kiểm thử) chỉ gửi một lần, với X-MUX-Delivery-Attempt: 1, và không bao giờ được thử lại.

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

Các sự kiện upload.* mang uploadJobId, fileId và status; provider.upload_failed mang errorCode thay cho mirrorUrl.

Xác minh chữ ký

Header có dạng t=1727265600,v1=5f2b…: t là thời điểm ký tính bằng giây Unix, v1 là HMAC-SHA256 dạng hex của <t>.<raw body> với khóa là khóa bí mật của endpoint. Hãy băm đúng các byte thô như khi nhận, so sánh trong thời gian không đổi, và từ chối dấu thời gian cũ hơn 5 phút.

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

Giới hạn tần suất

Giới hạn được tính theo từng khóa API, không theo địa chỉ IP. Mọi phản hồi ở endpoint có giới hạn đều mang X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset (giây epoch). Vượt giới hạn sẽ trả về 429 RATE_LIMITED kèm header Retry-After — hãy chờ đúng số giây đó. Việc tải lên các phần có ngân sách rộng; giới hạn hẹp áp dụng cho việc mở phiên và bắt đầu phân phối.

NhómEndpointMỗi khóaKhoảng thời gian
Bắt đầu tải lênPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 phút
Tải lên các phầnPATCH /api/v1/upload-sessions/{id}/chunks6001 phút
Thăm dò tiến độGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 phút
Cài đặt phân phối cho lượt tải lênPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 phút
Bắt đầu phân phốiPOST /api/v1/mirror-tasks/start301 phút
Tải lên từ xa (URL)POST /api/v1/remote-uploads2010 phút
Đọc tệpGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 phút
Thay đổi tệpPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 phút
Danh mục công khaiGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 phút

Đây là các con số mặc định. Nhà vận hành có thể thay đổi chúng, nên các header ở trên luôn là nguồn chính xác. Con số chính xác cho các khóa của bạn, và mức bạn đã dùng hiện tại, có ở trang Khóa API. Yêu cầu không có khóa được tính theo địa chỉ IP và nhận ngân sách nhỏ hơn cho bắt đầu tải lên (10 thay vì 60), tải lên các phần (300 thay vì 600), thăm dò tiến độ (300 thay vì 600), cài đặt phân phối cho lượt tải lên (60 thay vì 300), bắt đầu phân phối (10 thay vì 30), và cùng ngân sách cho tải lên từ xa (URL) và danh mục công khai. Đọc tệp và thay đổi tệp luôn cần khóa.

Lỗi

Phản hồi thành công có dạng { "success": true, "data": … }. Lỗi dùng một định dạng duy nhất, đi kèm mã trạng thái HTTP. code ổn định — hãy rẽ nhánh theo nó; message dành cho con người và có thể thay đổi. details được thêm khi có thêm ngữ cảnh, retryable cho biết thử lại cùng yêu cầu có giúp ích không, và requestId giúp chúng tôi tìm yêu cầu của bạn nếu bạn liên hệ hỗ trợ.

Lỗi
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
MãHTTPThử lại?Ý nghĩa
NO_TOKEN401KhôngKhông có khóa API nào được gửi
INVALID_API_KEY401KhôngKhóa sai hoặc đã bị thu hồi
INSUFFICIENT_SCOPE403KhôngKhóa thiếu phạm vi mà endpoint này cần
API_KEY_NOT_ALLOWED403KhôngKhông thể dùng endpoint này bằng khóa API
EMAIL_NOT_VERIFIED403KhôngHãy xác minh email của tài khoản trước; các phiên đang mở vẫn hoạt động
SESSION_REVOKED401KhôngPhiên đăng nhập đã kết thúc (đặt lại hoặc đổi mật khẩu, đăng xuất); hãy đăng nhập lại
ACCOUNT_INACTIVE403KhôngTài khoản bị đình chỉ hoặc đã được lên lịch xóa
ACCOUNT_DISABLED401 / 409KhôngTài khoản đã bị đình chỉ: 401 khi kiểm tra khóa, 409 nếu thay đổi trong lúc yêu cầu đang chạy
ACCOUNT_PENDING_DELETION409KhôngTài khoản được lên lịch xóa trong lúc yêu cầu đang chạy; không có gì mới được bắt đầu
VALIDATION_ERROR400KhôngBody hoặc tham số không hợp lệ; xem details
FILE_REJECTED400KhôngLoại hoặc kích thước tệp không được phép; details.reason cho biết cụ thể
TOO_MANY_MIRRORS400KhôngNhiều host hơn mức một tệp được phép
NO_CONNECTED_PROVIDERS400KhôngMọi host đã chọn đều cần tài khoản của riêng bạn và chưa host nào được kết nối
PROVIDER_REJECTS_FILE400KhôngKhông host nào đã chọn nhận loại hoặc kích thước tệp này
NO_AVAILABLE_PROVIDERS400KhôngHiện không host nào đã chọn nhận tải lên; hãy chọn host khác hoặc thử lại sau. `details.waiting` liệt kê các host chỉ đang tạm dừng (ví dụ giới hạn hằng ngày, được gỡ trong 24 giờ): với chúng, thử lại sau vẫn được dù `retryable` là false
NO_VALID_PROVIDERS400KhôngKhông giá trị providerSlugs nào khớp với host đang bật; xem GET /api/v1/providers
INVALID_JOB_STATE400KhôngKhông thể bắt đầu tác vụ ở trạng thái hiện tại
JOB_NOT_READY400KhôngTệp chưa có tác vụ phân phối
FILE_TOO_LARGE_FOR_UPLOAD400KhôngTệp không vừa trong 10 000 phần với kích thước phần của phiên; details.limitBytes
MISSING_OFFSET400KhôngMột phần được gửi mà không có header upload-offset dạng số
RAW_BODY_REQUIRED400KhôngBody của phần phải là byte thô với content-type application/offset+octet-stream
TOO_MANY_URLS400KhôngSố URL trong một yêu cầu remote-uploads vượt mức cho phép
FILE_NOT_FOUND404KhôngKhông có tệp này trong tài khoản của bạn (hoặc tệp đã bị xóa)
JOB_NOT_FOUND404KhôngKhông có tác vụ phân phối này trong tài khoản của bạn
SESSION_NOT_FOUND404KhôngKhông có phiên tải lên này trong tài khoản của bạn
SHARE_NOT_FOUND404KhôngTệp chưa có trang chia sẻ
QUOTA_EXCEEDED409KhôngĐạt giới hạn tải lên hằng ngày hoặc đồng thời; details.retryAt cho biết khi nào được giải phóng
CHUNK_OFFSET_CONFLICT409Khôngupload-offset không khớp với số byte đã nhận; hãy tiếp tục từ HEAD
CHUNK_TOO_SMALL409KhôngMột phần không phải phần cuối nhỏ hơn 5 MiB
CHUNK_TOO_MANY_PARTS409KhôngNhiều hơn 10 000 phần; hãy gửi các phần lớn hơn
CHUNK_MISALIGNED409KhôngPhần không phải là một lát chunkSize trọn vẹn bắt đầu tại bội số của chunkSize: bắt buộc với phần gửi vượt trước và, nếu phần đầu là một lát chunkSize trọn vẹn, với mọi phần sau (theo thứ tự hay vượt trước); hoặc một phần được gửi vượt trước trong phiên chỉ nhận các phần theo thứ tự
CHUNK_OUT_OF_WINDOW409KhôngMột phần bắt đầu xa hơn maxChunksAhead phần sau uploadedBytes, hoặc vượt qua nó trước khi phần đầu tiên được chấp nhận; hãy gửi lại sau các phần trước đó
CHUNK_EXCEEDS_DECLARED_SIZE409KhôngPhần vượt quá kích thước tệp đã khai báo khi tạo phiên
CHUNK_EMPTY409KhôngPhần không có byte nào
CHUNK_NOT_RECEIVABLE409KhôngPhiên không còn nhận dữ liệu (đã hoàn tất, bị hủy hoặc hết hạn); hãy mở phiên mới
SESSION_EXPIRED409KhôngPhiên tải lên đã hết hạn; hãy mở phiên mới
SESSION_NOT_RECEIVABLE409KhôngPhiên đã bị hủy hoặc hết hạn và không nhận thêm thay đổi
SESSION_COMPLETED409KhôngLượt tải lên đã hoàn tất; hãy xóa tệp thay vì vậy
UPLOAD_INCOMPLETE409KhôngChưa nhận đủ mọi byte; hãy gửi các phần còn lại trước (details có số liệu)
IDEMPOTENCY_KEY_CONFLICT409KhôngidempotencyKey này đã được một lượt tải lên khác sử dụng; hãy dùng khóa riêng cho mỗi lượt tải lên
SOURCE_GONE409KhôngBản sao tệp của chúng tôi đã bị xóa, nên không thể gửi đến các host chưa được thử; hãy tải lên lại cho những host đó. Bản sao của chúng tôi bị xóa ngay khi tác vụ phân phối kết thúc (hoàn tất, hoàn tất một phần hoặc thất bại), và lượt tải lên không bao giờ được bắt đầu phân phối sẽ bị xóa 30 phút sau khi hoàn tất (tối đa 72 giờ khi kế hoạch phân phối vẫn đang chờ host; trừ tải lên từ URL). Gọi lại mirror-tasks/start cho tác vụ đã kết thúc chỉ với các host đã thử chỉ áp dụng cài đặt chia sẻ (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409KhôngTác vụ đã thất bại, bị hủy hoặc ở trạng thái không thể phân phối nữa
SHARE_TAKEN_DOWN409KhôngTrang chia sẻ của tệp đã bị gỡ, nên không thể gửi đến thêm host
FINALIZING409CóMột yêu cầu khác đang ghép tệp; hãy hỏi lại sau vài giây
CONFLICT409CóXung đột với một thay đổi khác đang diễn ra; hãy thử lại cùng yêu cầu
TEMPORARILY_UNAVAILABLE503Có, sau Retry-AfterMáy chủ hiện đang bận; hãy thử lại sau thời gian Retry-After. details.reason "staging_full": bộ nhớ tạm đã đầy, không nhận lượt tải lên mới (Retry-After khoảng 10 phút); các lượt tải lên đang diễn ra vẫn tiếp tục hoạt động
PAYLOAD_TOO_LARGE413KhôngBody của yêu cầu (hoặc một phần) lớn hơn mức máy chủ chấp nhận
REMOTE_TOO_LARGEtheo URLKhôngTrong kết quả remote-uploads: tệp vượt giới hạn tải lên từ URL
RATE_LIMITED429Có, sau Retry-AfterQuá nhiều yêu cầu cho nhóm này
INTERNAL_ERROR500CóLỗi máy chủ; chi tiết được ghi log, không bao giờ trả về
MAINTENANCE503Có, sau Retry-AfterTải lên mới tạm thời bị dừng; thao tác đọc vẫn hoạt động
UPLOADS_TEMPORARILY_UNAVAILABLE503Có, sau Retry-AfterKhông đọc được bộ đếm tải lên của chúng tôi; không có phiên nào được mở
SHUTTING_DOWN503Có, sau Retry-AfterMáy chủ đang khởi động lại (Retry-After 5 giây); hãy chờ rồi gửi lại cùng yêu cầu — chưa có gì được xử lý

Vì sao một host bị bỏ qua

Đây không phải là lỗi: chúng nằm trong skipped[].reason của một lệnh start thành công (và của distribution trong phản hồi hoàn tất tệp). Các host khác vẫn nhận tệp. Chỉ khi không host nào đã chọn có thể nhận tệp thì lệnh gọi mới thất bại: PROVIDER_REJECTS_FILE (không host nào nhận tệp này), NO_CONNECTED_PROVIDERS (host nào cũng cần tài khoản của riêng bạn), NO_AVAILABLE_PROVIDERS (hiện không host nào nhận tải lên) hoặc NO_VALID_PROVIDERS (không slug nào khớp với host đang bật).

Lý doÝ nghĩa
UNKNOWN_PROVIDERKhông có host nào với slug này — hãy kiểm tra chính tả so với GET /api/v1/providers
PROVIDER_DISABLEDHost đang bị tắt hoặc đang bảo trì
ACCOUNT_REQUIREDHost chỉ nhận tải lên vào tài khoản của riêng bạn — hãy kết nối ở trang Kết nối
GUEST_UPLOAD_OFFHost hiện không nhận tải lên và không thể kết nối với tài khoản
DAILY_LIMIT_REACHEDGiới hạn hằng ngày của host cho tải lên không cần tài khoản tạm thời đã hết (tối đa 24 giờ) — hãy kết nối tài khoản của riêng bạn để vẫn tải lên được
FILE_TOO_LARGETệp vượt giới hạn dung lượng của host này
MIME_NOT_ALLOWEDHost không nhận loại tệp này
ALREADY_ATTEMPTEDHost này đã được thử cho tệp này, nên tệp không được gửi lại tới đó

Tài liệu tham chiếu API liệt kê các mã mà từng endpoint có thể trả về.