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_…
1Sitzung öffnen
POST /
api/ v1/ upload-sessions filename + sizeBytes; sessionId und chunkSize erhalten
2Teile senden
PATCH /
api/ v1/ upload-sessions/ {id}/ chunks Rohbytes der Reihe nach; die Antwort, die die Datei vervollständigt, enthält fileId
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).
| Scope | Erreicht |
|---|---|
upload:write | Upload-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:read | Dateien auflisten, Dateidetails, Mirror- und Auftragsstatus |
file:write | Freigabeeinstellungen einer Datei |
file:delete | Lö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.
| Methode | Pfad | Scope | Funktion |
|---|---|---|---|
| POST | / | upload:write | Upload-Sitzung öffnen (optional mit Verteilungsplan) |
| PATCH | / | upload:write | Nächsten Teil der Bytes senden |
| HEAD | / | upload:write | Wo fortgesetzt wird: der Header Upload-Offset |
| GET | / | upload:writefile:read | Sitzungsstatus: empfangene Bytes, fileId, finalizable |
| GET | / | upload:writefile:read | Ihre Upload-Limits, Nutzung und unfertigen Sitzungen |
| POST | / | upload:write | Upload abschließen, dessen letzte Antwort verloren ging (sicher wiederholbar) |
| POST | / | upload:write | Verhindern, dass eine aufgeschobene Verteilung von selbst startet |
| PUT | / | upload:write | Verteilungsplan eines Uploads ersetzen |
| DELETE | / | upload:write | Unfertigen Upload abbrechen und seinen Platz freigeben |
| POST | / | upload:write | Dateien von http(s)-URLs in Ihr Konto abrufen |
| POST | / | upload:write | Datei an die gewählten Hoster senden |
| GET | / | upload:writefile:read | Auftragsstatus, jeder Hoster und der Freigabelink (shareTakenDown kennzeichnet eine entfernte Seite) |
| GET | / | file:read | Ihre Dateien auflisten (Cursor-Paginierung, Suche, Filter) |
| GET | / | file:read | Eine Datei: Größe, Prüfsumme, Auftrag, Freigabeeinstellungen, Statistiken |
| GET | / | file:read | Alle Kopien einer Datei: Hoster, Link, Zustand, Klicks |
| PATCH | / | file:write | Freigabepasswort, Ablauf, Sichtbarkeit |
| DELETE | / | file:delete | Datei und (standardmäßig) ihre Kopien bei den Hostern löschen |
| GET | / | keiner (öffentlich) | Aktuelle Limits: größte Datei, Hoster pro Datei, Limits für URL-Uploads |
| GET | / | keiner (öffentlich) | Der Hoster-Katalog mit den Slugs, die Sie in providerSlugs senden |
| GET | / | keiner (öffentlich) | Gemessener Upload-Erfolg pro Hoster |
| GET | / | keiner (öffentlich) | Plattformsummen der letzten 30 Tage: Dateien, aktive Mirrors, Erfolgsquote |
Eine Datei hochladen und verteilen
- Öffnen Sie eine Sitzung mit
POST /api/v1/upload-sessions.filenameundsizeBytes(die exakte Länge in Bytes) sind Pflicht;mimeTypeund ein UUID-idempotencyKeysind optional – eine wiederholte Anfrage mit demselben Schlüssel liefert die bestehende Sitzung, statt eine zweite zu öffnen. Die Antwort enthältdata.sessionId(nichtid) unddata.chunkSize. - Senden Sie die Bytes mit
PATCH /api/v1/upload-sessions/{id}/chunks: Rohbytes, Content-Typeapplication/offset+octet-streamund die Startposition des Teils im Headerupload-offset. Teile werden der Reihe nach gesendet oder bis zumaxChunksAheadTeile im Voraus; senden Sie der Reihe nach, verwenden Siedata.uploadedBytesaus jeder Antwort als nächsten Offset. Senden Sie Teile vonchunkSizeBytes; 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ältdata.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 vondata.maxChunksAhead(4, wenn der erste Teil ein ganzerchunkSize-Abschnitt war, 0 = nur der Reihe nach). War der erste Teil ein ganzerchunkSize-Abschnitt, muss jeder spätere Teil ebenfalls einer sein (der Reihe nach oder im Voraus): Er beginnt bei einem Vielfachen vonchunkSizeund ist genauchunkSizeBytes groß (der letzte: der Rest der Datei). Ein Teil, der voruploadedBytesvorausgesendet wird, muss ein solcher Abschnitt sein und darf höchstensdata.maxChunksAheadTeile vorausliegen, sonst erhält er409 CHUNK_MISALIGNEDoder409 CHUNK_OUT_OF_WINDOW.uploadedByteszählt nur die lückenlos empfangenen Bytes, und der Teil, der die Datei vervollständigt – egal welcher –, erhält die Antwort mitfileId. Das erneute Senden eines bereits angekommenen Teils ist ein harmloser Erfolg. - Verteilen Sie mit
POST /api/v1/mirror-tasks/start:fileIdundproviderSlugssind Pflicht (die Slugs stammen ausGET /api/v1/providers). Optional:minSuccess(Standard 1 – wie viele Hoster die Datei annehmen müssen, damit der Auftrag nicht fehlschlägt; er ist nurcompleted, wenn auch jeder Hoster sie angenommen hat, sonstpartially_completed. Hoster, die diesen Dateityp ablehnen, werden nicht gezählt),sharePassword,expiresInDaysoderexpiresAt. Die Antwort enthältuploadJobId,taskCount,shareSlug,alreadyStartedundskipped[]– ein Hoster, der diese Datei nicht annehmen kann, wird übersprungen, nicht als fehlgeschlagen gewertet; lesen Sie alsoskipped[](die Gründe sind unten aufgeführt). Eine Datei kann derzeit an höchstens 50 Hoster gehen. - Verfolgen Sie den Abschluss mit
GET /api/v1/mirror-tasks/{uploadJobId}alle paar Sekunden, bisdata.terminalden Werttruehat. Die Antwort listet jeden Hoster intasks[]auf (providerSlug,status,mirrorUrl,errorCode) und den Freigabelink indata.shareUrl.data.shareTakenDownisttrue, 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.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";
}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).
{
"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
}
]
}
}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 -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.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.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"requests; FILE_ID setzen
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+, ES-Modul; FILE_ID setzen
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; FILE_ID setzen
<?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."
}
}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.
| Ereignis | Wann |
|---|---|
upload.completed | Jeder 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_completed | Mindestens minSuccess Hoster haben die Datei angenommen, aber mindestens ein anderer Hoster ist fehlgeschlagen |
upload.failed | Weniger als minSuccess Hoster haben die Datei angenommen (minSuccess 0 zählt als 1) |
upload.quarantined | Der Malware-Scan hat die Datei markiert (nur bei aktiviertem Scan) |
provider.upload_succeeded | Ein Hoster hat die Datei angenommen – einmal pro Hoster gesendet |
provider.upload_failed | Ein Hoster hat die Datei aufgegeben – einmal pro Hoster gesendet |
webhook.test | Sie 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.
{
"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);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 deliveredreines PHP 8.1+
<?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 deliveredRate-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.
| Bucket | Endpunkte | Pro Schlüssel | Zeitfenster |
|---|---|---|---|
| Uploads starten | POST /POST /DELETE / | 60 | 1 Minute |
| Teile hochladen | PATCH / | 600 | 1 Minute |
| Fortschritt abfragen | GET /HEAD /GET /GET / | 600 | 1 Minute |
| Verteilungseinstellungen eines Uploads | POST /PUT / | 300 | 1 Minute |
| Verteilung starten | POST / | 30 | 1 Minute |
| Uploads per URL | POST / | 20 | 10 Minuten |
| Dateien lesen | GET /GET /GET / | 300 | 1 Minute |
| Dateien ändern | PATCH /DELETE / | 60 | 1 Minute |
| Öffentlicher Katalog | GET /GET /GET /GET / | 300 | 1 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.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Code | HTTP | Wiederholen? | Bedeutung |
|---|---|---|---|
NO_TOKEN | 401 | Nein | Es wurde kein API-Schlüssel gesendet |
INVALID_API_KEY | 401 | Nein | Der Schlüssel ist falsch oder widerrufen |
INSUFFICIENT_SCOPE | 403 | Nein | Dem Schlüssel fehlt der Scope, den dieser Endpunkt benötigt |
API_KEY_NOT_ALLOWED | 403 | Nein | Dieser Endpunkt kann nicht mit einem API-Schlüssel verwendet werden |
EMAIL_NOT_VERIFIED | 403 | Nein | Bestätigen Sie zuerst die E-Mail-Adresse des Kontos; offene Sitzungen funktionieren weiter |
SESSION_REVOKED | 401 | Nein | Die Anmeldesitzung wurde beendet (Passwort zurückgesetzt oder geändert, Abmeldung); melden Sie sich erneut an |
ACCOUNT_INACTIVE | 403 | Nein | Das Konto ist gesperrt oder zur Löschung vorgemerkt |
ACCOUNT_DISABLED | 401 / 409 | Nein | Das Konto wurde gesperrt: 401 bei der Schlüsselprüfung, 409, wenn sich dies während der laufenden Anfrage geändert hat |
ACCOUNT_PENDING_DELETION | 409 | Nein | Das Konto wurde während der laufenden Anfrage zur Löschung vorgemerkt; es wird nichts Neues gestartet |
VALIDATION_ERROR | 400 | Nein | Der Body oder ein Parameter ist ungültig; siehe details |
FILE_REJECTED | 400 | Nein | Dateityp oder -größe ist nicht erlaubt; details.reason nennt den Grund |
TOO_MANY_MIRRORS | 400 | Nein | Mehr Hoster, als eine Datei haben darf |
NO_CONNECTED_PROVIDERS | 400 | Nein | Jeder ausgewählte Hoster benötigt Ihr eigenes Konto, und keiner ist verbunden |
PROVIDER_REJECTS_FILE | 400 | Nein | Kein ausgewählter Hoster akzeptiert diesen Dateityp oder diese Größe |
NO_AVAILABLE_PROVIDERS | 400 | Nein | Keiner 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_PROVIDERS | 400 | Nein | Kein Wert in providerSlugs passt zu einem aktivierten Hoster; siehe GET /api/v1/providers |
INVALID_JOB_STATE | 400 | Nein | Der Auftrag kann in seinem aktuellen Zustand nicht gestartet werden |
JOB_NOT_READY | 400 | Nein | Die Datei hat noch keinen Verteilungsauftrag |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | Nein | Die Datei passt nicht in 10 000 Teile der Teilgröße der Sitzung; details.limitBytes |
MISSING_OFFSET | 400 | Nein | Ein Teil wurde ohne numerischen Header upload-offset gesendet |
RAW_BODY_REQUIRED | 400 | Nein | Der Body eines Teils muss aus Rohbytes mit content-type application/offset+octet-stream bestehen |
TOO_MANY_URLS | 400 | Nein | Mehr URLs in einer remote-uploads-Anfrage als erlaubt |
FILE_NOT_FOUND | 404 | Nein | Keine solche Datei in Ihrem Konto (oder sie wurde gelöscht) |
JOB_NOT_FOUND | 404 | Nein | Kein solcher Verteilungsauftrag in Ihrem Konto |
SESSION_NOT_FOUND | 404 | Nein | Keine solche Upload-Sitzung in Ihrem Konto |
SHARE_NOT_FOUND | 404 | Nein | Die Datei hat noch keine Freigabeseite |
QUOTA_EXCEEDED | 409 | Nein | Ein tägliches oder gleichzeitiges Upload-Limit; details.retryAt gibt an, wann es frei wird |
CHUNK_OFFSET_CONFLICT | 409 | Nein | upload-offset passt nicht zu den empfangenen Bytes; ab HEAD fortsetzen |
CHUNK_TOO_SMALL | 409 | Nein | Ein Teil außer dem letzten ist kleiner als 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | Nein | Mehr als 10 000 Teile; senden Sie größere |
CHUNK_MISALIGNED | 409 | Nein | Der 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_WINDOW | 409 | Nein | Ein 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_SIZE | 409 | Nein | Der Teil geht über die beim Erstellen der Sitzung angegebene Dateigröße hinaus |
CHUNK_EMPTY | 409 | Nein | Der Teil enthält keine Bytes |
CHUNK_NOT_RECEIVABLE | 409 | Nein | Die Sitzung nimmt keine Daten mehr an (sie wurde abgeschlossen, abgebrochen oder ist abgelaufen); öffnen Sie eine neue |
SESSION_EXPIRED | 409 | Nein | Die Upload-Sitzung ist abgelaufen; öffnen Sie eine neue |
SESSION_NOT_RECEIVABLE | 409 | Nein | Die Sitzung wurde abgebrochen oder ist abgelaufen und nimmt keine Änderungen mehr an |
SESSION_COMPLETED | 409 | Nein | Der Upload ist bereits abgeschlossen; löschen Sie stattdessen die Datei |
UPLOAD_INCOMPLETE | 409 | Nein | Noch sind nicht alle Bytes angekommen; senden Sie zuerst die restlichen Teile (details enthält die Zahlen) |
IDEMPOTENCY_KEY_CONFLICT | 409 | Nein | Dieser idempotencyKey wird bereits von einem anderen Upload verwendet; nutzen Sie pro Upload einen eindeutigen Schlüssel |
SOURCE_GONE | 409 | Nein | Unsere 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_DISTRIBUTABLE | 409 | Nein | Der Auftrag ist fehlgeschlagen, wurde abgebrochen oder befindet sich in einem Zustand, in dem er nicht mehr verteilt werden kann |
SHARE_TAKEN_DOWN | 409 | Nein | Die Freigabeseite der Datei wurde gesperrt, daher kann sie an keine weiteren Hoster gesendet werden |
FINALIZING | 409 | Ja | Eine andere Anfrage setzt die Datei gerade zusammen; fragen Sie in ein paar Sekunden erneut |
CONFLICT | 409 | Ja | Kollision mit einer anderen laufenden Änderung; wiederholen Sie dieselbe Anfrage |
TEMPORARILY_UNAVAILABLE | 503 | Ja, nach Retry-After | Der 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_LARGE | 413 | Nein | Der Request-Body (oder ein Teil) ist größer, als der Server akzeptiert |
REMOTE_TOO_LARGE | pro URL | Nein | In einem remote-uploads-Ergebnis: Die Datei überschreitet das Limit für URL-Uploads |
RATE_LIMITED | 429 | Ja, nach Retry-After | Zu viele Anfragen für diesen Bucket |
INTERNAL_ERROR | 500 | Ja | Serverfehler; Details werden protokolliert, nie zurückgegeben |
MAINTENANCE | 503 | Ja, nach Retry-After | Neue Uploads sind vorerst pausiert; Lesezugriffe funktionieren weiter |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Ja, nach Retry-After | Unser Upload-Zähler konnte nicht gelesen werden; es wurde keine Sitzung geöffnet |
SHUTTING_DOWN | 503 | Ja, nach Retry-After | Der 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).
| Grund | Bedeutung |
|---|---|
UNKNOWN_PROVIDER | Es gibt keinen Hoster mit diesem Slug – prüfen Sie die Schreibweise anhand von GET /api/v1/providers |
PROVIDER_DISABLED | Der Hoster ist gerade deaktiviert oder in Wartung |
ACCOUNT_REQUIRED | Der Hoster nimmt Uploads nur in Ihr eigenes Konto an – verbinden Sie es auf der Seite „Verbindungen“ |
GUEST_UPLOAD_OFF | Der Hoster nimmt gerade keine Uploads an und kann nicht mit einem Konto verbunden werden |
DAILY_LIMIT_REACHED | Das 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_LARGE | Die Datei überschreitet das Größenlimit dieses Hosters |
MIME_NOT_ALLOWED | Der Hoster akzeptiert diesen Dateityp nicht |
ALREADY_ATTEMPTED | Dieser 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.