Documentazione API
Carica un file una volta, invialo ai file hosting che scegli e ottieni un solo link di condivisione, direttamente dal tuo codice.
Aggiornato il
Un’API REST con versioni: carica un file a blocchi, invialo agli host che scegli e tutte le copie vengono raccolte in un’unica pagina di condivisione con stato live.
- URL di base
- https://api.mirroruploadx.com/api/v1
- Autenticazione
- x-api-key: mux_…
1Apri una sessione
POST /
api/ v1/ upload-sessions filename + sizeBytes; ricevi sessionId e chunkSize
2Invia i blocchi
PATCH /
api/ v1/ upload-sessions/ {id}/ chunks byte grezzi in ordine; la risposta che completa il file contiene fileId
3Distribuisci
POST /
api/ v1/ mirror-tasks/ start fileId + providerSlugs; poi interroga il processo
Crea una chiave nella pagina Chiavi API. La guida completa con il codice è in Caricare e distribuire.
Autenticazione
Crea una chiave nella pagina Chiavi API della tua dashboard. La chiave completa (inizia con mux_) viene mostrata una sola volta, quindi salvala subito. Inviala nell’header x-api-key a ogni richiesta; Authorization: Bearer mux_… è accettato allo stesso modo per i client che supportano solo i bearer token.
Le chiavi hanno permessi limitati: una chiave raggiunge solo gli endpoint coperti dai suoi permessi e una chiamata con il permesso sbagliato restituisce 403 INSUFFICIENT_SCOPE, con il permesso necessario indicato nel messaggio. Impostazioni dell’account, gestione delle chiavi e webhook non sono raggiungibili con una chiave API (API_KEY_NOT_ALLOWED).
| Permesso | Consente |
|---|---|
upload:write | Sessioni di caricamento (creazione, blocchi, completamento, annullamento), la tua quota di caricamento, sospensione o modifica della distribuzione automatica di un caricamento (hold-distribution, distribution-intent), caricamenti da URL remoto, avvio della distribuzione |
file:read | Elenco dei file, dettagli dei file, stato dei mirror e dei processi |
file:write | Impostazioni di condivisione di un file |
file:delete | Eliminazione di un file e dei suoi mirror |
Endpoint
Tutto ciò che una chiave API può raggiungere, più gli endpoint pubblici che non richiedono chiave. Quando la colonna dei permessi ne elenca due, ne basta uno. Gli schemi di richiesta e risposta di ciascuno sono nel riferimento API.
| Metodo | Percorso | Permesso | Cosa fa |
|---|---|---|---|
| POST | / | upload:write | Apre una sessione di caricamento (facoltativamente con un piano di distribuzione) |
| PATCH | / | upload:write | Invia il blocco di byte successivo |
| HEAD | / | upload:write | Da dove riprendere: l’header Upload-Offset |
| GET | / | upload:writefile:read | Stato della sessione: byte ricevuti, fileId, finalizable |
| GET | / | upload:writefile:read | I tuoi limiti di caricamento, l’utilizzo e le sessioni non completate |
| POST | / | upload:write | Completa un caricamento la cui risposta finale è andata persa (si può ritentare in sicurezza) |
| POST | / | upload:write | Impedisce che una distribuzione differita parta da sola |
| PUT | / | upload:write | Sostituisce il piano di distribuzione di un caricamento |
| DELETE | / | upload:write | Annulla un caricamento non completato e libera il suo posto |
| POST | / | upload:write | Recupera file da URL http(s) nel tuo account |
| POST | / | upload:write | Invia un file agli host che scegli |
| GET | / | upload:writefile:read | Stato del processo, ogni host e il link di condivisione (shareTakenDown segnala una pagina rimossa) |
| GET | / | file:read | Elenca i tuoi file (paginazione a cursore, ricerca, filtri) |
| GET | / | file:read | Un file: dimensione, checksum, processo, impostazioni di condivisione, statistiche |
| GET | / | file:read | Tutte le copie di un file: host, link, stato, clic |
| PATCH | / | file:write | Password di condivisione, scadenza, visibilità |
| DELETE | / | file:delete | Elimina un file e (per impostazione predefinita) le sue copie sugli host |
| GET | / | nessuno (pubblico) | Limiti attuali: file più grande, host per file, limiti dei caricamenti da URL |
| GET | / | nessuno (pubblico) | Il catalogo degli host, con gli slug da inviare in providerSlugs |
| GET | / | nessuno (pubblico) | Successo dei caricamenti misurato per host |
| GET | / | nessuno (pubblico) | Totali della piattaforma negli ultimi 30 giorni: file, mirror online, tasso di successo |
Caricare un file e distribuirlo
- Apri una sessione con
POST /api/v1/upload-sessions.filenameesizeBytes(la lunghezza esatta in byte) sono obbligatori;mimeTypee unidempotencyKeyUUID sono facoltativi: ripetendo una richiesta con la stessa chiave si ottiene la sessione esistente invece di aprirne una seconda. La risposta contienedata.sessionId(nonid) edata.chunkSize. - Invia i byte con
PATCH /api/v1/upload-sessions/{id}/chunks: byte grezzi, content typeapplication/offset+octet-streame la posizione iniziale del blocco nell’headerupload-offset. I blocchi vanno inviati in ordine, oppure fino amaxChunksAheadblocchi in anticipo; inviando in ordine, usadata.uploadedBytesdi ogni risposta come offset successivo. Invia blocchi dichunkSizebyte; ogni blocco tranne l’ultimo deve essere di almeno 5 MiB e un caricamento può avere al massimo 10 000 blocchi. La risposta che completa il file contienedata.fileId. Per maggiore velocità puoi tenere in volo 2–3 blocchi dello stesso file. Invia il primo blocco da solo; la sua risposta indica il valore reale didata.maxChunksAhead(4 se il primo blocco era una porzione intera dichunkSize, 0 = solo in ordine). Se il primo blocco era una porzione intera dichunkSize, anche ogni blocco successivo deve esserlo (in ordine o in anticipo): inizia a un multiplo dichunkSizeed è lungo esattamentechunkSizebyte (l’ultimo: il resto del file). Un blocco inviato in anticipo rispetto auploadedBytesdeve essere una porzione di questo tipo e iniziare al massimodata.maxChunksAheadblocchi più avanti, altrimenti riceve409 CHUNK_MISALIGNEDo409 CHUNK_OUT_OF_WINDOW.uploadedBytesconta solo i byte ricevuti senza interruzioni e il blocco che completa il file, qualunque esso sia, riceve la risposta confileId. Inviare di nuovo un blocco già arrivato è un successo innocuo. - Distribuisci con
POST /api/v1/mirror-tasks/start:fileIdeproviderSlugssono obbligatori (gli slug provengono daGET /api/v1/providers). Facoltativi:minSuccess(predefinito 1: quanti host devono accettare il file perché il processo non fallisca; ècompletedsolo quando anche tutti gli altri host lo hanno accettato, altrimentipartially_completed. Gli host che rifiutano questo tipo di file non vengono conteggiati),sharePassword,expiresInDaysoexpiresAt. La risposta contieneuploadJobId,taskCount,shareSlug,alreadyStartedeskipped[]: un host che non può accettare questo file viene saltato, non conteggiato come errore, quindi leggiskipped[](i motivi sono elencati più sotto). Al momento un file può andare su un massimo di 50 host. - Segui il completamento con
GET /api/v1/mirror-tasks/{uploadJobId}ogni pochi secondi finchédata.terminalnon ètrue. La risposta elenca ogni host intasks[](providerSlug,status,mirrorUrl,errorCode) e il link di condivisione indata.shareUrl.data.shareTakenDownètruequando quella pagina di condivisione è stata rimossa e non si apre più.
Il file più grande accettato al momento è di 5,00 GB.
bash, richiede 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";
}Esempi di risposta
L’apertura di una sessione risponde 201. Ogni blocco tranne l’ultimo risponde { uploadedBytes, completed: false, expiresAt }; l’ultimo contiene il file. distribution è presente solo se hai passato un piano all’apertura della sessione (vedi sotto).
{
"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 primo start riuscito risponde 202; chiamarlo di nuovo per un processo già in corso risponde 200 con alreadyStarted: true. Quando il link di un host è mantenuto privato per policy, mirrorUrl è null e mirrorHidden è true: la pagina di condivisione lo elenca comunque.
Evitare la seconda chiamata
Passa distribution all’apertura della sessione e il server avvia la distribuzione appena il file è completo. Controlla data.distribution nella risposta che completa il file: started: true significa che il processo è in coda (uploadJobId, shareSlug). Con started: false e deferred: true non è ancora stato messo in coda nulla, volutamente: vedi sotto. Con started: false e senza deferred, il caricamento è comunque riuscito ma la distribuzione non è potuta partire (error spiega perché): chiama POST /api/v1/mirror-tasks/start con il fileId. Un error insieme a deferred: true indica un errore temporaneo (per esempio, tutti gli host sono occupati o in manutenzione): non chiamare start e non caricare di nuovo il file; il server ritenterà da solo l’avvio della distribuzione a partire da autoStartAt (fino a 5 tentativi). Chiama hold-distribution per fermarlo.
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": "…" } }Aggiungi deferred: true a distribution per un periodo di tolleranza: la risposta finale è { started: false, deferred: true, autoStartAt } e il server avvia da solo la distribuzione a autoStartAt (circa 2 minuti dopo), a meno che tu non chiami prima start. Per fermare l’avvio automatico, chiama POST /api/v1/upload-sessions/{id}/hold-distribution (senza corpo; autoStartAt diventa null e la avvii tu). Per cambiare invece il piano, chiama PUT /api/v1/upload-sessions/{id}/distribution-intent con gli stessi campi di distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): sostituisce il piano e rimuove un’eventuale sospensione e, una volta terminato il caricamento, l’avvio automatico viene spostato ad almeno 2 minuti dopo la chiamata. Se la distribuzione è già partita, entrambe rispondono 200 e distribution-intent indica alreadyStarted: true.
Avvia entro 30 minuti. Quando un caricamento termina e non viene avviata alcuna distribuzione, la nostra copia del file viene rimossa dopo 30 minuti (con un piano di distribuzione ancora in attesa che gli host tornino disponibili, dopo al massimo 72 ore; i caricamenti da URL remoto non sono interessati). Dopodiché start e distribution-intent rispondono 409 SOURCE_GONE e il file deve essere caricato di nuovo.
Se la risposta finale va persa
Chiama GET /api/v1/upload-sessions/{id}: un fileId significa che il file esiste; finalizable: true significa che tutti i byte sono arrivati e POST /api/v1/upload-sessions/{id}/complete lo completa. Questa chiamata si può ritentare in sicurezza e non crea mai un secondo file. Un offset non corrispondente riceve 409 CHUNK_OFFSET_CONFLICT: invia HEAD sulla sessione e riprendi dal suo header Upload-Offset. Chiamare di nuovo start per un processo in corso non è un errore: ricevi 200 con alreadyStarted: true.
Caricare da un URL
POST /api/v1/remote-uploads accetta { "urls": [...] } e recupera ogni file per te (permesso upload:write). Vengono recuperati solo link http e https, gli indirizzi di reti private vengono rifiutati e viene seguito solo un numero limitato di reindirizzamenti. Una richiesta contiene al massimo 10 URL (restituito da GET /api/v1/platform); suddividi gli elenchi più lunghi.
Il limite di dimensione per file dipende dall’origine. Quando l’origine indica la dimensione del file, ogni file può arrivare a 5,00 GB (limits.remoteUploadPassthroughMaxBytes); quando non la indica, fino a 100,0 MB (limits.remoteUploadMaxBytes). Il nome del file proviene dall’header Content-Disposition dell’origine, se lo invia; un nome senza estensione ne riceve una in base al tipo del file.
La richiesta resta in attesa mentre i file vengono scaricati. Se la connessione cade prima, il file arriva comunque nel tuo account: trovalo con GET /api/v1/files. Ogni fileId viene poi distribuito con POST /api/v1/mirror-tasks/start, come sopra.
Quando lo spazio temporaneo è pieno, l’intera richiesta riceve 503 TEMPORARILY_UNAVAILABLE con details.reason: "staging_full" e un header Retry-After. Se solo un URL non ci sta, la sua voce in results[] ha ok: false e lo stesso codice; un risultato per singolo URL non ha header, quindi l’attesa in secondi si trova in 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.Gestire i file
I tuoi file restano nel tuo account dopo il caricamento. Elencali con GET /api/v1/files (limit fino a 100; passa il nextCursor della risposta come cursor per la pagina successiva, q cerca per nome). GET /api/v1/files/{id} restituisce un file con il suo processo, le impostazioni di condivisione e le statistiche delle visite; GET /api/v1/files/{id}/mirrors elenca tutte le copie con link, stato e clic.
PATCH /api/v1/files/{id}/share (permesso file:write) modifica la pagina di condivisione: password (4–128 caratteri, null la rimuove; non viene mai restituita, solo passwordProtected), expiresAt (data ISO, null per nessuna scadenza), visibility e hideDownloadCount. Invia solo i campi che vuoi modificare. DELETE /api/v1/files/{id} (permesso file:delete) rimuove il file e mette in coda l’eliminazione delle sue copie sugli host; aggiungi ?keepMirrors=true per conservarle. Alcuni host non supportano l’eliminazione, quindi una copia potrebbe restare lì.
bash, richiede jq; imposta 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; imposta 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+, modulo ES; imposta 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; imposta 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
Aggiungi un endpoint nella pagina Webhook. L’URL deve usare https://; il suo segreto di firma (whsec_…) viene mostrato una sola volta, alla creazione. Un endpoint senza eventi selezionati li riceve tutti.
| Evento | Quando |
|---|---|
upload.completed | Tutti gli host hanno accettato il file, e almeno minSuccess lo hanno fatto: gli host che hanno rifiutato questo file (rejected) o sono stati annullati non vengono conteggiati |
upload.partially_completed | Almeno minSuccess host hanno accettato il file, ma almeno un altro host non è riuscito |
upload.failed | Meno di minSuccess host hanno accettato il file (minSuccess 0 vale come 1) |
upload.quarantined | La scansione antimalware ha segnalato il file (solo quando la scansione è attiva) |
provider.upload_succeeded | Un host ha accettato il file: inviato una volta per host |
provider.upload_failed | Un host ha rinunciato al file: inviato una volta per host |
webhook.test | Hai premuto Test nella pagina Webhook |
Ogni consegna è un POST con un corpo JSON e gli header X-MUX-Event e X-MUX-Signature. Qualsiasi risposta 2xx entro 10 secondi vale come consegnata; i reindirizzamenti non vengono seguiti. Una consegna non riuscita (errore di rete, timeout, 408, 425, 429 o 5xx) viene ritentata dopo 1, 5 e 30 minuti con lo stesso corpo; gli altri 4xx e i reindirizzamenti no. Ogni tentativo include X-MUX-Delivery-Attempt (1–4) e una nuova firma, quindi deduplica in base al corpo. L’ordine di consegna non è garantito (un evento ritentato può arrivare dopo uno più recente); confronta data e createdAt prima di agire. Usa GET /api/v1/mirror-tasks/{uploadJobId} per recuperare lo stato. Dopo 15 consegne consecutive con l’ultimo tentativo fallito, o un’ora di errori senza un solo successo, l’endpoint viene sospeso; riattivandolo il conteggio si azzera. Una consegna webhook.test (il pulsante Test) viene inviata una sola volta, con X-MUX-Delivery-Attempt: 1, e non viene mai ritentata.
{
"event": "provider.upload_succeeded",
"createdAt": "2026-09-25T12:00:00.000Z",
"data": {
"uploadJobId": "…",
"fileId": "…",
"provider": "gofile",
"providerName": "Gofile",
"status": "succeeded",
"mirrorUrl": "https://…"
}
}Gli eventi upload.* contengono uploadJobId, fileId e status; provider.upload_failed contiene errorCode invece di mirrorUrl.
Verificare la firma
L’header ha la forma t=1727265600,v1=5f2b…: t è il momento della firma in secondi Unix, v1 è l’HMAC-SHA256 esadecimale di <t>.<raw body> con il segreto del tuo endpoint come chiave. Calcola l’hash dei byte grezzi esattamente come ricevuti, confronta in tempo costante e rifiuta i timestamp più vecchi di 5 minuti.
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+ puro
<?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 deliveredLimiti di frequenza
I limiti sono conteggiati per chiave API, non per indirizzo IP. Ogni risposta su un endpoint limitato contiene X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi epoch). Se superi il limite ricevi 429 RATE_LIMITED con un header Retry-After: attendi quel numero di secondi. I caricamenti dei blocchi hanno un margine ampio; i limiti stretti riguardano l’apertura delle sessioni e l’avvio delle distribuzioni.
| Gruppo | Endpoint | Per chiave | Intervallo |
|---|---|---|---|
| Avvio dei caricamenti | POST /POST /DELETE / | 60 | 1 minuto |
| Caricamento dei blocchi | PATCH / | 600 | 1 minuto |
| Controllo dell’avanzamento | GET /HEAD /GET /GET / | 600 | 1 minuto |
| Impostazioni di distribuzione di un caricamento | POST /PUT / | 300 | 1 minuto |
| Avvio della distribuzione | POST / | 30 | 1 minuto |
| Caricamenti remoti (URL) | POST / | 20 | 10 minuti |
| Lettura dei file | GET /GET /GET / | 300 | 1 minuto |
| Modifica dei file | PATCH /DELETE / | 60 | 1 minuto |
| Catalogo pubblico | GET /GET /GET /GET / | 300 | 1 minuto |
Questi sono i valori predefiniti. Il gestore può modificarli, quindi fanno sempre fede gli header indicati sopra. I valori esatti per le tue chiavi, e quanto ne hai usato finora, sono nella pagina Chiavi API. Le richieste senza chiave vengono conteggiate per indirizzo IP e hanno margini più ridotti per avvio dei caricamenti (10 invece di 60), caricamento dei blocchi (300 invece di 600), controllo dell’avanzamento (300 invece di 600), impostazioni di distribuzione di un caricamento (60 invece di 300), avvio della distribuzione (10 invece di 30) e lo stesso margine per caricamenti remoti (URL) e catalogo pubblico. Lettura dei file e modifica dei file richiedono sempre una chiave.
Errori
Le risposte riuscite hanno la forma { "success": true, "data": … }. Gli errori usano un’unica forma, accanto allo stato HTTP. code è stabile: basa la logica su di esso; message è pensato per le persone e può cambiare. details viene aggiunto quando c’è più contesto, retryable indica se ripetere la stessa richiesta può essere utile e requestId ci aiuta a trovare la tua richiesta se contatti l’assistenza.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Codice | HTTP | Ritentare? | Significato |
|---|---|---|---|
NO_TOKEN | 401 | No | Non è stata inviata alcuna chiave API |
INVALID_API_KEY | 401 | No | La chiave è errata o revocata |
INSUFFICIENT_SCOPE | 403 | No | La chiave non ha il permesso richiesto da questo endpoint |
API_KEY_NOT_ALLOWED | 403 | No | Questo endpoint non può essere usato con una chiave API |
EMAIL_NOT_VERIFIED | 403 | No | Verifica prima l’email dell’account; le sessioni aperte continuano a funzionare |
SESSION_REVOKED | 401 | No | La sessione di accesso è stata chiusa (reimpostazione o modifica della password, uscita); accedi di nuovo |
ACCOUNT_INACTIVE | 403 | No | L’account è sospeso o in attesa di eliminazione |
ACCOUNT_DISABLED | 401 / 409 | No | L’account è stato sospeso: 401 al controllo della chiave, 409 se è cambiato durante l’esecuzione della richiesta |
ACCOUNT_PENDING_DELETION | 409 | No | L’eliminazione dell’account è stata programmata durante l’esecuzione della richiesta; non viene avviato nulla di nuovo |
VALIDATION_ERROR | 400 | No | Il corpo o un parametro non è valido; vedi details |
FILE_REJECTED | 400 | No | Il tipo o la dimensione del file non è consentito; details.reason indica quale |
TOO_MANY_MIRRORS | 400 | No | Più host di quanti un file ne possa avere |
NO_CONNECTED_PROVIDERS | 400 | No | Tutti gli host selezionati richiedono un tuo account e nessuno è collegato |
PROVIDER_REJECTS_FILE | 400 | No | Nessun host selezionato accetta questo tipo o questa dimensione di file |
NO_AVAILABLE_PROVIDERS | 400 | No | Nessuno degli host selezionati accetta caricamenti al momento; scegline altri o riprova più tardi. `details.waiting` elenca gli host solo in pausa (per esempio un limite giornaliero, rimosso entro 24 ore): per questi riprovare più tardi funziona anche se `retryable` è false |
NO_VALID_PROVIDERS | 400 | No | Nessun valore di providerSlugs corrisponde a un host attivo; vedi GET /api/v1/providers |
INVALID_JOB_STATE | 400 | No | Il processo non può essere avviato nel suo stato attuale |
JOB_NOT_READY | 400 | No | Il file non ha ancora un processo di distribuzione |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | No | Il file non entra in 10 000 blocchi della dimensione di blocco della sessione; details.limitBytes |
MISSING_OFFSET | 400 | No | Un blocco è stato inviato senza un header upload-offset numerico |
RAW_BODY_REQUIRED | 400 | No | Il corpo di un blocco deve essere in byte grezzi con content-type application/offset+octet-stream |
TOO_MANY_URLS | 400 | No | Più URL del consentito in una richiesta remote-uploads |
FILE_NOT_FOUND | 404 | No | Nessun file di questo tipo nel tuo account (o è stato eliminato) |
JOB_NOT_FOUND | 404 | No | Nessun processo di distribuzione di questo tipo nel tuo account |
SESSION_NOT_FOUND | 404 | No | Nessuna sessione di caricamento di questo tipo nel tuo account |
SHARE_NOT_FOUND | 404 | No | Il file non ha ancora una pagina di condivisione |
QUOTA_EXCEEDED | 409 | No | Un limite di caricamenti giornaliero o simultaneo; details.retryAt indica quando si libera |
CHUNK_OFFSET_CONFLICT | 409 | No | upload-offset non corrisponde ai byte ricevuti; riprendi da HEAD |
CHUNK_TOO_SMALL | 409 | No | Un blocco diverso dall’ultimo è inferiore a 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | No | Più di 10 000 blocchi; inviane di più grandi |
CHUNK_MISALIGNED | 409 | No | Il blocco non è una porzione intera di chunkSize che inizia a un multiplo di chunkSize: è obbligatorio per un blocco inviato in anticipo e, se il primo blocco era una porzione intera di chunkSize, anche per ogni blocco successivo (in ordine o in anticipo); oppure un blocco è stato inviato in anticipo in una sessione che accetta blocchi solo in ordine |
CHUNK_OUT_OF_WINDOW | 409 | No | Un blocco inizia più di maxChunksAhead blocchi oltre uploadedBytes, o comunque oltre prima che il primo blocco sia stato accettato; inviarlo di nuovo dopo quelli precedenti |
CHUNK_EXCEEDS_DECLARED_SIZE | 409 | No | Il blocco supera la dimensione del file dichiarata alla creazione della sessione |
CHUNK_EMPTY | 409 | No | Il blocco non contiene byte |
CHUNK_NOT_RECEIVABLE | 409 | No | La sessione non accetta più dati (è stata completata, annullata o è scaduta); aprine una nuova |
SESSION_EXPIRED | 409 | No | La sessione di caricamento è scaduta; aprine una nuova |
SESSION_NOT_RECEIVABLE | 409 | No | La sessione è stata annullata o è scaduta e non accetta altre modifiche |
SESSION_COMPLETED | 409 | No | Il caricamento è già terminato; elimina invece il file |
UPLOAD_INCOMPLETE | 409 | No | Non tutti i byte sono arrivati; invia prima i blocchi rimanenti (details contiene i conteggi) |
IDEMPOTENCY_KEY_CONFLICT | 409 | No | Questo idempotencyKey è già usato da un altro caricamento; usa una chiave univoca per ogni caricamento |
SOURCE_GONE | 409 | No | La nostra copia del file è già stata rimossa, quindi non può essere inviata agli host su cui non è ancora stata tentata; caricala di nuovo per quegli host. La nostra copia viene rimossa non appena un processo di distribuzione termina (completato, parzialmente completato o non riuscito) e un caricamento la cui distribuzione non viene mai avviata viene rimosso 30 minuti dopo il suo termine (fino a 72 ore quando il suo piano di distribuzione è ancora in attesa degli host; esclusi i caricamenti da URL remoto). Chiamare di nuovo mirror-tasks/start per un processo terminato con i soli host già tentati applica solo le impostazioni di condivisione (alreadyStarted: true) |
JOB_NOT_DISTRIBUTABLE | 409 | No | Il processo non è riuscito, è stato annullato o si trova in uno stato che non può più essere distribuito |
SHARE_TAKEN_DOWN | 409 | No | La pagina di condivisione del file è stata rimossa, quindi non può essere inviato ad altri host |
FINALIZING | 409 | Sì | Un’altra richiesta sta assemblando il file; riprova tra qualche secondo |
CONFLICT | 409 | Sì | Conflitto con un’altra modifica in corso; ripeti la stessa richiesta |
TEMPORARILY_UNAVAILABLE | 503 | Sì, dopo Retry-After | Il server è occupato in questo momento; riprova dopo l’attesa indicata da Retry-After. details.reason "staging_full": lo spazio temporaneo è pieno e non è stato accettato alcun nuovo caricamento (Retry-After circa 10 minuti); i caricamenti già in corso continuano a funzionare |
PAYLOAD_TOO_LARGE | 413 | No | Il corpo della richiesta (o un blocco) è più grande di quanto il server accetti |
REMOTE_TOO_LARGE | per URL | No | In un risultato di remote-uploads: il file supera il limite dei caricamenti da URL |
RATE_LIMITED | 429 | Sì, dopo Retry-After | Troppe richieste per questo gruppo |
INTERNAL_ERROR | 500 | Sì | Errore del server; i dettagli vengono registrati, mai restituiti |
MAINTENANCE | 503 | Sì, dopo Retry-After | I nuovi caricamenti sono sospesi per ora; le letture continuano a funzionare |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Sì, dopo Retry-After | Non è stato possibile leggere il nostro contatore dei caricamenti; nessuna sessione è stata aperta |
SHUTTING_DOWN | 503 | Sì, dopo Retry-After | Il server si sta riavviando (Retry-After 5 secondi); attendi e invia di nuovo la stessa richiesta: non è stato elaborato nulla |
Perché un host è stato saltato
Questi non sono errori: arrivano in skipped[].reason di uno start riuscito (e di distribution nella risposta che completa il file). Gli altri host ricevono comunque il file. La chiamata fallisce solo quando nessun host selezionato può accettarlo: PROVIDER_REJECTS_FILE (nessuno accetta questo file), NO_CONNECTED_PROVIDERS (tutti richiedono un tuo account), NO_AVAILABLE_PROVIDERS (nessuno accetta caricamenti al momento) o NO_VALID_PROVIDERS (nessuno slug corrisponde a un host attivo).
| Motivo | Significato |
|---|---|
UNKNOWN_PROVIDER | Non esiste alcun host con questo slug: controlla l’ortografia con GET /api/v1/providers |
PROVIDER_DISABLED | L’host è disattivato o in manutenzione in questo momento |
ACCOUNT_REQUIRED | L’host accetta caricamenti solo sul tuo account: collegalo nella pagina Collegamenti |
GUEST_UPLOAD_OFF | L’host non accetta caricamenti al momento e non può essere collegato a un account |
DAILY_LIMIT_REACHED | Il limite giornaliero dell’host per i caricamenti senza account è esaurito per ora (fino a 24 h): collega il tuo account per caricare comunque |
FILE_TOO_LARGE | Il file supera il limite di dimensione di questo host |
MIME_NOT_ALLOWED | L’host non accetta questo tipo di file |
ALREADY_ATTEMPTED | Questo host è già stato tentato per questo file, quindi non vi viene inviato di nuovo |
Il riferimento API elenca i codici che ogni endpoint può restituire.