Vai al contenuto

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_…
  1. 1Apri una sessione

    POST /api/v1/upload-sessions

    filename + sizeBytes; ricevi sessionId e chunkSize

  2. 2Invia i blocchi

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

    byte grezzi in ordine; la risposta che completa il file contiene fileId

  3. 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).

PermessoConsente
upload:writeSessioni 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:readElenco dei file, dettagli dei file, stato dei mirror e dei processi
file:writeImpostazioni di condivisione di un file
file:deleteEliminazione 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.

MetodoPercorsoPermessoCosa fa
POST/api/v1/upload-sessionsupload:writeApre una sessione di caricamento (facoltativamente con un piano di distribuzione)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeInvia il blocco di byte successivo
HEAD/api/v1/upload-sessions/{id}upload:writeDa dove riprendere: l’header Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readStato della sessione: byte ricevuti, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readI tuoi limiti di caricamento, l’utilizzo e le sessioni non completate
POST/api/v1/upload-sessions/{id}/completeupload:writeCompleta un caricamento la cui risposta finale è andata persa (si può ritentare in sicurezza)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeImpedisce che una distribuzione differita parta da sola
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeSostituisce il piano di distribuzione di un caricamento
DELETE/api/v1/upload-sessions/{id}upload:writeAnnulla un caricamento non completato e libera il suo posto
POST/api/v1/remote-uploadsupload:writeRecupera file da URL http(s) nel tuo account
POST/api/v1/mirror-tasks/startupload:writeInvia un file agli host che scegli
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readStato del processo, ogni host e il link di condivisione (shareTakenDown segnala una pagina rimossa)
GET/api/v1/filesfile:readElenca i tuoi file (paginazione a cursore, ricerca, filtri)
GET/api/v1/files/{id}file:readUn file: dimensione, checksum, processo, impostazioni di condivisione, statistiche
GET/api/v1/files/{id}/mirrorsfile:readTutte le copie di un file: host, link, stato, clic
PATCH/api/v1/files/{id}/sharefile:writePassword di condivisione, scadenza, visibilità
DELETE/api/v1/files/{id}file:deleteElimina un file e (per impostazione predefinita) le sue copie sugli host
GET/api/v1/platformnessuno (pubblico)Limiti attuali: file più grande, host per file, limiti dei caricamenti da URL
GET/api/v1/providersnessuno (pubblico)Il catalogo degli host, con gli slug da inviare in providerSlugs
GET/api/v1/providers/statusnessuno (pubblico)Successo dei caricamenti misurato per host
GET/api/v1/stats/publicnessuno (pubblico)Totali della piattaforma negli ultimi 30 giorni: file, mirror online, tasso di successo

Caricare un file e distribuirlo

  1. Apri una sessione con POST /api/v1/upload-sessions. filename e sizeBytes (la lunghezza esatta in byte) sono obbligatori; mimeType e un idempotencyKey UUID sono facoltativi: ripetendo una richiesta con la stessa chiave si ottiene la sessione esistente invece di aprirne una seconda. La risposta contiene data.sessionId (non id) e data.chunkSize.
  2. Invia i byte con PATCH /api/v1/upload-sessions/{id}/chunks: byte grezzi, content type application/offset+octet-stream e la posizione iniziale del blocco nell’header upload-offset. I blocchi vanno inviati in ordine, oppure fino a maxChunksAhead blocchi in anticipo; inviando in ordine, usa data.uploadedBytes di ogni risposta come offset successivo. Invia blocchi di chunkSize byte; 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 contiene data.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 di data.maxChunksAhead (4 se il primo blocco era una porzione intera di chunkSize, 0 = solo in ordine). Se il primo blocco era una porzione intera di chunkSize, anche ogni blocco successivo deve esserlo (in ordine o in anticipo): inizia a un multiplo di chunkSize ed è lungo esattamente chunkSize byte (l’ultimo: il resto del file). Un blocco inviato in anticipo rispetto a uploadedBytes deve essere una porzione di questo tipo e iniziare al massimo data.maxChunksAhead blocchi più avanti, altrimenti riceve 409 CHUNK_MISALIGNED o 409 CHUNK_OUT_OF_WINDOW. uploadedBytes conta solo i byte ricevuti senza interruzioni e il blocco che completa il file, qualunque esso sia, riceve la risposta con fileId. Inviare di nuovo un blocco già arrivato è un successo innocuo.
  3. Distribuisci con POST /api/v1/mirror-tasks/start: fileId e providerSlugs sono obbligatori (gli slug provengono da GET /api/v1/providers). Facoltativi: minSuccess (predefinito 1: quanti host devono accettare il file perché il processo non fallisca; è completed solo quando anche tutti gli altri host lo hanno accettato, altrimenti partially_completed. Gli host che rifiutano questo tipo di file non vengono conteggiati), sharePassword, expiresInDays o expiresAt. La risposta contiene uploadJobId, taskCount, shareSlug, alreadyStarted e skipped[]: un host che non può accettare questo file viene saltato, non conteggiato come errore, quindi leggi skipped[] (i motivi sono elencati più sotto). Al momento un file può andare su un massimo di 50 host.
  4. Segui il completamento con GET /api/v1/mirror-tasks/{uploadJobId} ogni pochi secondi finché data.terminal non è true. La risposta elenca ogni host in tasks[] (providerSlug, status, mirrorUrl, errorCode) e il link di condivisione in data.shareUrl. data.shareTakenDown è true quando 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.json

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

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (completa il file) → 200
{
  "success": true,
  "data": {
    "uploadedBytes": 10485760,
    "completed": true,
    "fileId": "…",
    "scan": "skipped",
    "distributable": true,
    "distribution": {
      "started": true,
      "uploadJobId": "…",
      "taskCount": 2,
      "shareSlug": "…",
      "skipped": []
    }
  }
}
POST /mirror-tasks/start → 202
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "taskCount": 2,
    "shareSlug": "…",
    "skipped": [],
    "alreadyStarted": false
  }
}
GET /mirror-tasks/{uploadJobId} → 200
{
  "success": true,
  "data": {
    "uploadJobId": "…",
    "status": "completed",
    "terminal": true,
    "shareSlug": "…",
    "shareUrl": "https://mirroruploadx.com/f/…",
    "shareTakenDown": false,
    "minSuccess": 1,
    "scan": "skipped",
    "tasks": [
      {
        "provider": "Gofile",
        "providerSlug": "gofile",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://gofile.io/d/…",
        "mirrorHidden": false
      },
      {
        "provider": "Pixeldrain",
        "providerSlug": "pixeldrain",
        "status": "succeeded",
        "attempts": 1,
        "errorCode": null,
        "viaOwnAccount": false,
        "errorMessage": null,
        "mirrorUrl": "https://pixeldrain.com/u/…",
        "mirrorHidden": false
      }
    ]
  }
}

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
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.

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"
DELETE /files/{id} → 200
{
  "success": true,
  "data": {
    "stagingDeleted": true,
    "mirrorsQueued": true,
    "mirrorsPurgeDeferred": false,
    "note": "File removed. Copies on providers are being deleted; some may remain on providers that do not support deletion."
  }
}

Webhook

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.

EventoQuando
upload.completedTutti 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_completedAlmeno minSuccess host hanno accettato il file, ma almeno un altro host non è riuscito
upload.failedMeno di minSuccess host hanno accettato il file (minSuccess 0 vale come 1)
upload.quarantinedLa scansione antimalware ha segnalato il file (solo quando la scansione è attiva)
provider.upload_succeededUn host ha accettato il file: inviato una volta per host
provider.upload_failedUn host ha rinunciato al file: inviato una volta per host
webhook.testHai 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.

Corpo
{
  "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);

Limiti 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.

GruppoEndpointPer chiaveIntervallo
Avvio dei caricamentiPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 minuto
Caricamento dei blocchiPATCH /api/v1/upload-sessions/{id}/chunks6001 minuto
Controllo dell’avanzamentoGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 minuto
Impostazioni di distribuzione di un caricamentoPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 minuto
Avvio della distribuzionePOST /api/v1/mirror-tasks/start301 minuto
Caricamenti remoti (URL)POST /api/v1/remote-uploads2010 minuti
Lettura dei fileGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 minuto
Modifica dei filePATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 minuto
Catalogo pubblicoGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 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.

Errore
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CodiceHTTPRitentare?Significato
NO_TOKEN401NoNon è stata inviata alcuna chiave API
INVALID_API_KEY401NoLa chiave è errata o revocata
INSUFFICIENT_SCOPE403NoLa chiave non ha il permesso richiesto da questo endpoint
API_KEY_NOT_ALLOWED403NoQuesto endpoint non può essere usato con una chiave API
EMAIL_NOT_VERIFIED403NoVerifica prima l’email dell’account; le sessioni aperte continuano a funzionare
SESSION_REVOKED401NoLa sessione di accesso è stata chiusa (reimpostazione o modifica della password, uscita); accedi di nuovo
ACCOUNT_INACTIVE403NoL’account è sospeso o in attesa di eliminazione
ACCOUNT_DISABLED401 / 409NoL’account è stato sospeso: 401 al controllo della chiave, 409 se è cambiato durante l’esecuzione della richiesta
ACCOUNT_PENDING_DELETION409NoL’eliminazione dell’account è stata programmata durante l’esecuzione della richiesta; non viene avviato nulla di nuovo
VALIDATION_ERROR400NoIl corpo o un parametro non è valido; vedi details
FILE_REJECTED400NoIl tipo o la dimensione del file non è consentito; details.reason indica quale
TOO_MANY_MIRRORS400NoPiù host di quanti un file ne possa avere
NO_CONNECTED_PROVIDERS400NoTutti gli host selezionati richiedono un tuo account e nessuno è collegato
PROVIDER_REJECTS_FILE400NoNessun host selezionato accetta questo tipo o questa dimensione di file
NO_AVAILABLE_PROVIDERS400NoNessuno 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_PROVIDERS400NoNessun valore di providerSlugs corrisponde a un host attivo; vedi GET /api/v1/providers
INVALID_JOB_STATE400NoIl processo non può essere avviato nel suo stato attuale
JOB_NOT_READY400NoIl file non ha ancora un processo di distribuzione
FILE_TOO_LARGE_FOR_UPLOAD400NoIl file non entra in 10 000 blocchi della dimensione di blocco della sessione; details.limitBytes
MISSING_OFFSET400NoUn blocco è stato inviato senza un header upload-offset numerico
RAW_BODY_REQUIRED400NoIl corpo di un blocco deve essere in byte grezzi con content-type application/offset+octet-stream
TOO_MANY_URLS400NoPiù URL del consentito in una richiesta remote-uploads
FILE_NOT_FOUND404NoNessun file di questo tipo nel tuo account (o è stato eliminato)
JOB_NOT_FOUND404NoNessun processo di distribuzione di questo tipo nel tuo account
SESSION_NOT_FOUND404NoNessuna sessione di caricamento di questo tipo nel tuo account
SHARE_NOT_FOUND404NoIl file non ha ancora una pagina di condivisione
QUOTA_EXCEEDED409NoUn limite di caricamenti giornaliero o simultaneo; details.retryAt indica quando si libera
CHUNK_OFFSET_CONFLICT409Noupload-offset non corrisponde ai byte ricevuti; riprendi da HEAD
CHUNK_TOO_SMALL409NoUn blocco diverso dall’ultimo è inferiore a 5 MiB
CHUNK_TOO_MANY_PARTS409NoPiù di 10 000 blocchi; inviane di più grandi
CHUNK_MISALIGNED409NoIl 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_WINDOW409NoUn 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_SIZE409NoIl blocco supera la dimensione del file dichiarata alla creazione della sessione
CHUNK_EMPTY409NoIl blocco non contiene byte
CHUNK_NOT_RECEIVABLE409NoLa sessione non accetta più dati (è stata completata, annullata o è scaduta); aprine una nuova
SESSION_EXPIRED409NoLa sessione di caricamento è scaduta; aprine una nuova
SESSION_NOT_RECEIVABLE409NoLa sessione è stata annullata o è scaduta e non accetta altre modifiche
SESSION_COMPLETED409NoIl caricamento è già terminato; elimina invece il file
UPLOAD_INCOMPLETE409NoNon tutti i byte sono arrivati; invia prima i blocchi rimanenti (details contiene i conteggi)
IDEMPOTENCY_KEY_CONFLICT409NoQuesto idempotencyKey è già usato da un altro caricamento; usa una chiave univoca per ogni caricamento
SOURCE_GONE409NoLa 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_DISTRIBUTABLE409NoIl processo non è riuscito, è stato annullato o si trova in uno stato che non può più essere distribuito
SHARE_TAKEN_DOWN409NoLa pagina di condivisione del file è stata rimossa, quindi non può essere inviato ad altri host
FINALIZING409SìUn’altra richiesta sta assemblando il file; riprova tra qualche secondo
CONFLICT409SìConflitto con un’altra modifica in corso; ripeti la stessa richiesta
TEMPORARILY_UNAVAILABLE503Sì, dopo Retry-AfterIl 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_LARGE413NoIl corpo della richiesta (o un blocco) è più grande di quanto il server accetti
REMOTE_TOO_LARGEper URLNoIn un risultato di remote-uploads: il file supera il limite dei caricamenti da URL
RATE_LIMITED429Sì, dopo Retry-AfterTroppe richieste per questo gruppo
INTERNAL_ERROR500SìErrore del server; i dettagli vengono registrati, mai restituiti
MAINTENANCE503Sì, dopo Retry-AfterI nuovi caricamenti sono sospesi per ora; le letture continuano a funzionare
UPLOADS_TEMPORARILY_UNAVAILABLE503Sì, dopo Retry-AfterNon è stato possibile leggere il nostro contatore dei caricamenti; nessuna sessione è stata aperta
SHUTTING_DOWN503Sì, dopo Retry-AfterIl 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).

MotivoSignificato
UNKNOWN_PROVIDERNon esiste alcun host con questo slug: controlla l’ortografia con GET /api/v1/providers
PROVIDER_DISABLEDL’host è disattivato o in manutenzione in questo momento
ACCOUNT_REQUIREDL’host accetta caricamenti solo sul tuo account: collegalo nella pagina Collegamenti
GUEST_UPLOAD_OFFL’host non accetta caricamenti al momento e non può essere collegato a un account
DAILY_LIMIT_REACHEDIl 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_LARGEIl file supera il limite di dimensione di questo host
MIME_NOT_ALLOWEDL’host non accetta questo tipo di file
ALREADY_ATTEMPTEDQuesto 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.