Documentația API
Încarcă un fișier o dată, trimite-l pe hosturile de fișiere alese și primește înapoi un singur link de partajare — din propriul cod.
Actualizat
Un API REST versionat: încarci un fișier pe bucăți, îl trimiți pe hosturile alese, iar toate copiile sunt adunate pe o singură pagină de partajare, cu stare live.
- URL de bază
- https://api.mirroruploadx.com/api/v1
- Autentificare
- x-api-key: mux_…
1Deschide o sesiune
POST /
api/ v1/ upload-sessions filename + sizeBytes; primești sessionId și chunkSize
2Trimite bucățile
PATCH /
api/ v1/ upload-sessions/ {id}/ chunks octeți bruți, în ordine; răspunsul care completează fișierul conține fileId
3Distribuie
POST /
api/ v1/ mirror-tasks/ start fileId + providerSlugs; apoi interoghează jobul
Creează o cheie pe pagina Chei API. Ghidul complet, cu cod, se află în Încărcare și distribuire.
Autentificare
Creează o cheie pe pagina Chei API din panoul tău. Cheia completă (începe cu mux_) este afișată o singură dată, așa că salveaz-o imediat. Trimite-o în headerul x-api-key la fiecare cerere; Authorization: Bearer mux_… este acceptat la fel, pentru clienții care folosesc doar tokenuri bearer.
Cheile au permisiuni limitate: o cheie ajunge doar la endpointurile acoperite de permisiunile ei, iar un apel cu permisiunea greșită returnează 403 INSUFFICIENT_SCOPE, cu permisiunea necesară în mesaj. Setările contului, gestionarea cheilor și webhookurile nu sunt deloc accesibile cu o cheie API (API_KEY_NOT_ALLOWED).
| Permisiune | Acces la |
|---|---|
upload:write | Sesiuni de încărcare (creare, bucăți, finalizare, anulare), cota ta de încărcare, suspendarea sau modificarea distribuirii automate a unei încărcări (hold-distribution, distribution-intent), încărcări de la URL, pornirea distribuirii |
file:read | Listarea fișierelor, detaliile fișierelor, starea oglinzilor și a joburilor |
file:write | Setările de partajare ale unui fișier |
file:delete | Ștergerea unui fișier și a oglinzilor lui |
Endpointuri
Tot ce poate accesa o cheie API, plus endpointurile publice care nu necesită cheie. Când coloana de permisiuni listează două permisiuni, oricare dintre ele este suficientă. Schemele de cerere și răspuns pentru fiecare se află în referința API.
| Metodă | Cale | Permisiune | Ce face |
|---|---|---|---|
| POST | / | upload:write | Deschide o sesiune de încărcare (opțional cu un plan de distribuire) |
| PATCH | / | upload:write | Trimite următoarea bucată de octeți |
| HEAD | / | upload:write | De unde se reia: headerul Upload-Offset |
| GET | / | upload:writefile:read | Starea sesiunii: octeți primiți, fileId, finalizable |
| GET | / | upload:writefile:read | Limitele tale de încărcare, consumul și sesiunile nefinalizate |
| POST | / | upload:write | Finalizează o încărcare al cărei răspuns final s-a pierdut (sigur la reîncercare) |
| POST | / | upload:write | Împiedică pornirea automată a unei distribuiri amânate |
| PUT | / | upload:write | Înlocuiește planul de distribuire al unei încărcări |
| DELETE | / | upload:write | Anulează o încărcare nefinalizată și eliberează-i locul |
| POST | / | upload:write | Preia fișiere de la URL-uri http(s) în contul tău |
| POST | / | upload:write | Trimite un fișier pe hosturile alese |
| GET | / | upload:writefile:read | Starea jobului, fiecare host și linkul de partajare (shareTakenDown semnalează o pagină eliminată) |
| GET | / | file:read | Listează fișierele tale (paginare cu cursor, căutare, filtre) |
| GET | / | file:read | Un fișier: mărime, sumă de control, job, setări de partajare, statistici |
| GET | / | file:read | Toate copiile unui fișier: host, link, stare, clicuri |
| PATCH | / | file:write | Parola de partajare, expirarea, vizibilitatea |
| DELETE | / | file:delete | Șterge un fișier și (implicit) copiile lui de pe hosturi |
| GET | / | niciuna (public) | Limitele curente: cel mai mare fișier, hosturi per fișier, plafoane pentru încărcarea de la URL |
| GET | / | niciuna (public) | Catalogul de hosturi, cu slugurile pe care le trimiți în providerSlugs |
| GET | / | niciuna (public) | Rata de reușită măsurată la încărcare, per host |
| GET | / | niciuna (public) | Totalurile platformei pentru ultimele 30 de zile: fișiere, oglinzi live, rată de reușită |
Încarcă un fișier și distribuie-l
- Deschide o sesiune cu
POST /api/v1/upload-sessions.filenameșisizeBytes(lungimea exactă în octeți) sunt obligatorii;mimeTypeși un UUIDidempotencyKeysunt opționale — repetarea unei cereri cu aceeași cheie returnează sesiunea existentă în loc să deschidă una nouă. Răspunsul conținedata.sessionId(nuid) șidata.chunkSize. - Trimite octeții cu
PATCH /api/v1/upload-sessions/{id}/chunks: octeți bruți, tipul de conținutapplication/offset+octet-streamși poziția de început a bucății în headerulupload-offset. Bucățile se trimit în ordine sau cu până lamaxChunksAheadbucăți înainte; dacă trimiți în ordine, foloseștedata.uploadedBytesdin fiecare răspuns ca offset următor. Trimite bucăți dechunkSizeocteți; fiecare bucată, cu excepția ultimei, trebuie să aibă cel puțin 5 MiB, iar o încărcare poate avea cel mult 10 000 de bucăți. Răspunsul care completează fișierul conținedata.fileId. Pentru viteză mai mare, poți ține simultan în tranzit 2–3 bucăți ale aceluiași fișier. Trimite prima bucată singură; răspunsul ei oferă valoarea realădata.maxChunksAhead(4 dacă prima bucată a fost o felie întreagă dechunkSize, 0 = doar în ordine). Dacă prima bucată a fost o felie întreagă dechunkSize, fiecare bucată ulterioară trebuie să fie la fel (în ordine sau înainte): începe la un multiplu dechunkSizeși are exactchunkSizeocteți (ultima: restul fișierului). O bucată trimisă înainteauploadedBytestrebuie să fie o astfel de felie și să înceapă cu cel multdata.maxChunksAheadbucăți înainte, altfel primește409 CHUNK_MISALIGNEDsau409 CHUNK_OUT_OF_WINDOW.uploadedBytesnumără doar octeții primiți fără goluri, iar bucata care completează fișierul, oricare ar fi ea, primește răspunsul cufileId. Retrimiterea unei bucăți deja sosite este un succes inofensiv. - Distribuie cu
POST /api/v1/mirror-tasks/start:fileIdșiproviderSlugssunt obligatorii (slugurile provin dinGET /api/v1/providers). Opționale:minSuccess(implicit 1 — câte hosturi trebuie să accepte fișierul pentru ca jobul să nu eșueze; estecompleteddoar când și toate celelalte hosturi l-au preluat, altfelpartially_completed. Hosturile care refuză acest tip de fișier nu sunt luate în calcul),sharePassword,expiresInDayssauexpiresAt. Răspunsul conțineuploadJobId,taskCount,shareSlug,alreadyStartedșiskipped[]— un host care nu poate prelua acest fișier este omis, nu eșuat, așa că citeșteskipped[](motivele sunt listate mai jos). Un fișier poate ajunge momentan pe cel mult 50 hosturi. - Urmărește finalizarea cu
GET /api/v1/mirror-tasks/{uploadJobId}la câteva secunde, până cânddata.terminalestetrue. Răspunsul listează fiecare host întasks[](providerSlug,status,mirrorUrl,errorCode) și linkul de partajare îndata.shareUrl.data.shareTakenDownestetruecând acea pagină de partajare a fost eliminată și nu se mai deschide.
Cel mai mare fișier acceptat în prezent are 5,00 GB.
bash, necesită 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";
}Exemple de răspunsuri
Deschiderea unei sesiuni răspunde cu 201. Fiecare bucată, cu excepția ultimei, răspunde cu { uploadedBytes, completed: false, expiresAt }; ultima conține fișierul. distribution apare doar dacă ai transmis un plan la deschiderea sesiunii (vezi mai jos).
{
"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
}
]
}
}Un prim start reușit răspunde cu 202; un nou apel pentru un job care rulează deja răspunde cu 200 și alreadyStarted: true. Când linkul unui host este păstrat privat conform politicii, mirrorUrl este null, iar mirrorHidden este true — pagina de partajare îl listează în continuare.
Renunță la al doilea apel
Transmite distribution când deschizi sesiunea, iar serverul începe distribuirea imediat ce fișierul este complet. Verifică data.distribution în răspunsul care completează fișierul: started: true înseamnă că jobul este în coadă (uploadJobId, shareSlug). Cu started: false și deferred: true, intenționat nu este încă nimic în coadă — vezi mai jos. Cu started: false și fără deferred, încărcarea a reușit, dar distribuirea nu a putut porni (error spune de ce): apelează POST /api/v1/mirror-tasks/start cu fileId. Un error împreună cu deferred: true înseamnă un eșec temporar (de exemplu, toate hosturile sunt ocupate sau în mentenanță): nu apela start și nu încărca fișierul din nou — serverul va reîncerca singur pornirea distribuirii începând cu autoStartAt (până la 5 încercări). Apelează hold-distribution ca să o oprești.
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": "…" } }Adaugă deferred: true în distribution pentru o perioadă de grație: răspunsul final este { started: false, deferred: true, autoStartAt }, iar serverul pornește singur distribuirea la autoStartAt (aproximativ 2 minute mai târziu), dacă nu apelezi tu start înainte. Ca să oprești pornirea automată, apelează POST /api/v1/upload-sessions/{id}/hold-distribution (fără corp; autoStartAt devine null și pornești tu distribuirea). Ca să schimbi planul, apelează PUT /api/v1/upload-sessions/{id}/distribution-intent cu aceleași câmpuri ca distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): înlocuiește planul și ridică suspendarea, iar după ce încărcarea s-a terminat, pornirea automată se mută la cel puțin 2 minute după apel. Dacă distribuirea a pornit deja, ambele răspund cu 200, iar distribution-intent indică alreadyStarted: true.
Pornește în 30 de minute. Când o încărcare se termină și nu este pornită nicio distribuire, copia noastră a fișierului este ștearsă după 30 de minute (dacă un plan de distribuire încă așteaptă să devină disponibile hosturile, după cel mult 72 de ore; încărcările de la URL nu sunt afectate). După aceea, start și distribution-intent răspund cu 409 SOURCE_GONE, iar fișierul trebuie încărcat din nou.
Dacă răspunsul final se pierde
Apelează GET /api/v1/upload-sessions/{id}: un fileId înseamnă că fișierul există; finalizable: true înseamnă că toți octeții au sosit, iar POST /api/v1/upload-sessions/{id}/complete îl finalizează. Acest apel este sigur la reîncercare și nu creează niciodată un al doilea fișier. Un offset nepotrivit primește 409 CHUNK_OFFSET_CONFLICT — trimite HEAD pe sesiune și reia de la headerul ei Upload-Offset. Un nou apel start pentru un job care rulează nu este o eroare: primești 200 cu alreadyStarted: true.
Încărcare de la un URL
POST /api/v1/remote-uploads primește { "urls": [...] } și preia fiecare fișier pentru tine (permisiunea upload:write). Sunt preluate doar linkuri http și https, adresele de rețea private sunt refuzate și se urmează doar un număr limitat de redirecționări. O cerere conține cel mult 10 URL-uri (returnat de GET /api/v1/platform); împarte listele mai lungi.
Limita de mărime per fișier depinde de sursă. Când aceasta raportează mărimea fișierului, fiecare fișier poate avea până la 5,00 GB (limits.remoteUploadPassthroughMaxBytes); când nu o raportează, până la 100,0 MB (limits.remoteUploadMaxBytes). Numele fișierului provine din headerul Content-Disposition al sursei, dacă îl trimite; un nume fără extensie primește una pe baza tipului fișierului.
Cererea așteaptă cât timp se descarcă fișierele. Dacă conexiunea cade înainte, fișierul ajunge totuși în contul tău — îl găsești cu GET /api/v1/files. Fiecare fileId este apoi distribuit cu POST /api/v1/mirror-tasks/start, ca mai sus.
Când spațiul de stocare temporar este plin, întreaga cerere primește 503 TEMPORARILY_UNAVAILABLE cu details.reason: "staging_full" și un header Retry-After. Dacă un singur URL nu încape, acea intrare din results[] are ok: false și același cod; un rezultat per URL nu are header, așa că timpul de așteptare în secunde se află în 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.Gestionarea fișierelor
Fișierele tale rămân în cont după încărcare. Listează-le cu GET /api/v1/files (limit până la 100; transmite nextCursor din răspuns ca cursor pentru pagina următoare, q caută după nume). GET /api/v1/files/{id} returnează un fișier cu jobul, setările de partajare și statisticile de vizualizare; GET /api/v1/files/{id}/mirrors listează fiecare copie cu linkul, starea și clicurile ei.
PATCH /api/v1/files/{id}/share (permisiunea file:write) modifică pagina de partajare: password (4–128 caractere, null o elimină — nu este returnată niciodată, doar passwordProtected), expiresAt (dată ISO, null pentru fără expirare), visibility și hideDownloadCount. Trimite doar câmpurile pe care vrei să le schimbi. DELETE /api/v1/files/{id} (permisiunea file:delete) elimină fișierul și pune în coadă pentru ștergere copiile lui de pe hosturi; adaugă ?keepMirrors=true ca să le păstrezi. Unele hosturi nu acceptă ștergerea, așa că o copie poate rămâne acolo.
bash, necesită jq; setează 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; setează 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; setează 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; setează 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."
}
}Webhookuri
Adaugă un endpoint pe pagina Webhookuri. URL-ul trebuie să folosească https://; secretul de semnare (whsec_…) este afișat o singură dată, la creare. Un endpoint fără evenimente selectate le primește pe toate.
| Eveniment | Când |
|---|---|
upload.completed | Toate hosturile au acceptat fișierul, iar cel puțin minSuccess l-au acceptat — hosturile care au refuzat acest fișier (rejected) sau au fost anulate nu sunt luate în calcul |
upload.partially_completed | Cel puțin minSuccess hosturi au acceptat fișierul, dar cel puțin un alt host a eșuat |
upload.failed | Mai puțin de minSuccess hosturi au acceptat fișierul (minSuccess 0 contează ca 1) |
upload.quarantined | Scanarea antimalware a semnalat fișierul (doar când scanarea este activată) |
provider.upload_succeeded | Un host a acceptat fișierul — trimis o dată per host |
provider.upload_failed | Un host a renunțat la fișier — trimis o dată per host |
webhook.test | Ai apăsat Testează pe pagina Webhookuri |
Fiecare livrare este un singur POST cu un corp JSON și headerele X-MUX-Event și X-MUX-Signature. Orice răspuns 2xx în 10 secunde contează ca livrat; redirecționările nu sunt urmate. O livrare eșuată (eroare de rețea, timeout, 408, 425, 429 sau 5xx) este reîncercată după 1, 5 și 30 de minute, cu același corp; celelalte coduri 4xx și redirecționările nu sunt reîncercate. Fiecare încercare conține X-MUX-Delivery-Attempt (1–4) și o semnătură nouă, așa că elimină duplicatele după corp. Ordinea livrărilor nu este garantată (un eveniment reîncercat poate sosi după unul mai nou); compară data și createdAt înainte de a acționa. Folosește GET /api/v1/mirror-tasks/{uploadJobId} ca să recuperezi starea. După 15 livrări consecutive a căror ultimă încercare a eșuat, sau după o oră de eșecuri fără niciun succes, endpointul este suspendat; reactivarea lui resetează contorul. O livrare webhook.test (butonul Testează) este trimisă o singură dată, cu X-MUX-Delivery-Attempt: 1, și nu este reîncercată niciodată.
{
"event": "provider.upload_succeeded",
"createdAt": "2026-09-25T12:00:00.000Z",
"data": {
"uploadJobId": "…",
"fileId": "…",
"provider": "gofile",
"providerName": "Gofile",
"status": "succeeded",
"mirrorUrl": "https://…"
}
}Evenimentele upload.* conțin uploadJobId, fileId și status; provider.upload_failed conține errorCode în loc de mirrorUrl.
Verificarea semnăturii
Headerul arată ca t=1727265600,v1=5f2b…: t este momentul semnării în secunde Unix, v1 este HMAC-SHA256 hex al <t>.<raw body>, cu cheia secretă a endpointului tău. Calculează hashul pe octeții bruți exact așa cum au fost primiți, compară în timp constant și respinge marcajele temporale mai vechi de 5 minute.
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+ simplu
<?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 deliveredLimite de rată
Limitele sunt contorizate per cheie API, nu per adresă IP. Fiecare răspuns de la un endpoint limitat conține X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset (secunde epoch). Depășirea returnează 429 RATE_LIMITED cu un header Retry-After — așteaptă atâtea secunde. Încărcarea bucăților are un buget larg; limitele stricte sunt la deschiderea sesiunilor și pornirea distribuirilor.
| Categorie | Endpointuri | Per cheie | Interval |
|---|---|---|---|
| Pornirea încărcărilor | POST /POST /DELETE / | 60 | 1 minut |
| Încărcarea bucăților | PATCH / | 600 | 1 minut |
| Interogarea progresului | GET /HEAD /GET /GET / | 600 | 1 minut |
| Setările de distribuire ale unei încărcări | POST /PUT / | 300 | 1 minut |
| Pornirea distribuirii | POST / | 30 | 1 minut |
| Încărcări de la URL | POST / | 20 | 10 minute |
| Citirea fișierelor | GET /GET /GET / | 300 | 1 minut |
| Modificarea fișierelor | PATCH /DELETE / | 60 | 1 minut |
| Catalogul public | GET /GET /GET /GET / | 300 | 1 minut |
Acestea sunt valorile implicite. Operatorul le poate modifica, așa că headerele de mai sus sunt întotdeauna sursa de adevăr. Valorile exacte pentru cheile tale și cât ai consumat din fiecare în acest moment se află pe pagina Chei API. Cererile fără cheie sunt contorizate per adresă IP și primesc bugete mai mici pentru pornirea încărcărilor (10 în loc de 60), încărcarea bucăților (300 în loc de 600), interogarea progresului (300 în loc de 600), setările de distribuire ale unei încărcări (60 în loc de 300), pornirea distribuirii (10 în loc de 30), și același buget pentru încărcările de la URL și catalogul public. Citirea fișierelor și modificarea fișierelor necesită întotdeauna o cheie.
Erori
Răspunsurile reușite au forma { "success": true, "data": … }. Erorile folosesc o singură formă, alături de starea HTTP. code este stabil — ramifică logica după el; message este pentru oameni și se poate schimba. details este adăugat când există context suplimentar, retryable indică dacă repetarea aceleiași cereri poate ajuta, iar requestId ne ajută să-ți găsim cererea dacă contactezi asistența.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Cod | HTTP | Reîncerci? | Semnificație |
|---|---|---|---|
NO_TOKEN | 401 | Nu | Nu a fost trimisă nicio cheie API |
INVALID_API_KEY | 401 | Nu | Cheia este greșită sau revocată |
INSUFFICIENT_SCOPE | 403 | Nu | Cheii îi lipsește permisiunea necesară pentru acest endpoint |
API_KEY_NOT_ALLOWED | 403 | Nu | Acest endpoint nu poate fi folosit cu o cheie API |
EMAIL_NOT_VERIFIED | 403 | Nu | Verifică mai întâi e-mailul contului; sesiunile deschise continuă să funcționeze |
SESSION_REVOKED | 401 | Nu | Sesiunea de autentificare a fost încheiată (resetarea sau schimbarea parolei, deconectare); autentifică-te din nou |
ACCOUNT_INACTIVE | 403 | Nu | Contul este suspendat sau programat pentru ștergere |
ACCOUNT_DISABLED | 401 / 409 | Nu | Contul a fost suspendat: 401 la verificarea cheii, 409 dacă s-a schimbat în timp ce cererea rula |
ACCOUNT_PENDING_DELETION | 409 | Nu | Contul a fost programat pentru ștergere în timp ce cererea rula; nu se pornește nimic nou |
VALIDATION_ERROR | 400 | Nu | Corpul sau un parametru este invalid; vezi details |
FILE_REJECTED | 400 | Nu | Tipul sau mărimea fișierului nu sunt permise; details.reason spune care |
TOO_MANY_MIRRORS | 400 | Nu | Mai multe hosturi decât poate avea un fișier |
NO_CONNECTED_PROVIDERS | 400 | Nu | Fiecare host selectat necesită propriul tău cont și niciunul nu este conectat |
PROVIDER_REJECTS_FILE | 400 | Nu | Niciun host selectat nu acceptă acest tip sau această mărime de fișier |
NO_AVAILABLE_PROVIDERS | 400 | Nu | Niciunul dintre hosturile selectate nu acceptă încărcări acum; alege altele sau încearcă mai târziu. `details.waiting` listează hosturile doar puse pe pauză (de exemplu o limită zilnică, ridicată în 24 de ore): pentru ele o încercare ulterioară funcționează chiar dacă `retryable` este false |
NO_VALID_PROVIDERS | 400 | Nu | Nicio valoare din providerSlugs nu corespunde unui host activ; vezi GET /api/v1/providers |
INVALID_JOB_STATE | 400 | Nu | Jobul nu poate fi pornit în starea lui actuală |
JOB_NOT_READY | 400 | Nu | Fișierul nu are încă un job de distribuire |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | Nu | Fișierul nu încape în 10 000 de bucăți de mărimea stabilită pentru sesiune; details.limitBytes |
MISSING_OFFSET | 400 | Nu | O bucată a fost trimisă fără un header numeric upload-offset |
RAW_BODY_REQUIRED | 400 | Nu | Corpul unei bucăți trebuie să fie format din octeți bruți, cu content-type application/offset+octet-stream |
TOO_MANY_URLS | 400 | Nu | Mai multe URL-uri într-o cerere remote-uploads decât este permis |
FILE_NOT_FOUND | 404 | Nu | Acest fișier nu există în contul tău (sau a fost șters) |
JOB_NOT_FOUND | 404 | Nu | Acest job de distribuire nu există în contul tău |
SESSION_NOT_FOUND | 404 | Nu | Această sesiune de încărcare nu există în contul tău |
SHARE_NOT_FOUND | 404 | Nu | Fișierul nu are încă o pagină de partajare |
QUOTA_EXCEEDED | 409 | Nu | O limită zilnică sau de încărcări simultane; details.retryAt spune când se eliberează |
CHUNK_OFFSET_CONFLICT | 409 | Nu | upload-offset nu corespunde octeților primiți; reia de la HEAD |
CHUNK_TOO_SMALL | 409 | Nu | O bucată, alta decât ultima, are sub 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | Nu | Mai mult de 10 000 de bucăți; trimite bucăți mai mari |
CHUNK_MISALIGNED | 409 | Nu | Bucata nu este o felie întreagă de chunkSize care începe la un multiplu de chunkSize: obligatoriu pentru o bucată trimisă înainte și, dacă prima bucată a fost o felie întreagă de chunkSize, pentru fiecare bucată ulterioară (în ordine sau înainte); sau o bucată a fost trimisă înainte într-o sesiune care acceptă bucăți doar în ordine |
CHUNK_OUT_OF_WINDOW | 409 | Nu | O bucată începe la mai mult de maxChunksAhead bucăți după uploadedBytes, sau după acesta înainte ca prima bucată să fi fost acceptată; trimite-o din nou după cele anterioare |
CHUNK_EXCEEDS_DECLARED_SIZE | 409 | Nu | Bucata depășește mărimea fișierului declarată la crearea sesiunii |
CHUNK_EMPTY | 409 | Nu | Bucata nu conține octeți |
CHUNK_NOT_RECEIVABLE | 409 | Nu | Sesiunea nu mai acceptă date (a fost finalizată, anulată sau a expirat); deschide una nouă |
SESSION_EXPIRED | 409 | Nu | Sesiunea de încărcare a expirat; deschide una nouă |
SESSION_NOT_RECEIVABLE | 409 | Nu | Sesiunea a fost anulată sau a expirat și nu mai acceptă modificări |
SESSION_COMPLETED | 409 | Nu | Încărcarea s-a terminat deja; șterge în schimb fișierul |
UPLOAD_INCOMPLETE | 409 | Nu | Nu au sosit toți octeții; trimite mai întâi bucățile rămase (details conține numărătorile) |
IDEMPOTENCY_KEY_CONFLICT | 409 | Nu | Acest idempotencyKey este deja folosit de o altă încărcare; folosește o cheie unică pentru fiecare încărcare |
SOURCE_GONE | 409 | Nu | Copia noastră a fișierului a fost deja ștearsă, așa că nu mai poate fi trimisă pe hosturile pe care nu a fost încercată; încarcă-l din nou pentru acestea. Copia noastră este ștearsă imediat ce un job de distribuire se termină (finalizat, finalizat parțial sau eșuat), iar o încărcare a cărei distribuire nu este pornită niciodată este ștearsă la 30 de minute după ce se termină (până la 72 de ore când planul ei de distribuire încă așteaptă hosturile; cu excepția încărcărilor de la URL). Un nou apel mirror-tasks/start pentru un job terminat, doar cu hosturi deja încercate, aplică doar setările de partajare (alreadyStarted: true) |
JOB_NOT_DISTRIBUTABLE | 409 | Nu | Jobul a eșuat, a fost anulat sau se află într-o stare care nu mai permite distribuirea |
SHARE_TAKEN_DOWN | 409 | Nu | Pagina de partajare a fișierului a fost eliminată, așa că nu mai poate fi trimis pe alte hosturi |
FINALIZING | 409 | Da | O altă cerere asamblează fișierul; întreabă din nou peste câteva secunde |
CONFLICT | 409 | Da | Coliziune cu o altă modificare în curs; reîncearcă aceeași cerere |
TEMPORARILY_UNAVAILABLE | 503 | Da, după Retry-After | Serverul este ocupat acum; reîncearcă după intervalul Retry-After. details.reason "staging_full": spațiul de stocare temporar este plin, nu a fost acceptată nicio încărcare nouă (Retry-After aproximativ 10 minute); încărcările deja în curs continuă să funcționeze |
PAYLOAD_TOO_LARGE | 413 | Nu | Corpul cererii (sau o bucată) este mai mare decât acceptă serverul |
REMOTE_TOO_LARGE | per URL | Nu | Într-un rezultat remote-uploads: fișierul depășește limita pentru încărcarea de la URL |
RATE_LIMITED | 429 | Da, după Retry-After | Prea multe cereri pentru această categorie |
INTERNAL_ERROR | 500 | Da | Eroare de server; detaliile sunt înregistrate, nu sunt returnate niciodată |
MAINTENANCE | 503 | Da, după Retry-After | Încărcările noi sunt suspendate deocamdată; citirile continuă să funcționeze |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Da, după Retry-After | Contorul nostru de încărcări nu a putut fi citit; nu a fost deschisă nicio sesiune |
SHUTTING_DOWN | 503 | Da, după Retry-After | Serverul repornește (Retry-After 5 secunde); așteaptă și trimite din nou aceeași cerere — nu a fost procesat nimic |
De ce a fost omis un host
Acestea nu sunt erori: apar în skipped[].reason al unui start reușit (și al distribution din răspunsul care completează fișierul). Celelalte hosturi primesc în continuare fișierul. Apelul eșuează doar când niciun host selectat nu îl poate prelua: PROVIDER_REJECTS_FILE (niciunul nu acceptă acest fișier), NO_CONNECTED_PROVIDERS (toate necesită propriul tău cont), NO_AVAILABLE_PROVIDERS (niciunul nu acceptă încărcări în acest moment) sau NO_VALID_PROVIDERS (niciun slug nu corespunde unui host activ).
| Motiv | Semnificație |
|---|---|
UNKNOWN_PROVIDER | Nu există niciun host cu acest slug — verifică ortografia în GET /api/v1/providers |
PROVIDER_DISABLED | Hostul este oprit sau în mentenanță în acest moment |
ACCOUNT_REQUIRED | Hostul acceptă încărcări doar în propriul tău cont — conectează-l pe pagina Conexiuni |
GUEST_UPLOAD_OFF | Hostul nu acceptă încărcări acum și nu poate fi conectat la un cont |
DAILY_LIMIT_REACHED | Limita zilnică a hostului pentru încărcări fără cont este consumată deocamdată (până la 24 h) — conectează-ți propriul cont ca să poți încărca oricum |
FILE_TOO_LARGE | Fișierul depășește limita de mărime a acestui host |
MIME_NOT_ALLOWED | Hostul nu acceptă acest tip de fișier |
ALREADY_ATTEMPTED | Acest host a fost deja încercat pentru acest fișier, așa că nu i se mai trimite din nou |
Referința API listează codurile pe care le poate returna fiecare endpoint.