Zum Inhalt springen

API-Dokumentation

Laden Sie eine Datei einmal hoch, senden Sie sie an die Filehoster Ihrer Wahl und erhalten Sie einen Freigabelink zurück – aus Ihrem eigenen Code.

Aktualisiert

Eine versionierte REST-API: Laden Sie eine Datei in Teilen hoch, senden Sie sie an die Hoster Ihrer Wahl, und alle Kopien werden auf einer Freigabeseite mit Live-Status gesammelt.

Basis-URL
https://api.mirroruploadx.com/api/v1
Authentifizierung
x-api-key: mux_…
  1. 1Sitzung öffnen

    POST /api/v1/upload-sessions

    filename + sizeBytes; sessionId und chunkSize erhalten

  2. 2Teile senden

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

    Rohbytes der Reihe nach; die Antwort, die die Datei vervollständigt, enthält fileId

  3. 3Verteilen

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; dann den Auftrag abfragen

Erstellen Sie einen Schlüssel auf der Seite API-Schlüssel. Eine vollständige Anleitung mit Code finden Sie unter Hochladen und verteilen.

Authentifizierung

Erstellen Sie einen Schlüssel auf der Seite API-Schlüssel in Ihrem Dashboard. Der vollständige Schlüssel (er beginnt mit mux_) wird nur einmal angezeigt – speichern Sie ihn also sofort. Senden Sie ihn bei jeder Anfrage im Header x-api-key; Authorization: Bearer mux_… wird für Clients, die nur Bearer-Tokens beherrschen, ebenso akzeptiert.

Schlüssel haben Berechtigungen (Scopes): Ein Schlüssel erreicht nur die Endpunkte, die seine Scopes abdecken, und ein Aufruf mit falschem Scope liefert 403 INSUFFICIENT_SCOPE mit dem benötigten Scope in der Meldung. Kontoeinstellungen, Schlüsselverwaltung und Webhooks sind mit einem API-Schlüssel überhaupt nicht erreichbar (API_KEY_NOT_ALLOWED).

ScopeErreicht
upload:writeUpload-Sitzungen (erstellen, Teile, abschließen, abbrechen), Ihr Upload-Kontingent, Anhalten oder Ändern der automatischen Verteilung eines Uploads (hold-distribution, distribution-intent), Uploads per URL, Starten der Verteilung
file:readDateien auflisten, Dateidetails, Mirror- und Auftragsstatus
file:writeFreigabeeinstellungen einer Datei
file:deleteLöschen einer Datei und ihrer Mirrors

Endpunkte

Alles, was ein API-Schlüssel erreichen kann, sowie die öffentlichen Endpunkte, die keinen Schlüssel benötigen. Stehen in der Scope-Spalte zwei Scopes, genügt einer davon. Anfrage- und Antwortschemata zu jedem Endpunkt finden Sie in der API-Referenz.

MethodePfadScopeFunktion
POST/api/v1/upload-sessionsupload:writeUpload-Sitzung öffnen (optional mit Verteilungsplan)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeNächsten Teil der Bytes senden
HEAD/api/v1/upload-sessions/{id}upload:writeWo fortgesetzt wird: der Header Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readSitzungsstatus: empfangene Bytes, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readIhre Upload-Limits, Nutzung und unfertigen Sitzungen
POST/api/v1/upload-sessions/{id}/completeupload:writeUpload abschließen, dessen letzte Antwort verloren ging (sicher wiederholbar)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeVerhindern, dass eine aufgeschobene Verteilung von selbst startet
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeVerteilungsplan eines Uploads ersetzen
DELETE/api/v1/upload-sessions/{id}upload:writeUnfertigen Upload abbrechen und seinen Platz freigeben
POST/api/v1/remote-uploadsupload:writeDateien von http(s)-URLs in Ihr Konto abrufen
POST/api/v1/mirror-tasks/startupload:writeDatei an die gewählten Hoster senden
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readAuftragsstatus, jeder Hoster und der Freigabelink (shareTakenDown kennzeichnet eine entfernte Seite)
GET/api/v1/filesfile:readIhre Dateien auflisten (Cursor-Paginierung, Suche, Filter)
GET/api/v1/files/{id}file:readEine Datei: Größe, Prüfsumme, Auftrag, Freigabeeinstellungen, Statistiken
GET/api/v1/files/{id}/mirrorsfile:readAlle Kopien einer Datei: Hoster, Link, Zustand, Klicks
PATCH/api/v1/files/{id}/sharefile:writeFreigabepasswort, Ablauf, Sichtbarkeit
DELETE/api/v1/files/{id}file:deleteDatei und (standardmäßig) ihre Kopien bei den Hostern löschen
GET/api/v1/platformkeiner (öffentlich)Aktuelle Limits: größte Datei, Hoster pro Datei, Limits für URL-Uploads
GET/api/v1/providerskeiner (öffentlich)Der Hoster-Katalog mit den Slugs, die Sie in providerSlugs senden
GET/api/v1/providers/statuskeiner (öffentlich)Gemessener Upload-Erfolg pro Hoster
GET/api/v1/stats/publickeiner (öffentlich)Plattformsummen der letzten 30 Tage: Dateien, aktive Mirrors, Erfolgsquote

Eine Datei hochladen und verteilen

  1. Öffnen Sie eine Sitzung mit POST /api/v1/upload-sessions. filename und sizeBytes (die exakte Länge in Bytes) sind Pflicht; mimeType und ein UUID-idempotencyKey sind optional – eine wiederholte Anfrage mit demselben Schlüssel liefert die bestehende Sitzung, statt eine zweite zu öffnen. Die Antwort enthält data.sessionId (nicht id) und data.chunkSize.
  2. Senden Sie die Bytes mit PATCH /api/v1/upload-sessions/{id}/chunks: Rohbytes, Content-Type application/offset+octet-stream und die Startposition des Teils im Header upload-offset. Teile werden der Reihe nach gesendet oder bis zu maxChunksAhead Teile im Voraus; senden Sie der Reihe nach, verwenden Sie data.uploadedBytes aus jeder Antwort als nächsten Offset. Senden Sie Teile von chunkSize Bytes; jeder Teil außer dem letzten muss mindestens 5 MiB groß sein, und ein Upload darf höchstens 10 000 Teile haben. Die Antwort, die die Datei vervollständigt, enthält data.fileId. Für mehr Geschwindigkeit können Sie 2–3 Teile derselben Datei gleichzeitig unterwegs haben. Senden Sie den ersten Teil allein; seine Antwort liefert den tatsächlichen Wert von data.maxChunksAhead (4, wenn der erste Teil ein ganzer chunkSize-Abschnitt war, 0 = nur der Reihe nach). War der erste Teil ein ganzer chunkSize-Abschnitt, muss jeder spätere Teil ebenfalls einer sein (der Reihe nach oder im Voraus): Er beginnt bei einem Vielfachen von chunkSize und ist genau chunkSize Bytes groß (der letzte: der Rest der Datei). Ein Teil, der vor uploadedBytes vorausgesendet wird, muss ein solcher Abschnitt sein und darf höchstens data.maxChunksAhead Teile vorausliegen, sonst erhält er 409 CHUNK_MISALIGNED oder 409 CHUNK_OUT_OF_WINDOW. uploadedBytes zählt nur die lückenlos empfangenen Bytes, und der Teil, der die Datei vervollständigt – egal welcher –, erhält die Antwort mit fileId. Das erneute Senden eines bereits angekommenen Teils ist ein harmloser Erfolg.
  3. Verteilen Sie mit POST /api/v1/mirror-tasks/start: fileId und providerSlugs sind Pflicht (die Slugs stammen aus GET /api/v1/providers). Optional: minSuccess (Standard 1 – wie viele Hoster die Datei annehmen müssen, damit der Auftrag nicht fehlschlägt; er ist nur completed, wenn auch jeder Hoster sie angenommen hat, sonst partially_completed. Hoster, die diesen Dateityp ablehnen, werden nicht gezählt), sharePassword, expiresInDays oder expiresAt. Die Antwort enthält uploadJobId, taskCount, shareSlug, alreadyStarted und skipped[] – ein Hoster, der diese Datei nicht annehmen kann, wird übersprungen, nicht als fehlgeschlagen gewertet; lesen Sie also skipped[] (die Gründe sind unten aufgeführt). Eine Datei kann derzeit an höchstens 50 Hoster gehen.
  4. Verfolgen Sie den Abschluss mit GET /api/v1/mirror-tasks/{uploadJobId} alle paar Sekunden, bis data.terminal den Wert true hat. Die Antwort listet jeden Hoster in tasks[] auf (providerSlug, status, mirrorUrl, errorCode) und den Freigabelink in data.shareUrl. data.shareTakenDown ist true, wenn diese Freigabeseite gesperrt wurde und sich nicht mehr öffnen lässt.

Die größte derzeit akzeptierte Datei ist 5,00 GB.

bash, benötigt 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

Beispielantworten

Das Öffnen einer Sitzung antwortet mit 201. Jeder Teil außer dem letzten antwortet mit { uploadedBytes, completed: false, expiresAt }; der letzte enthält die Datei. distribution ist nur vorhanden, wenn Sie beim Öffnen der Sitzung einen Plan übergeben haben (siehe unten).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (vervollständigt die Datei) → 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
      }
    ]
  }
}

Ein erster, erfolgreicher start antwortet mit 202; ein erneuter Aufruf für einen bereits laufenden Auftrag antwortet mit 200 und alreadyStarted: true. Wird der Link eines Hosters aufgrund einer Richtlinie privat gehalten, ist mirrorUrl null und mirrorHidden true – die Freigabeseite listet ihn trotzdem auf.

Den zweiten Aufruf sparen

Übergeben Sie distribution beim Öffnen der Sitzung, und der Server beginnt mit der Verteilung, sobald die Datei vollständig ist. Prüfen Sie data.distribution in der Antwort, die die Datei vervollständigt: started: true bedeutet, dass der Auftrag eingereiht ist (uploadJobId, shareSlug). Bei started: false und deferred: true ist absichtlich noch nichts eingereiht – siehe unten. Bei started: false ohne deferred war der Upload zwar erfolgreich, die Verteilung konnte aber nicht starten (error nennt den Grund): Rufen Sie POST /api/v1/mirror-tasks/start mit der fileId auf. Ein error zusammen mit deferred: true bedeutet einen vorübergehenden Fehler (zum Beispiel sind alle Hoster ausgelastet oder in Wartung): Rufen Sie nicht start auf und laden Sie die Datei nicht erneut hoch – der Server versucht ab autoStartAt selbst erneut, die Verteilung zu starten (bis zu 5 Versuche). Rufen Sie hold-distribution auf, um das zu verhindern.

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": "…" } }

Fügen Sie deferred: true zu distribution hinzu, um eine Karenzzeit zu erhalten: Die letzte Antwort lautet { started: false, deferred: true, autoStartAt }, und der Server startet die Verteilung selbst zum Zeitpunkt autoStartAt (etwa 2 Minuten später), sofern Sie nicht vorher start aufrufen. Um den automatischen Start zu verhindern, rufen Sie POST /api/v1/upload-sessions/{id}/hold-distribution auf (ohne Body; autoStartAt wird null, und Sie starten selbst). Um stattdessen den Plan zu ändern, rufen Sie PUT /api/v1/upload-sessions/{id}/distribution-intent mit denselben Feldern wie distribution auf (providerSlugs, minSuccess, expiresInDays, sharePassword): Dies ersetzt den Plan und hebt ein Anhalten auf, und nach Abschluss des Uploads verschiebt sich der automatische Start auf mindestens 2 Minuten nach dem Aufruf. Hat die Verteilung bereits begonnen, antworten beide mit 200, und distribution-intent meldet alreadyStarted: true.

Starten Sie innerhalb von 30 Minuten. Ist ein Upload abgeschlossen und wird keine Verteilung gestartet, wird unsere Kopie der Datei nach 30 Minuten entfernt (mit einem Verteilungsplan, der noch auf verfügbare Hoster wartet, nach höchstens 72 Stunden; Uploads per URL sind nicht betroffen). Danach antworten start und distribution-intent mit 409 SOURCE_GONE, und die Datei muss erneut hochgeladen werden.

Wenn die letzte Antwort verloren geht

Rufen Sie GET /api/v1/upload-sessions/{id} auf: Eine fileId bedeutet, dass die Datei existiert; finalizable: true bedeutet, dass alle Bytes angekommen sind und POST /api/v1/upload-sessions/{id}/complete den Upload abschließt. Dieser Aufruf ist sicher wiederholbar und erzeugt nie eine zweite Datei. Ein nicht passender Offset erhält 409 CHUNK_OFFSET_CONFLICT – senden Sie HEAD an die Sitzung und setzen Sie ab ihrem Header Upload-Offset fort. Ein erneuter Aufruf von start für einen laufenden Auftrag ist kein Fehler: Sie erhalten 200 mit alreadyStarted: true.

Upload von einer URL

POST /api/v1/remote-uploads nimmt { "urls": [...] } entgegen und ruft jede Datei für Sie ab (Scope upload:write). Abgerufen werden nur http- und https-Links, private Netzwerkadressen werden abgelehnt, und es wird nur einer begrenzten Zahl von Weiterleitungen gefolgt. Eine Anfrage enthält höchstens 10 URLs (geliefert von GET /api/v1/platform); teilen Sie längere Listen auf.

Das Größenlimit pro Datei hängt von der Quelle ab. Gibt sie die Größe der Datei an, darf jede Datei bis zu 5,00 GB (limits.remoteUploadPassthroughMaxBytes) groß sein; gibt sie sie nicht an, bis zu 100,0 MB (limits.remoteUploadMaxBytes). Der Dateiname stammt aus dem Header Content-Disposition der Quelle, sofern sie einen sendet; ein Name ohne Endung erhält eine anhand des Dateityps.

Die Anfrage wartet, während die Dateien heruntergeladen werden. Bricht die Verbindung vorher ab, landet die Datei trotzdem in Ihrem Konto – Sie finden sie mit GET /api/v1/files. Jede fileId wird dann wie oben mit POST /api/v1/mirror-tasks/start verteilt.

Ist der Zwischenspeicher voll, erhält die gesamte Anfrage 503 TEMPORARILY_UNAVAILABLE mit details.reason: "staging_full" und einem Header Retry-After. Passt nur eine URL nicht, hat dieser Eintrag in results[] ok: false und denselben Code; ein Ergebnis pro URL hat keinen Header, daher steht die Wartezeit in Sekunden 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.

Dateien verwalten

Ihre Dateien bleiben nach dem Upload in Ihrem Konto. Listen Sie sie mit GET /api/v1/files auf (limit bis 100; übergeben Sie nextCursor aus der Antwort als cursor für die nächste Seite, q sucht nach Namen). GET /api/v1/files/{id} liefert eine Datei mit ihrem Auftrag, ihren Freigabeeinstellungen und Aufrufstatistiken; GET /api/v1/files/{id}/mirrors listet jede Kopie mit Link, Zustand und Klicks auf.

PATCH /api/v1/files/{id}/share (Scope file:write) ändert die Freigabeseite: password (4–128 Zeichen, null entfernt es – es wird nie zurückgegeben, nur passwordProtected), expiresAt (ISO-Datum, null für keinen Ablauf), visibility und hideDownloadCount. Senden Sie nur die Felder, die Sie ändern möchten. DELETE /api/v1/files/{id} (Scope file:delete) entfernt die Datei und reiht ihre Kopien bei den Hostern zur Löschung ein; fügen Sie ?keepMirrors=true hinzu, um sie zu behalten. Manche Hoster unterstützen kein Löschen, daher kann dort eine Kopie verbleiben.

bash, benötigt jq; FILE_ID setzen

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

Webhooks

Fügen Sie auf der Seite Webhooks einen Endpunkt hinzu. Die URL muss https:// verwenden; ihr Signatur-Secret (whsec_…) wird einmal beim Erstellen angezeigt. Ein Endpunkt ohne ausgewählte Ereignisse erhält alle.

EreignisWann
upload.completedJeder Hoster hat die Datei angenommen, und zwar mindestens minSuccess – Hoster, die diese Datei abgelehnt haben (rejected) oder abgebrochen wurden, werden nicht gezählt
upload.partially_completedMindestens minSuccess Hoster haben die Datei angenommen, aber mindestens ein anderer Hoster ist fehlgeschlagen
upload.failedWeniger als minSuccess Hoster haben die Datei angenommen (minSuccess 0 zählt als 1)
upload.quarantinedDer Malware-Scan hat die Datei markiert (nur bei aktiviertem Scan)
provider.upload_succeededEin Hoster hat die Datei angenommen – einmal pro Hoster gesendet
provider.upload_failedEin Hoster hat die Datei aufgegeben – einmal pro Hoster gesendet
webhook.testSie haben auf der Webhooks-Seite auf „Testen“ geklickt

Jede Zustellung ist ein POST mit JSON-Body und den Headern X-MUX-Event und X-MUX-Signature. Jede 2xx-Antwort innerhalb von 10 Sekunden gilt als zugestellt; Weiterleitungen wird nicht gefolgt. Eine fehlgeschlagene Zustellung (Netzwerkfehler, Timeout, 408, 425, 429 oder 5xx) wird nach 1, 5 und 30 Minuten mit demselben Body wiederholt; andere 4xx-Antworten und Weiterleitungen nicht. Jeder Versuch enthält X-MUX-Delivery-Attempt (1–4) und eine neue Signatur – deduplizieren Sie daher anhand des Bodys. Die Zustellreihenfolge ist nicht garantiert (ein wiederholtes Ereignis kann nach einem neueren ankommen); vergleichen Sie data und createdAt, bevor Sie darauf reagieren. Verwenden Sie GET /api/v1/mirror-tasks/{uploadJobId}, um aufzuholen. Nach 15 aufeinanderfolgenden Zustellungen, deren letzter Versuch fehlschlug, oder nach einer Stunde Fehlschlägen ohne einen einzigen Erfolg wird der Endpunkt pausiert; das erneute Aktivieren setzt den Zähler zurück. Eine webhook.test-Zustellung (die Schaltfläche „Testen“) wird einmal mit X-MUX-Delivery-Attempt: 1 gesendet und nie wiederholt.

Body
{
  "event": "provider.upload_succeeded",
  "createdAt": "2026-09-25T12:00:00.000Z",
  "data": {
    "uploadJobId": "…",
    "fileId": "…",
    "provider": "gofile",
    "providerName": "Gofile",
    "status": "succeeded",
    "mirrorUrl": "https://…"
  }
}

upload.*-Ereignisse enthalten uploadJobId, fileId und status; provider.upload_failed enthält errorCode statt mirrorUrl.

Signatur prüfen

Der Header sieht so aus: t=1727265600,v1=5f2b…. t ist der Signaturzeitpunkt in Unix-Sekunden, v1 ist der hexadezimale HMAC-SHA256 von <t>.<raw body> mit dem Secret Ihres Endpunkts als Schlüssel. Hashen Sie die Rohbytes genau so, wie sie empfangen wurden, vergleichen Sie in konstanter Zeit und lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind.

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

Rate-Limits

Limits werden pro API-Schlüssel gezählt, nicht pro IP-Adresse. Jede Antwort eines begrenzten Endpunkts enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Epoch-Sekunden). Bei Überschreitung folgt 429 RATE_LIMITED mit einem Header Retry-After – warten Sie so viele Sekunden. Uploads von Teilen haben ein großzügiges Budget; die engen Limits betreffen das Öffnen von Sitzungen und das Starten von Verteilungen.

BucketEndpunktePro SchlüsselZeitfenster
Uploads startenPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 Minute
Teile hochladenPATCH /api/v1/upload-sessions/{id}/chunks6001 Minute
Fortschritt abfragenGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 Minute
Verteilungseinstellungen eines UploadsPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 Minute
Verteilung startenPOST /api/v1/mirror-tasks/start301 Minute
Uploads per URLPOST /api/v1/remote-uploads2010 Minuten
Dateien lesenGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 Minute
Dateien ändernPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 Minute
Öffentlicher KatalogGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 Minute

Dies sind die Standardwerte. Der Betreiber kann sie ändern, daher sind die oben genannten Header immer maßgeblich. Die genauen Werte für Ihre Schlüssel und wie viel Sie davon aktuell verbraucht haben, finden Sie auf der Seite API-Schlüssel. Anfragen ohne Schlüssel werden pro IP-Adresse gezählt und erhalten kleinere Budgets für Uploads starten (10 statt 60), Teile hochladen (300 statt 600), Fortschritt abfragen (300 statt 600), Verteilungseinstellungen eines Uploads (60 statt 300), Verteilung starten (10 statt 30) und dasselbe Budget für Uploads per URL und öffentlicher Katalog. Dateien lesen und Dateien ändern benötigen immer einen Schlüssel.

Fehler

Erfolgreiche Antworten haben die Form { "success": true, "data": … }. Fehler verwenden eine einheitliche Form, zusätzlich zum HTTP-Status. code ist stabil – verzweigen Sie danach; message ist für Menschen gedacht und kann sich ändern. details wird hinzugefügt, wenn es mehr Kontext gibt, retryable gibt an, ob ein erneuter Versuch derselben Anfrage helfen kann, und requestId hilft uns, Ihre Anfrage zu finden, wenn Sie sich an den Support wenden.

Fehler
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CodeHTTPWiederholen?Bedeutung
NO_TOKEN401NeinEs wurde kein API-Schlüssel gesendet
INVALID_API_KEY401NeinDer Schlüssel ist falsch oder widerrufen
INSUFFICIENT_SCOPE403NeinDem Schlüssel fehlt der Scope, den dieser Endpunkt benötigt
API_KEY_NOT_ALLOWED403NeinDieser Endpunkt kann nicht mit einem API-Schlüssel verwendet werden
EMAIL_NOT_VERIFIED403NeinBestätigen Sie zuerst die E-Mail-Adresse des Kontos; offene Sitzungen funktionieren weiter
SESSION_REVOKED401NeinDie Anmeldesitzung wurde beendet (Passwort zurückgesetzt oder geändert, Abmeldung); melden Sie sich erneut an
ACCOUNT_INACTIVE403NeinDas Konto ist gesperrt oder zur Löschung vorgemerkt
ACCOUNT_DISABLED401 / 409NeinDas Konto wurde gesperrt: 401 bei der Schlüsselprüfung, 409, wenn sich dies während der laufenden Anfrage geändert hat
ACCOUNT_PENDING_DELETION409NeinDas Konto wurde während der laufenden Anfrage zur Löschung vorgemerkt; es wird nichts Neues gestartet
VALIDATION_ERROR400NeinDer Body oder ein Parameter ist ungültig; siehe details
FILE_REJECTED400NeinDateityp oder -größe ist nicht erlaubt; details.reason nennt den Grund
TOO_MANY_MIRRORS400NeinMehr Hoster, als eine Datei haben darf
NO_CONNECTED_PROVIDERS400NeinJeder ausgewählte Hoster benötigt Ihr eigenes Konto, und keiner ist verbunden
PROVIDER_REJECTS_FILE400NeinKein ausgewählter Hoster akzeptiert diesen Dateityp oder diese Größe
NO_AVAILABLE_PROVIDERS400NeinKeiner der ausgewählten Hoster nimmt gerade Uploads an; wählen Sie andere oder versuchen Sie es später. `details.waiting` listet Hoster, die nur pausiert sind (etwa ein Tageslimit, das innerhalb von 24 Stunden fällt): Für diese funktioniert ein späterer Versuch, obwohl `retryable` false ist
NO_VALID_PROVIDERS400NeinKein Wert in providerSlugs passt zu einem aktivierten Hoster; siehe GET /api/v1/providers
INVALID_JOB_STATE400NeinDer Auftrag kann in seinem aktuellen Zustand nicht gestartet werden
JOB_NOT_READY400NeinDie Datei hat noch keinen Verteilungsauftrag
FILE_TOO_LARGE_FOR_UPLOAD400NeinDie Datei passt nicht in 10 000 Teile der Teilgröße der Sitzung; details.limitBytes
MISSING_OFFSET400NeinEin Teil wurde ohne numerischen Header upload-offset gesendet
RAW_BODY_REQUIRED400NeinDer Body eines Teils muss aus Rohbytes mit content-type application/offset+octet-stream bestehen
TOO_MANY_URLS400NeinMehr URLs in einer remote-uploads-Anfrage als erlaubt
FILE_NOT_FOUND404NeinKeine solche Datei in Ihrem Konto (oder sie wurde gelöscht)
JOB_NOT_FOUND404NeinKein solcher Verteilungsauftrag in Ihrem Konto
SESSION_NOT_FOUND404NeinKeine solche Upload-Sitzung in Ihrem Konto
SHARE_NOT_FOUND404NeinDie Datei hat noch keine Freigabeseite
QUOTA_EXCEEDED409NeinEin tägliches oder gleichzeitiges Upload-Limit; details.retryAt gibt an, wann es frei wird
CHUNK_OFFSET_CONFLICT409Neinupload-offset passt nicht zu den empfangenen Bytes; ab HEAD fortsetzen
CHUNK_TOO_SMALL409NeinEin Teil außer dem letzten ist kleiner als 5 MiB
CHUNK_TOO_MANY_PARTS409NeinMehr als 10 000 Teile; senden Sie größere
CHUNK_MISALIGNED409NeinDer Teil ist kein ganzer chunkSize-Abschnitt, der bei einem Vielfachen von chunkSize beginnt: erforderlich für einen vorausgesendeten Teil und, wenn der erste Teil ein ganzer chunkSize-Abschnitt war, auch für jeden späteren Teil (der Reihe nach oder im Voraus); oder ein Teil wurde in einer Sitzung vorausgesendet, die Teile nur der Reihe nach annimmt
CHUNK_OUT_OF_WINDOW409NeinEin Teil beginnt mehr als maxChunksAhead Teile nach uploadedBytes oder überhaupt danach, bevor der erste Teil angenommen wurde; senden Sie ihn nach den früheren erneut
CHUNK_EXCEEDS_DECLARED_SIZE409NeinDer Teil geht über die beim Erstellen der Sitzung angegebene Dateigröße hinaus
CHUNK_EMPTY409NeinDer Teil enthält keine Bytes
CHUNK_NOT_RECEIVABLE409NeinDie Sitzung nimmt keine Daten mehr an (sie wurde abgeschlossen, abgebrochen oder ist abgelaufen); öffnen Sie eine neue
SESSION_EXPIRED409NeinDie Upload-Sitzung ist abgelaufen; öffnen Sie eine neue
SESSION_NOT_RECEIVABLE409NeinDie Sitzung wurde abgebrochen oder ist abgelaufen und nimmt keine Änderungen mehr an
SESSION_COMPLETED409NeinDer Upload ist bereits abgeschlossen; löschen Sie stattdessen die Datei
UPLOAD_INCOMPLETE409NeinNoch sind nicht alle Bytes angekommen; senden Sie zuerst die restlichen Teile (details enthält die Zahlen)
IDEMPOTENCY_KEY_CONFLICT409NeinDieser idempotencyKey wird bereits von einem anderen Upload verwendet; nutzen Sie pro Upload einen eindeutigen Schlüssel
SOURCE_GONE409NeinUnsere Kopie der Datei wurde bereits entfernt, daher kann sie nicht an Hoster gesendet werden, bei denen sie noch nicht versucht wurde; laden Sie sie für diese erneut hoch. Unsere Kopie wird entfernt, sobald ein Verteilungsauftrag endet (abgeschlossen, teilweise abgeschlossen oder fehlgeschlagen), und ein Upload, dessen Verteilung nie gestartet wird, wird 30 Minuten nach seinem Abschluss entfernt (bis zu 72 Stunden, wenn sein Verteilungsplan noch auf Hoster wartet; ausgenommen Uploads per URL). Ein erneuter Aufruf von mirror-tasks/start für einen beendeten Auftrag mit ausschließlich bereits versuchten Hostern wendet nur die Freigabeeinstellungen an (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409NeinDer Auftrag ist fehlgeschlagen, wurde abgebrochen oder befindet sich in einem Zustand, in dem er nicht mehr verteilt werden kann
SHARE_TAKEN_DOWN409NeinDie Freigabeseite der Datei wurde gesperrt, daher kann sie an keine weiteren Hoster gesendet werden
FINALIZING409JaEine andere Anfrage setzt die Datei gerade zusammen; fragen Sie in ein paar Sekunden erneut
CONFLICT409JaKollision mit einer anderen laufenden Änderung; wiederholen Sie dieselbe Anfrage
TEMPORARILY_UNAVAILABLE503Ja, nach Retry-AfterDer Server ist gerade ausgelastet; versuchen Sie es nach der Retry-After-Wartezeit erneut. details.reason "staging_full": Der Zwischenspeicher ist voll, es wurde kein neuer Upload angenommen (Retry-After etwa 10 Minuten); bereits laufende Uploads funktionieren weiter
PAYLOAD_TOO_LARGE413NeinDer Request-Body (oder ein Teil) ist größer, als der Server akzeptiert
REMOTE_TOO_LARGEpro URLNeinIn einem remote-uploads-Ergebnis: Die Datei überschreitet das Limit für URL-Uploads
RATE_LIMITED429Ja, nach Retry-AfterZu viele Anfragen für diesen Bucket
INTERNAL_ERROR500JaServerfehler; Details werden protokolliert, nie zurückgegeben
MAINTENANCE503Ja, nach Retry-AfterNeue Uploads sind vorerst pausiert; Lesezugriffe funktionieren weiter
UPLOADS_TEMPORARILY_UNAVAILABLE503Ja, nach Retry-AfterUnser Upload-Zähler konnte nicht gelesen werden; es wurde keine Sitzung geöffnet
SHUTTING_DOWN503Ja, nach Retry-AfterDer Server startet neu (Retry-After 5 Sekunden); warten Sie und senden Sie dieselbe Anfrage erneut – es wurde nichts verarbeitet

Warum ein Hoster übersprungen wurde

Dies sind keine Fehler: Sie erscheinen in skipped[].reason eines erfolgreichen start (und von distribution in der Antwort, die die Datei vervollständigt). Die anderen Hoster erhalten die Datei trotzdem. Nur wenn kein ausgewählter Hoster sie annehmen kann, schlägt der Aufruf fehl: PROVIDER_REJECTS_FILE (keiner akzeptiert diese Datei), NO_CONNECTED_PROVIDERS (jeder benötigt Ihr eigenes Konto), NO_AVAILABLE_PROVIDERS (keiner nimmt gerade Uploads an) oder NO_VALID_PROVIDERS (kein Slug passt zu einem aktivierten Hoster).

GrundBedeutung
UNKNOWN_PROVIDEREs gibt keinen Hoster mit diesem Slug – prüfen Sie die Schreibweise anhand von GET /api/v1/providers
PROVIDER_DISABLEDDer Hoster ist gerade deaktiviert oder in Wartung
ACCOUNT_REQUIREDDer Hoster nimmt Uploads nur in Ihr eigenes Konto an – verbinden Sie es auf der Seite „Verbindungen“
GUEST_UPLOAD_OFFDer Hoster nimmt gerade keine Uploads an und kann nicht mit einem Konto verbunden werden
DAILY_LIMIT_REACHEDDas Tageslimit des Hosters für Uploads ohne Konto ist vorerst aufgebraucht (bis zu 24 Std.) – verbinden Sie Ihr eigenes Konto, um trotzdem hochzuladen
FILE_TOO_LARGEDie Datei überschreitet das Größenlimit dieses Hosters
MIME_NOT_ALLOWEDDer Hoster akzeptiert diesen Dateityp nicht
ALREADY_ATTEMPTEDDieser Hoster wurde für diese Datei bereits versucht, daher wird sie nicht erneut dorthin gesendet

Die API-Referenz listet die Codes auf, die jeder Endpunkt zurückgeben kann.