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_…
1Buka sesi
POST /
api/ v1/ upload-sessions filename + sizeBytes; dapatkan sessionId dan chunkSize
2Kirim chunk
PATCH /
api/ v1/ upload-sessions/ {id}/ chunks byte mentah secara berurutan; balasan yang melengkapi file berisi fileId
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).
| Lingkup | Menjangkau |
|---|---|
upload:write | Sesi 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:read | Daftar file, detail file, status mirror dan pekerjaan |
file:write | Pengaturan berbagi pada file |
file:delete | Menghapus 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.
| Metode | Path | Lingkup | Fungsinya |
|---|---|---|---|
| POST | / | upload:write | Membuka sesi unggah (opsional dengan rencana distribusi) |
| PATCH | / | upload:write | Mengirim chunk byte berikutnya |
| HEAD | / | upload:write | Titik untuk melanjutkan: header Upload-Offset |
| GET | / | upload:writefile:read | Status sesi: byte yang diterima, fileId, finalizable |
| GET | / | upload:writefile:read | Batas unggah, pemakaian, dan sesi Anda yang belum selesai |
| POST | / | upload:write | Menyelesaikan unggahan yang balasan terakhirnya hilang (aman untuk dicoba ulang) |
| POST | / | upload:write | Mencegah distribusi tertunda dimulai dengan sendirinya |
| PUT | / | upload:write | Mengganti rencana distribusi sebuah unggahan |
| DELETE | / | upload:write | Membatalkan unggahan yang belum selesai dan mengosongkan slotnya |
| POST | / | upload:write | Mengambil file dari URL http(s) ke akun Anda |
| POST | / | upload:write | Mengirim file ke host pilihan Anda |
| GET | / | upload:writefile:read | Status pekerjaan, setiap host, dan tautan berbagi (shareTakenDown menandai halaman yang diturunkan) |
| GET | / | file:read | Daftar file Anda (paginasi kursor, pencarian, filter) |
| GET | / | file:read | Satu file: ukuran, checksum, pekerjaan, pengaturan berbagi, statistik |
| GET | / | file:read | Setiap salinan file: host, tautan, kesehatan, klik |
| PATCH | / | file:write | Kata sandi berbagi, masa berlaku, visibilitas |
| DELETE | / | file:delete | Menghapus file dan (secara bawaan) salinannya di host |
| GET | / | tidak ada (publik) | Batas saat ini: file terbesar, host per file, batas unggah URL |
| GET | / | tidak ada (publik) | Katalog host, dengan slug yang Anda kirim di providerSlugs |
| GET | / | tidak ada (publik) | Tingkat keberhasilan unggah terukur per host |
| GET | / | tidak ada (publik) | Total platform selama 30 hari terakhir: file, mirror aktif, tingkat keberhasilan |
Unggah file dan distribusikan
- Buka sesi dengan
POST /api/v1/upload-sessions.filenamedansizeBytes(panjang byte yang tepat) wajib diisi;mimeTypedanidempotencyKeyberupa UUID bersifat opsional — mengulang permintaan dengan kunci yang sama mengembalikan sesi yang sudah ada alih-alih membuka sesi kedua. Balasannya berisidata.sessionId(bukanid) dandata.chunkSize. - Kirim byte-nya dengan
PATCH /api/v1/upload-sessions/{id}/chunks: byte mentah, content typeapplication/offset+octet-stream, dan posisi awal chunk di headerupload-offset. Chunk dikirim berurutan, atau hinggamaxChunksAheadchunk lebih dulu; jika mengirim berurutan, gunakandata.uploadedBytesdari setiap balasan sebagai offset berikutnya. Kirim chunk berukuranchunkSizebyte; setiap chunk kecuali yang terakhir minimal 5 MiB, dan satu unggahan dapat memiliki paling banyak 10 000 chunk. Balasan yang melengkapi file berisidata.fileId. Untuk kecepatan lebih, Anda boleh mengirim 2–3 chunk dari file yang sama secara bersamaan. Kirim chunk pertama sendirian; balasannya memberikan nilaidata.maxChunksAheadyang sebenarnya (4 jika chunk pertama berupa irisanchunkSizeutuh, 0 = hanya berurutan). Jika chunk pertama berupa irisanchunkSizeutuh, setiap chunk berikutnya juga harus demikian (berurutan maupun lebih dulu): dimulai pada kelipatanchunkSizedan berukuran tepatchunkSizebyte (yang terakhir: sisa file). Chunk yang dikirim mendahuluiuploadedBytesharus berupa irisan semacam itu dan dimulai paling jauhdata.maxChunksAheadchunk di depan; jika tidak, akan mendapat409 CHUNK_MISALIGNEDatau409 CHUNK_OUT_OF_WINDOW.uploadedByteshanya menghitung byte yang diterima tanpa celah, dan chunk mana pun yang melengkapi file akan mendapat balasan berisifileId. Mengirim ulang chunk yang sudah sampai adalah keberhasilan yang tidak berbahaya. - Distribusikan dengan
POST /api/v1/mirror-tasks/start:fileIddanproviderSlugswajib diisi (slug berasal dariGET /api/v1/providers). Opsional:minSuccess(bawaan 1 — berapa host yang harus menerima file agar pekerjaan tidak gagal; statusnyacompletedhanya jika setiap host juga menerimanya, selain itupartially_completed. Host yang menolak jenis file ini tidak dihitung),sharePassword,expiresInDaysatauexpiresAt. Balasannya berisiuploadJobId,taskCount,shareSlug,alreadyStarted, danskipped[]— host yang tidak dapat menerima file ini dilewati, bukan gagal, jadi bacaskipped[](alasannya tercantum di bawah). Saat ini satu file dapat dikirim ke paling banyak 50 host. - Pantau hingga selesai dengan
GET /api/v1/mirror-tasks/{uploadJobId}setiap beberapa detik sampaidata.terminalbernilaitrue. Balasannya mencantumkan setiap host ditasks[](providerSlug,status,mirrorUrl,errorCode) dan tautan berbagi didata.shareUrl.data.shareTakenDownbernilaitruejika 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.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";
}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).
{
"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
}
]
}
}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 -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.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.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"requests; atur 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+, modul ES; atur 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; atur 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
Tambahkan endpoint di halaman Webhook. URL harus memakai https://; rahasia penandatanganannya (whsec_…) ditampilkan sekali, saat Anda membuatnya. Endpoint tanpa peristiwa yang dipilih menerima semuanya.
| Peristiwa | Kapan |
|---|---|
upload.completed | Setiap host menerima file, dan setidaknya minSuccess host menerimanya — host yang menolak file ini (rejected) atau dibatalkan tidak dihitung |
upload.partially_completed | Setidaknya minSuccess host menerima file, tetapi setidaknya satu host lain gagal |
upload.failed | Kurang dari minSuccess host yang menerima file (minSuccess 0 dihitung sebagai 1) |
upload.quarantined | Pemindaian malware menandai file (hanya jika pemindaian diaktifkan) |
provider.upload_succeeded | Satu host menerima file — dikirim sekali per host |
provider.upload_failed | Satu host menyerah terhadap file — dikirim sekali per host |
webhook.test | Anda 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.
{
"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);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+ murni
<?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 deliveredBatas 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.
| Kelompok | Endpoint | Per kunci | Rentang |
|---|---|---|---|
| Memulai unggahan | POST /POST /DELETE / | 60 | 1 menit |
| Mengunggah chunk | PATCH / | 600 | 1 menit |
| Polling progres | GET /HEAD /GET /GET / | 600 | 1 menit |
| Pengaturan distribusi unggahan | POST /PUT / | 300 | 1 menit |
| Memulai distribusi | POST / | 30 | 1 menit |
| Unggah jarak jauh (URL) | POST / | 20 | 10 menit |
| Membaca file | GET /GET /GET / | 300 | 1 menit |
| Mengubah file | PATCH /DELETE / | 60 | 1 menit |
| Katalog publik | GET /GET /GET /GET / | 300 | 1 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.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Kode | HTTP | Coba ulang? | Arti |
|---|---|---|---|
NO_TOKEN | 401 | Tidak | Tidak ada kunci API yang dikirim |
INVALID_API_KEY | 401 | Tidak | Kunci salah atau sudah dicabut |
INSUFFICIENT_SCOPE | 403 | Tidak | Kunci tidak memiliki lingkup yang diperlukan endpoint ini |
API_KEY_NOT_ALLOWED | 403 | Tidak | Endpoint ini tidak dapat digunakan dengan kunci API |
EMAIL_NOT_VERIFIED | 403 | Tidak | Verifikasi email akun terlebih dahulu; sesi yang terbuka tetap berfungsi |
SESSION_REVOKED | 401 | Tidak | Sesi masuk telah diakhiri (reset atau penggantian kata sandi, keluar); masuk lagi |
ACCOUNT_INACTIVE | 403 | Tidak | Akun ditangguhkan atau dijadwalkan untuk dihapus |
ACCOUNT_DISABLED | 401 / 409 | Tidak | Akun ditangguhkan: 401 pada pemeriksaan kunci, 409 jika berubah saat permintaan sedang berjalan |
ACCOUNT_PENDING_DELETION | 409 | Tidak | Akun dijadwalkan untuk dihapus saat permintaan sedang berjalan; tidak ada hal baru yang dimulai |
VALIDATION_ERROR | 400 | Tidak | Body atau parameter tidak valid; lihat details |
FILE_REJECTED | 400 | Tidak | Jenis atau ukuran file tidak diizinkan; details.reason menyebutkan yang mana |
TOO_MANY_MIRRORS | 400 | Tidak | Jumlah host melebihi yang diizinkan untuk satu file |
NO_CONNECTED_PROVIDERS | 400 | Tidak | Setiap host terpilih memerlukan akun Anda sendiri dan tidak ada yang terhubung |
PROVIDER_REJECTS_FILE | 400 | Tidak | Tidak ada host terpilih yang menerima jenis atau ukuran file ini |
NO_AVAILABLE_PROVIDERS | 400 | Tidak | Tidak 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_PROVIDERS | 400 | Tidak | Tidak ada nilai providerSlugs yang cocok dengan host yang aktif; lihat GET /api/v1/providers |
INVALID_JOB_STATE | 400 | Tidak | Pekerjaan tidak dapat dimulai dalam statusnya saat ini |
JOB_NOT_READY | 400 | Tidak | File belum memiliki pekerjaan distribusi |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | Tidak | File tidak muat dalam 10 000 chunk dengan ukuran chunk sesi; details.limitBytes |
MISSING_OFFSET | 400 | Tidak | Chunk dikirim tanpa header upload-offset berupa angka |
RAW_BODY_REQUIRED | 400 | Tidak | Body chunk harus berupa byte mentah dengan content-type application/offset+octet-stream |
TOO_MANY_URLS | 400 | Tidak | Jumlah URL dalam satu permintaan remote-uploads melebihi batas |
FILE_NOT_FOUND | 404 | Tidak | File tersebut tidak ada di akun Anda (atau sudah dihapus) |
JOB_NOT_FOUND | 404 | Tidak | Pekerjaan distribusi tersebut tidak ada di akun Anda |
SESSION_NOT_FOUND | 404 | Tidak | Sesi unggah tersebut tidak ada di akun Anda |
SHARE_NOT_FOUND | 404 | Tidak | File belum memiliki halaman berbagi |
QUOTA_EXCEEDED | 409 | Tidak | Batas unggah harian atau serentak; details.retryAt menyebutkan kapan kembali tersedia |
CHUNK_OFFSET_CONFLICT | 409 | Tidak | upload-offset tidak cocok dengan byte yang diterima; lanjutkan dari HEAD |
CHUNK_TOO_SMALL | 409 | Tidak | Chunk selain yang terakhir berukuran di bawah 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | Tidak | Lebih dari 10 000 chunk; kirim chunk yang lebih besar |
CHUNK_MISALIGNED | 409 | Tidak | Chunk 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_WINDOW | 409 | Tidak | Chunk dimulai lebih dari maxChunksAhead chunk setelah uploadedBytes, atau melewatinya sama sekali sebelum chunk pertama diterima; kirim lagi setelah chunk sebelumnya |
CHUNK_EXCEEDS_DECLARED_SIZE | 409 | Tidak | Chunk melewati ukuran file yang dinyatakan saat sesi dibuat |
CHUNK_EMPTY | 409 | Tidak | Chunk tidak berisi byte |
CHUNK_NOT_RECEIVABLE | 409 | Tidak | Sesi tidak lagi menerima data (sudah selesai, dibatalkan, atau kedaluwarsa); buka sesi baru |
SESSION_EXPIRED | 409 | Tidak | Sesi unggah sudah kedaluwarsa; buka sesi baru |
SESSION_NOT_RECEIVABLE | 409 | Tidak | Sesi sudah dibatalkan atau kedaluwarsa dan tidak menerima perubahan lagi |
SESSION_COMPLETED | 409 | Tidak | Unggahan sudah selesai; hapus file sebagai gantinya |
UPLOAD_INCOMPLETE | 409 | Tidak | Belum semua byte sampai; kirim chunk yang tersisa terlebih dahulu (details berisi jumlahnya) |
IDEMPOTENCY_KEY_CONFLICT | 409 | Tidak | idempotencyKey ini sudah dipakai oleh unggahan lain; gunakan kunci unik untuk setiap unggahan |
SOURCE_GONE | 409 | Tidak | Salinan 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_DISTRIBUTABLE | 409 | Tidak | Pekerjaan gagal, dibatalkan, atau berada dalam status yang tidak dapat didistribusikan lagi |
SHARE_TAKEN_DOWN | 409 | Tidak | Halaman berbagi file telah diturunkan, jadi file tidak dapat dikirim ke host lain |
FINALIZING | 409 | Ya | Permintaan lain sedang merakit file; tanyakan lagi dalam beberapa detik |
CONFLICT | 409 | Ya | Bertabrakan dengan perubahan lain yang sedang berlangsung; coba ulang permintaan yang sama |
TEMPORARILY_UNAVAILABLE | 503 | Ya, setelah Retry-After | Server 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_LARGE | 413 | Tidak | Body permintaan (atau satu chunk) lebih besar dari yang diterima server |
REMOTE_TOO_LARGE | per URL | Tidak | Dalam hasil remote-uploads: file melebihi batas unggah URL |
RATE_LIMITED | 429 | Ya, setelah Retry-After | Terlalu banyak permintaan untuk kelompok ini |
INTERNAL_ERROR | 500 | Ya | Error server; detail dicatat di log, tidak pernah dikembalikan |
MAINTENANCE | 503 | Ya, setelah Retry-After | Unggahan baru sedang dijeda; pembacaan tetap berfungsi |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Ya, setelah Retry-After | Penghitung unggahan kami tidak dapat dibaca; tidak ada sesi yang dibuka |
SHUTTING_DOWN | 503 | Ya, setelah Retry-After | Server 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).
| Alasan | Arti |
|---|---|
UNKNOWN_PROVIDER | Tidak ada host dengan slug ini — periksa ejaannya dengan GET /api/v1/providers |
PROVIDER_DISABLED | Host sedang dinonaktifkan atau dalam pemeliharaan |
ACCOUNT_REQUIRED | Host hanya menerima unggahan ke akun Anda sendiri — hubungkan di halaman Koneksi |
GUEST_UPLOAD_OFF | Host sedang tidak menerima unggahan dan tidak dapat dihubungkan ke akun |
DAILY_LIMIT_REACHED | Batas harian host untuk unggahan tanpa akun sudah habis untuk sementara (hingga 24 jam) — hubungkan akun Anda sendiri agar tetap dapat mengunggah |
FILE_TOO_LARGE | File melebihi batas ukuran host ini |
MIME_NOT_ALLOWED | Host tidak menerima jenis file ini |
ALREADY_ATTEMPTED | Host ini sudah dicoba untuk file ini, jadi file tidak dikirim lagi ke sana |
Referensi API mencantumkan kode yang dapat dikembalikan setiap endpoint.