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_…
1Mở phiên
POST /
api/ v1/ upload-sessions filename + sizeBytes; nhận sessionId và chunkSize
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
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 vi | Truy cập được |
|---|---|
upload:write | Phiê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:read | Liệt kê tệp, chi tiết tệp, trạng thái bản sao và tác vụ |
file:write | Cài đặt chia sẻ của tệp |
file:delete | Xó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ẫn | Phạm vi | Chức năng |
|---|---|---|---|
| POST | / | upload:write | Mở phiên tải lên (có thể kèm kế hoạch phân phối) |
| PATCH | / | upload:write | Gửi phần byte tiếp theo |
| HEAD | / | upload:write | Vị trí để tiếp tục: header Upload-Offset |
| GET | / | upload:writefile:read | Trạng thái phiên: số byte đã nhận, fileId, finalizable |
| GET | / | upload:writefile:read | Giớ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 | / | upload:write | Hoà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 | / | upload:write | Ngăn việc phân phối hoãn lại tự bắt đầu |
| PUT | / | upload:write | Thay kế hoạch phân phối của một lượt tải lên |
| DELETE | / | upload:write | Hủy lượt tải lên chưa hoàn tất và giải phóng chỗ |
| POST | / | upload:write | Lấy tệp từ URL http(s) vào tài khoản của bạn |
| POST | / | upload:write | Gửi tệp đến các host bạn chọn |
| GET | / | upload:writefile:read | Trạng thái tác vụ, từng host và liên kết chia sẻ (shareTakenDown đánh dấu trang đã bị gỡ) |
| GET | / | file:read | Liệt kê tệp của bạn (phân trang bằng cursor, tìm kiếm, bộ lọc) |
| GET | / | file:read | Một tệp: kích thước, checksum, tác vụ, cài đặt chia sẻ, thống kê |
| GET | / | file:read | Mọi bản sao của tệp: host, liên kết, tình trạng, lượt nhấp |
| PATCH | / | file:write | Mật khẩu chia sẻ, thời hạn, chế độ hiển thị |
| DELETE | / | file:delete | Xóa tệp và (mặc định) các bản sao của nó trên host |
| GET | / | khô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 | / | không (công khai) | Danh mục host, kèm các slug bạn gửi trong providerSlugs |
| GET | / | không (công khai) | Tỷ lệ tải lên thành công đo được theo từng host |
| GET | / | khô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
- Mở phiên bằng
POST /api/v1/upload-sessions.filenamevàsizeBytes(độ dài chính xác tính bằng byte) là bắt buộc;mimeTypevàidempotencyKeydạ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ứadata.sessionId(không phảiid) vàdata.chunkSize. - Gửi các byte bằng
PATCH /api/v1/upload-sessions/{id}/chunks: byte thô, content typeapplication/offset+octet-stream, và vị trí bắt đầu của phần trong headerupload-offset. Các phần được gửi theo thứ tự, hoặc vượt trước tối đamaxChunksAheadphần; khi gửi theo thứ tự, hãy dùngdata.uploadedBytestừ mỗi phản hồi làm offset tiếp theo. Gửi các phần có kích thướcchunkSizebyte; 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ứadata.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ếtdata.maxChunksAheadthực tế (4 nếu phần đầu là một látchunkSizetrọn vẹn, 0 = chỉ theo thứ tự). Nếu phần đầu là một látchunkSizetrọ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ủachunkSizevà dài đúngchunkSizebyte (phần cuối: phần còn lại của tệp). Phần được gửi vượt trướcuploadedBytesphải là một lát như vậy và bắt đầu không quádata.maxChunksAheadphần phía trước, nếu không sẽ nhận409 CHUNK_MISALIGNEDhoặc409 CHUNK_OUT_OF_WINDOW.uploadedByteschỉ 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. - Phân phối bằng
POST /api/v1/mirror-tasks/start:fileIdvàproviderSlugslà 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ỉcompletedkhi 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,expiresInDayshoặcexpiresAt. Phản hồi cóuploadJobId,taskCount,shareSlug,alreadyStartedvà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 đọcskipped[](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. - Theo dõi đến khi xong bằng
GET /api/v1/mirror-tasks/{uploadJobId}mỗi vài giây cho đến khidata.terminallàtrue. Phản hồi liệt kê mọi host trongtasks[](providerSlug,status,mirrorUrl,errorCode) và liên kết chia sẻ trongdata.shareUrl.data.shareTakenDownlàtruekhi 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.jsonrequests
import os, time, requests
API = "https://api.mirroruploadx.com"
H = {"x-api-key": os.environ["MUX_API_KEY"]}
def call(method, path, headers=None, **kw):
r = requests.request(method, API + path, headers={**H, **(headers or {})}, timeout=120, **kw)
body = r.json()
if not body.get("success"):
err = body["error"]
raise RuntimeError(f'{r.status_code} {err["code"]}: {err["message"]}')
return body["data"]
path = "clip.mp4"
size = os.path.getsize(path)
# 1. Open an upload session
s = call("POST", "/api/v1/upload-sessions",
json={"filename": os.path.basename(path), "sizeBytes": size, "mimeType": "video/mp4"})
session, chunk = s["sessionId"], s["chunkSize"]
# 2. Send the bytes in order; the reply says where to continue
offset, last = 0, None
with open(path, "rb") as f:
while offset < size:
f.seek(offset)
last = call("PATCH", f"/api/v1/upload-sessions/{session}/chunks",
headers={"upload-offset": str(offset),
"content-type": "application/offset+octet-stream"},
data=f.read(chunk))
offset = last["uploadedBytes"]
file_id = last["fileId"]
# 3. Distribute
job = call("POST", "/api/v1/mirror-tasks/start",
json={"fileId": file_id, "providerSlugs": ["gofile", "pixeldrain"], "minSuccess": 1})
for sk in job["skipped"]:
print("skipped", sk["slug"], sk["reason"], sk["detail"])
# 4. Poll until terminal
job_id = job["uploadJobId"]
while True:
st = call("GET", f"/api/v1/mirror-tasks/{job_id}")
if st["terminal"]:
break
time.sleep(5)
print(st["status"], st["shareUrl"])
for t in st["tasks"]:
print(t["providerSlug"], t["status"], t["mirrorUrl"] or t["errorCode"])Node.js 18+, fetch
// Node.js 18+ (global fetch), ES module
import { open, stat } from 'node:fs/promises';
import { basename } from 'node:path';
const API = 'https://api.mirroruploadx.com';
const KEY = process.env.MUX_API_KEY;
async function call(method, path, { json, body, headers = {} } = {}) {
const res = await fetch(API + path, {
method,
headers: { 'x-api-key': KEY, ...(json ? { 'content-type': 'application/json' } : {}), ...headers },
body: json ? JSON.stringify(json) : body,
});
const out = await res.json();
if (!out.success) throw new Error(`${res.status} ${out.error.code}: ${out.error.message}`);
return out.data;
}
const path = 'clip.mp4';
const { size } = await stat(path);
// 1. Open an upload session
const { sessionId, chunkSize } = await call('POST', '/api/v1/upload-sessions', {
json: { filename: basename(path), sizeBytes: size, mimeType: 'video/mp4' },
});
// 2. Send the bytes in order; the reply says where to continue
const fh = await open(path);
let offset = 0;
let last;
while (offset < size) {
const buf = Buffer.alloc(Math.min(chunkSize, size - offset));
await fh.read(buf, 0, buf.length, offset);
last = await call('PATCH', `/api/v1/upload-sessions/${sessionId}/chunks`, {
headers: { 'upload-offset': String(offset), 'content-type': 'application/offset+octet-stream' },
body: buf,
});
offset = last.uploadedBytes;
}
await fh.close();
// 3. Distribute
const job = await call('POST', '/api/v1/mirror-tasks/start', {
json: { fileId: last.fileId, providerSlugs: ['gofile', 'pixeldrain'], minSuccess: 1 },
});
for (const s of job.skipped) console.log('skipped', s.slug, s.reason, s.detail);
// 4. Poll until terminal
let st;
do {
await new Promise((r) => setTimeout(r, 5000));
st = await call('GET', `/api/v1/mirror-tasks/${job.uploadJobId}`);
} while (!st.terminal);
console.log(st.status, st.shareUrl);
for (const t of st.tasks) console.log(t.providerSlug, t.status, t.mirrorUrl ?? t.errorCode);PHP 8.1+, ext-curl
<?php
// PHP 8.1+, built-in ext-curl and ext-json only (no Composer)
declare(strict_types=1);
const API = 'https://api.mirroruploadx.com';
function call(string $method, string $path, ?array $json = null, ?string $body = null, array $headers = []): array
{
$h = ['x-api-key: ' . getenv('MUX_API_KEY'), 'expect:']; // no 100-continue round trip
if ($json !== null) {
$h[] = 'content-type: application/json';
$body = json_encode($json, JSON_THROW_ON_ERROR);
}
foreach ($headers as $k => $v) {
$h[] = "$k: $v";
}
$ch = curl_init(API . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $h,
CURLOPT_RETURNTRANSFER => true,
// no total cap (a large part can take minutes); give up on a stalled transfer instead
CURLOPT_TIMEOUT => 0,
CURLOPT_CONNECTTIMEOUT => 15,
CURLOPT_LOW_SPEED_LIMIT => 1024, // bytes per second
CURLOPT_LOW_SPEED_TIME => 60,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
}
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException('network error: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$out = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (empty($out['success'])) {
$err = $out['error'];
throw new RuntimeException("$status {$err['code']}: {$err['message']}");
}
return $out['data'];
}
$path = 'clip.mp4';
$size = filesize($path);
// 1. Open an upload session
$s = call('POST', '/api/v1/upload-sessions',
json: ['filename' => basename($path), 'sizeBytes' => $size, 'mimeType' => 'video/mp4']);
$session = $s['sessionId'];
$chunk = $s['chunkSize'];
// 2. Send the bytes in order, one chunk in memory at a time; the reply says where to continue
$fh = fopen($path, 'rb');
$offset = 0;
$last = null;
while ($offset < $size) {
fseek($fh, $offset);
$last = call('PATCH', "/api/v1/upload-sessions/$session/chunks", body: fread($fh, $chunk), headers: [
'upload-offset' => (string) $offset,
'content-type' => 'application/offset+octet-stream',
]);
$offset = $last['uploadedBytes'];
}
fclose($fh);
$fileId = $last['fileId'];
// 3. Distribute
$job = call('POST', '/api/v1/mirror-tasks/start',
json: ['fileId' => $fileId, 'providerSlugs' => ['gofile', 'pixeldrain'], 'minSuccess' => 1]);
foreach ($job['skipped'] as $sk) {
echo "skipped {$sk['slug']} {$sk['reason']} {$sk['detail']}\n";
}
// 4. Poll until terminal
$jobId = $job['uploadJobId'];
do {
sleep(5);
$st = call('GET', "/api/v1/mirror-tasks/$jobId");
} while (!$st['terminal']);
echo "{$st['status']} {$st['shareUrl']}\n";
foreach ($st['tasks'] as $t) {
echo $t['providerSlug'], ' ', $t['status'], ' ', $t['mirrorUrl'] ?? $t['errorCode'], "\n";
}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).
{
"success": true,
"data": {
"sessionId": "…",
"uploadedBytes": 0,
"chunkSize": 8388608,
"maxChunksAhead": 0
}
}{
"success": true,
"data": {
"uploadedBytes": 10485760,
"completed": true,
"fileId": "…",
"scan": "skipped",
"distributable": true,
"distribution": {
"started": true,
"uploadJobId": "…",
"taskCount": 2,
"shareSlug": "…",
"skipped": []
}
}
}{
"success": true,
"data": {
"uploadJobId": "…",
"taskCount": 2,
"shareSlug": "…",
"skipped": [],
"alreadyStarted": false
}
}{
"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 -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.PHP 8.1+, ext-curl
<?php
// PHP 8.1+, built-in ext-curl and ext-json only (no Composer)
$ch = curl_init('https://api.mirroruploadx.com/api/v1/remote-uploads');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('MUX_API_KEY'), 'content-type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['urls' => ['https://example.com/files/archive.zip']], JSON_THROW_ON_ERROR),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 0, // the request waits while the files download
]);
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException('network error: ' . curl_error($ch));
}
$out = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (empty($out['success'])) {
throw new RuntimeException("{$out['error']['code']}: {$out['error']['message']}");
}
// One result per URL, in order. A failed URL does not fail the batch.
foreach ($out['data']['results'] as $r) {
echo $r['ok']
? "{$r['url']} -> {$r['fileId']}\n"
: "{$r['url']} failed: {$r['code']} {$r['error']}\n";
}
// 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"requests; đặt FILE_ID
import os, requests
API = "https://api.mirroruploadx.com"
H = {"x-api-key": os.environ["MUX_API_KEY"]}
file_id = os.environ["FILE_ID"]
def call(method, path, **kw):
body = requests.request(method, API + path, headers=H, timeout=60, **kw).json()
if not body.get("success"):
raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
return body["data"]
# List your files, page by page
cursor = None
while True:
page = call("GET", "/api/v1/files", params={"limit": 100, **({"cursor": cursor} if cursor else {})})
for f in page["items"]:
print(f["id"], f["name"], f"{f['mirrorCount']}/{f['mirrorTotal']} mirrors")
cursor = page["nextCursor"]
if not cursor:
break
# One file, then every copy of it
print(call("GET", f"/api/v1/files/{file_id}")["share"])
for m in call("GET", f"/api/v1/files/{file_id}/mirrors")["mirrors"]:
print(m["providerSlug"], m["status"], m["url"])
# Share settings: a password and an expiry date (None removes either)
print(call("PATCH", f"/api/v1/files/{file_id}/share",
json={"password": "correct-horse", "expiresAt": "2026-12-31T23:59:59Z"}))
# Delete the file and its copies on hosts
print(call("DELETE", f"/api/v1/files/{file_id}")["note"])Node.js 18+, ES module; đặt FILE_ID
const API = 'https://api.mirroruploadx.com';
const KEY = process.env.MUX_API_KEY;
const fileId = process.env.FILE_ID;
async function call(method, path, json) {
const res = await fetch(API + path, {
method,
headers: { 'x-api-key': KEY, ...(json ? { 'content-type': 'application/json' } : {}) },
body: json ? JSON.stringify(json) : undefined,
});
const out = await res.json();
if (!out.success) throw new Error(`${res.status} ${out.error.code}: ${out.error.message}`);
return out.data;
}
// List your files, page by page
let cursor = null;
do {
const page = await call('GET', `/api/v1/files?limit=100${cursor ? `&cursor=${cursor}` : ''}`);
for (const f of page.items) console.log(f.id, f.name, `${f.mirrorCount}/${f.mirrorTotal} mirrors`);
cursor = page.nextCursor;
} while (cursor);
// One file, then every copy of it
console.log((await call('GET', `/api/v1/files/${fileId}`)).share);
for (const m of (await call('GET', `/api/v1/files/${fileId}/mirrors`)).mirrors) {
console.log(m.providerSlug, m.status, m.url);
}
// Share settings: a password and an expiry date (null removes either)
console.log(await call('PATCH', `/api/v1/files/${fileId}/share`, {
password: 'correct-horse',
expiresAt: '2026-12-31T23:59:59Z',
}));
// Delete the file and its copies on hosts
console.log((await call('DELETE', `/api/v1/files/${fileId}`)).note);PHP 8.1+, ext-curl; đặt FILE_ID
<?php
// PHP 8.1+, built-in ext-curl and ext-json only (no Composer)
declare(strict_types=1);
const API = 'https://api.mirroruploadx.com';
$fileId = getenv('FILE_ID');
function call(string $method, string $path, ?array $json = null, ?string $body = null, array $headers = []): array
{
$h = ['x-api-key: ' . getenv('MUX_API_KEY'), 'expect:']; // no 100-continue round trip
if ($json !== null) {
$h[] = 'content-type: application/json';
$body = json_encode($json, JSON_THROW_ON_ERROR);
}
foreach ($headers as $k => $v) {
$h[] = "$k: $v";
}
$ch = curl_init(API . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $h,
CURLOPT_RETURNTRANSFER => true,
// no total cap (a large part can take minutes); give up on a stalled transfer instead
CURLOPT_TIMEOUT => 0,
CURLOPT_CONNECTTIMEOUT => 15,
CURLOPT_LOW_SPEED_LIMIT => 1024, // bytes per second
CURLOPT_LOW_SPEED_TIME => 60,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
}
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException('network error: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$out = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (empty($out['success'])) {
$err = $out['error'];
throw new RuntimeException("$status {$err['code']}: {$err['message']}");
}
return $out['data'];
}
// List your files, page by page (http_build_query drops a null cursor)
$cursor = null;
do {
$page = call('GET', '/api/v1/files?' . http_build_query(['limit' => 100, 'cursor' => $cursor]));
foreach ($page['items'] as $f) {
echo "{$f['id']} {$f['name']} {$f['mirrorCount']}/{$f['mirrorTotal']} mirrors\n";
}
$cursor = $page['nextCursor'];
} while ($cursor);
// One file, then every copy of it
print_r(call('GET', "/api/v1/files/$fileId")['share']);
foreach (call('GET', "/api/v1/files/$fileId/mirrors")['mirrors'] as $m) {
echo "{$m['providerSlug']} {$m['status']} {$m['url']}\n";
}
// Share settings: a password and an expiry date (null removes either)
print_r(call('PATCH', "/api/v1/files/$fileId/share",
json: ['password' => 'correct-horse', 'expiresAt' => '2026-12-31T23:59:59Z']));
// Delete the file and its copies on hosts
echo call('DELETE', "/api/v1/files/$fileId")['note'], "\n";{
"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ện | Khi nào |
|---|---|
upload.completed | Mọ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.quarantined | Trình quét phần mềm độc hại đã gắn cờ tệp (chỉ khi bật quét) |
provider.upload_succeeded | Một host đã nhận tệp — gửi một lần cho mỗi host |
provider.upload_failed | Một host đã bỏ cuộc với tệp — gửi một lần cho mỗi host |
webhook.test | Bạ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.
{
"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);Flask
import hashlib, hmac, os, time
from flask import Flask, abort, request
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(kv.strip().split("=", 1) for kv in header.split(",") if "=" in kv)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or not v1 or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
app = Flask(__name__)
@app.post("/hooks/mirroruploadx")
def hook():
# get_data(): the raw bytes, exactly as signed
if not verify(request.get_data(), request.headers.get("X-MUX-Signature", ""),
os.environ["MUX_WEBHOOK_SECRET"]):
abort(401)
payload = request.get_json()
print(payload["event"], payload["data"].get("uploadJobId"))
return "", 204 # any 2xx counts as deliveredPHP 8.1+ thuần
<?php
// Plain PHP 8.1+ endpoint, e.g. public/hooks/mirroruploadx.php
declare(strict_types=1);
function verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
$parts = [];
foreach (explode(',', $header) as $kv) {
[$k, $v] = array_pad(explode('=', $kv, 2), 2, '');
$parts[trim($k)] = trim($v);
}
$t = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';
if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > $tolerance) {
return false; // malformed, or too old: replay
}
$expected = hash_hmac('sha256', "$t.$rawBody", $secret);
return hash_equals($expected, $v1);
}
// php://input: the raw bytes, exactly as signed (not $_POST, not re-encoded JSON)
$raw = file_get_contents('php://input');
if (!verify($raw, $_SERVER['HTTP_X_MUX_SIGNATURE'] ?? '', (string) getenv('MUX_WEBHOOK_SECRET'))) {
http_response_code(401);
exit;
}
$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
error_log($payload['event'] . ' ' . ($payload['data']['uploadJobId'] ?? ''));
http_response_code(204); // any 2xx counts as deliveredGiớ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óm | Endpoint | Mỗi khóa | Khoảng thời gian |
|---|---|---|---|
| Bắt đầu tải lên | POST /POST /DELETE / | 60 | 1 phút |
| Tải lên các phần | PATCH / | 600 | 1 phút |
| Thăm dò tiến độ | GET /HEAD /GET /GET / | 600 | 1 phút |
| Cài đặt phân phối cho lượt tải lên | POST /PUT / | 300 | 1 phút |
| Bắt đầu phân phối | POST / | 30 | 1 phút |
| Tải lên từ xa (URL) | POST / | 20 | 10 phút |
| Đọc tệp | GET /GET /GET / | 300 | 1 phút |
| Thay đổi tệp | PATCH /DELETE / | 60 | 1 phút |
| Danh mục công khai | GET /GET /GET /GET / | 300 | 1 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ợ.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Mã | HTTP | Thử lại? | Ý nghĩa |
|---|---|---|---|
NO_TOKEN | 401 | Không | Không có khóa API nào được gửi |
INVALID_API_KEY | 401 | Không | Khóa sai hoặc đã bị thu hồi |
INSUFFICIENT_SCOPE | 403 | Không | Khóa thiếu phạm vi mà endpoint này cần |
API_KEY_NOT_ALLOWED | 403 | Không | Không thể dùng endpoint này bằng khóa API |
EMAIL_NOT_VERIFIED | 403 | Không | Hã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_REVOKED | 401 | Không | Phiê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_INACTIVE | 403 | Không | Tài khoản bị đình chỉ hoặc đã được lên lịch xóa |
ACCOUNT_DISABLED | 401 / 409 | Không | Tà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_DELETION | 409 | Không | Tà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_ERROR | 400 | Không | Body hoặc tham số không hợp lệ; xem details |
FILE_REJECTED | 400 | Không | Loại hoặc kích thước tệp không được phép; details.reason cho biết cụ thể |
TOO_MANY_MIRRORS | 400 | Không | Nhiều host hơn mức một tệp được phép |
NO_CONNECTED_PROVIDERS | 400 | Không | Mọ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_FILE | 400 | Không | Không host nào đã chọn nhận loại hoặc kích thước tệp này |
NO_AVAILABLE_PROVIDERS | 400 | Không | Hiệ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_PROVIDERS | 400 | Không | Không giá trị providerSlugs nào khớp với host đang bật; xem GET /api/v1/providers |
INVALID_JOB_STATE | 400 | Không | Không thể bắt đầu tác vụ ở trạng thái hiện tại |
JOB_NOT_READY | 400 | Không | Tệp chưa có tác vụ phân phối |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | Không | Tệ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_OFFSET | 400 | Không | Một phần được gửi mà không có header upload-offset dạng số |
RAW_BODY_REQUIRED | 400 | Không | Body của phần phải là byte thô với content-type application/offset+octet-stream |
TOO_MANY_URLS | 400 | Không | Số URL trong một yêu cầu remote-uploads vượt mức cho phép |
FILE_NOT_FOUND | 404 | Không | Không có tệp này trong tài khoản của bạn (hoặc tệp đã bị xóa) |
JOB_NOT_FOUND | 404 | Không | Không có tác vụ phân phối này trong tài khoản của bạn |
SESSION_NOT_FOUND | 404 | Không | Không có phiên tải lên này trong tài khoản của bạn |
SHARE_NOT_FOUND | 404 | Không | Tệp chưa có trang chia sẻ |
QUOTA_EXCEEDED | 409 | Khô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_CONFLICT | 409 | Không | upload-offset không khớp với số byte đã nhận; hãy tiếp tục từ HEAD |
CHUNK_TOO_SMALL | 409 | Không | Một phần không phải phần cuối nhỏ hơn 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | Không | Nhiều hơn 10 000 phần; hãy gửi các phần lớn hơn |
CHUNK_MISALIGNED | 409 | Không | Phầ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_WINDOW | 409 | Không | Mộ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_SIZE | 409 | Không | Phần vượt quá kích thước tệp đã khai báo khi tạo phiên |
CHUNK_EMPTY | 409 | Không | Phần không có byte nào |
CHUNK_NOT_RECEIVABLE | 409 | Không | Phiê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_EXPIRED | 409 | Không | Phiên tải lên đã hết hạn; hãy mở phiên mới |
SESSION_NOT_RECEIVABLE | 409 | Không | Phiên đã bị hủy hoặc hết hạn và không nhận thêm thay đổi |
SESSION_COMPLETED | 409 | Không | Lượt tải lên đã hoàn tất; hãy xóa tệp thay vì vậy |
UPLOAD_INCOMPLETE | 409 | Không | Chư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_CONFLICT | 409 | Không | idempotencyKey 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_GONE | 409 | Không | Bả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_DISTRIBUTABLE | 409 | Không | Tá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_DOWN | 409 | Không | Trang chia sẻ của tệp đã bị gỡ, nên không thể gửi đến thêm host |
FINALIZING | 409 | Có | Một yêu cầu khác đang ghép tệp; hãy hỏi lại sau vài giây |
CONFLICT | 409 | Có | 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_UNAVAILABLE | 503 | Có, sau Retry-After | Má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_LARGE | 413 | Không | Body 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_LARGE | theo URL | Không | Trong kết quả remote-uploads: tệp vượt giới hạn tải lên từ URL |
RATE_LIMITED | 429 | Có, sau Retry-After | Quá nhiều yêu cầu cho nhóm này |
INTERNAL_ERROR | 500 | Có | Lỗi máy chủ; chi tiết được ghi log, không bao giờ trả về |
MAINTENANCE | 503 | Có, sau Retry-After | Tải lên mới tạm thời bị dừng; thao tác đọc vẫn hoạt động |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Có, sau Retry-After | Khô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_DOWN | 503 | Có, sau Retry-After | Má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_PROVIDER | Khô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_DISABLED | Host đang bị tắt hoặc đang bảo trì |
ACCOUNT_REQUIRED | Host 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_OFF | Host 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_REACHED | Giớ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_LARGE | Tệp vượt giới hạn dung lượng của host này |
MIME_NOT_ALLOWED | Host không nhận loại tệp này |
ALREADY_ATTEMPTED | Host 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ề.