Documentation de l’API
Envoyez un fichier une seule fois, transmettez-le aux hébergeurs de votre choix et récupérez un lien de partage unique — depuis votre propre code.
Mis à jour le
Une API REST versionnée : envoyez un fichier par morceaux, transmettez-le aux hébergeurs de votre choix, et toutes les copies sont réunies sur une page de partage unique avec leur état en direct.
- URL de base
- https://api.mirroruploadx.com/api/v1
- Authentification
- x-api-key: mux_…
1Ouvrir une session
POST /
api/ v1/ upload-sessions filename + sizeBytes ; récupérez sessionId et chunkSize
2Envoyer les morceaux
PATCH /
api/ v1/ upload-sessions/ {id}/ chunks octets bruts dans l’ordre ; la réponse qui complète le fichier contient fileId
3Distribuer
POST /
api/ v1/ mirror-tasks/ start fileId + providerSlugs ; puis interrogez la tâche
Créez une clé sur la page Clés API. Guide complet avec code dans Envoyer et distribuer.
Authentification
Créez une clé sur la page Clés API de votre tableau de bord. La clé complète (elle commence par mux_) n’est affichée qu’une fois : conservez-la immédiatement. Envoyez-la dans l’en-tête x-api-key à chaque requête ; Authorization: Bearer mux_… est accepté de la même façon pour les clients qui ne gèrent que les jetons bearer.
Les clés ont des portées : une clé n’accède qu’aux endpoints couverts par ses portées, et un appel avec la mauvaise portée renvoie 403 INSUFFICIENT_SCOPE, avec la portée requise dans le message. Les paramètres du compte, la gestion des clés et les webhooks ne sont pas accessibles du tout avec une clé API (API_KEY_NOT_ALLOWED).
| Portée | Accès |
|---|---|
upload:write | Sessions d’envoi (création, morceaux, finalisation, annulation), votre quota d’envoi, suspension ou modification de la distribution automatique d’un envoi (hold-distribution, distribution-intent), envois par URL, lancement de la distribution |
file:read | Liste des fichiers, détails des fichiers, état des miroirs et des tâches |
file:write | Paramètres de partage d’un fichier |
file:delete | Suppression d’un fichier et de ses miroirs |
Endpoints
Tout ce qu’une clé API peut atteindre, ainsi que les endpoints publics qui ne nécessitent aucune clé. Lorsque la colonne des portées en indique deux, l’une ou l’autre suffit. Les schémas de requête et de réponse de chacun figurent dans la référence de l’API.
| Méthode | Chemin | Portée | Rôle |
|---|---|---|---|
| POST | / | upload:write | Ouvrir une session d’envoi (avec un plan de distribution facultatif) |
| PATCH | / | upload:write | Envoyer le morceau d’octets suivant |
| HEAD | / | upload:write | Où reprendre : l’en-tête Upload-Offset |
| GET | / | upload:writefile:read | État de la session : octets reçus, fileId, finalizable |
| GET | / | upload:writefile:read | Vos limites d’envoi, votre utilisation et vos sessions inachevées |
| POST | / | upload:write | Finaliser un envoi dont la réponse finale s’est perdue (relance sans risque) |
| POST | / | upload:write | Empêcher une distribution différée de démarrer d’elle-même |
| PUT | / | upload:write | Remplacer le plan de distribution d’un envoi |
| DELETE | / | upload:write | Annuler un envoi inachevé et libérer sa place |
| POST | / | upload:write | Récupérer des fichiers depuis des URL http(s) dans votre compte |
| POST | / | upload:write | Envoyer un fichier aux hébergeurs choisis |
| GET | / | upload:writefile:read | État de la tâche, chaque hébergeur et le lien de partage (shareTakenDown signale une page retirée) |
| GET | / | file:read | Lister vos fichiers (pagination par curseur, recherche, filtres) |
| GET | / | file:read | Un fichier : taille, somme de contrôle, tâche, paramètres de partage, statistiques |
| GET | / | file:read | Toutes les copies d’un fichier : hébergeur, lien, état, clics |
| PATCH | / | file:write | Mot de passe, expiration et visibilité du partage |
| DELETE | / | file:delete | Supprimer un fichier et (par défaut) ses copies chez les hébergeurs |
| GET | / | aucune (public) | Limites actuelles : fichier le plus volumineux, hébergeurs par fichier, plafonds d’envoi par URL |
| GET | / | aucune (public) | Le catalogue des hébergeurs, avec les slugs à envoyer dans providerSlugs |
| GET | / | aucune (public) | Taux de réussite des envois mesuré par hébergeur |
| GET | / | aucune (public) | Totaux de la plateforme sur les 30 derniers jours : fichiers, miroirs en ligne, taux de réussite |
Envoyer un fichier et le distribuer
- Ouvrez une session avec
POST /api/v1/upload-sessions.filenameetsizeBytes(la longueur exacte en octets) sont obligatoires ;mimeTypeet unidempotencyKeyUUID sont facultatifs — répéter une requête avec la même clé renvoie la session existante au lieu d’en ouvrir une seconde. La réponse contientdata.sessionId(et nonid) etdata.chunkSize. - Envoyez les octets avec
PATCH /api/v1/upload-sessions/{id}/chunks: octets bruts, type de contenuapplication/offset+octet-stream, et position de début du morceau dans l’en-têteupload-offset. Les morceaux sont envoyés dans l’ordre, ou jusqu’àmaxChunksAheadmorceaux en avance ; en envoi ordonné, utilisezdata.uploadedBytesde chaque réponse comme offset suivant. Envoyez des morceaux dechunkSizeoctets ; chaque morceau sauf le dernier doit faire au moins 5 MiB, et un envoi peut compter au plus 10 000 morceaux. La réponse qui complète le fichier contientdata.fileId. Pour aller plus vite, vous pouvez avoir 2 à 3 morceaux du même fichier en cours d’envoi. Envoyez le premier morceau seul ; sa réponse donne la valeur réelle dedata.maxChunksAhead(4 si le premier morceau était une tranche complète dechunkSize, 0 = ordre strict uniquement). Si le premier morceau était une tranche complète dechunkSize, chaque morceau suivant doit l’être aussi (dans l’ordre ou en avance) : il commence à un multiple dechunkSizeet fait exactementchunkSizeoctets (le dernier : le reste du fichier). Un morceau envoyé en avance suruploadedBytesdoit être une telle tranche et commencer au plusdata.maxChunksAheadmorceaux en avance, sinon il reçoit409 CHUNK_MISALIGNEDou409 CHUNK_OUT_OF_WINDOW.uploadedBytesne compte que les octets reçus sans trou, et le morceau qui complète le fichier, quel qu’il soit, reçoit la réponse avecfileId. Renvoyer un morceau déjà arrivé est un succès sans conséquence. - Distribuez avec
POST /api/v1/mirror-tasks/start:fileIdetproviderSlugssont obligatoires (les slugs proviennent deGET /api/v1/providers). Facultatifs :minSuccess(1 par défaut — le nombre d’hébergeurs qui doivent accepter le fichier pour que la tâche n’échoue pas ; elle n’estcompletedque si tous les hébergeurs l’ont aussi accepté, sinonpartially_completed. Les hébergeurs qui refusent ce type de fichier ne sont pas comptés),sharePassword,expiresInDaysouexpiresAt. La réponse contientuploadJobId,taskCount,shareSlug,alreadyStartedetskipped[]— un hébergeur qui ne peut pas accepter ce fichier est ignoré, pas en échec ; lisez doncskipped[](les motifs sont listés ci-dessous). Un fichier peut actuellement être envoyé vers 50 hébergeurs au maximum. - Suivez la fin de l’opération avec
GET /api/v1/mirror-tasks/{uploadJobId}toutes les quelques secondes, jusqu’à ce quedata.terminalvailletrue. La réponse liste chaque hébergeur danstasks[](providerSlug,status,mirrorUrl,errorCode) et le lien de partage dansdata.shareUrl.data.shareTakenDownvauttruelorsque cette page de partage a été retirée et ne s’ouvre plus.
Le plus gros fichier accepté actuellement fait 5,00 GB.
bash, nécessite 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";
}Exemples de réponses
L’ouverture d’une session répond 201. Chaque morceau sauf le dernier répond { uploadedBytes, completed: false, expiresAt } ; le dernier renvoie le fichier. distribution n’est présent que si vous avez transmis un plan à l’ouverture de la session (voir ci-dessous).
{
"success": true,
"data": {
"sessionId": "…",
"uploadedBytes": 0,
"chunkSize": 8388608,
"maxChunksAhead": 0
}
}{
"success": true,
"data": {
"uploadedBytes": 10485760,
"completed": true,
"fileId": "…",
"scan": "skipped",
"distributable": true,
"distribution": {
"started": true,
"uploadJobId": "…",
"taskCount": 2,
"shareSlug": "…",
"skipped": []
}
}
}{
"success": true,
"data": {
"uploadJobId": "…",
"taskCount": 2,
"shareSlug": "…",
"skipped": [],
"alreadyStarted": false
}
}{
"success": true,
"data": {
"uploadJobId": "…",
"status": "completed",
"terminal": true,
"shareSlug": "…",
"shareUrl": "https://mirroruploadx.com/f/…",
"shareTakenDown": false,
"minSuccess": 1,
"scan": "skipped",
"tasks": [
{
"provider": "Gofile",
"providerSlug": "gofile",
"status": "succeeded",
"attempts": 1,
"errorCode": null,
"viaOwnAccount": false,
"errorMessage": null,
"mirrorUrl": "https://gofile.io/d/…",
"mirrorHidden": false
},
{
"provider": "Pixeldrain",
"providerSlug": "pixeldrain",
"status": "succeeded",
"attempts": 1,
"errorCode": null,
"viaOwnAccount": false,
"errorMessage": null,
"mirrorUrl": "https://pixeldrain.com/u/…",
"mirrorHidden": false
}
]
}
}Un premier start réussi répond 202 ; le rappeler pour une tâche déjà en cours répond 200 avec alreadyStarted: true. Lorsque le lien d’un hébergeur est gardé privé par choix, mirrorUrl vaut null et mirrorHidden vaut true — la page de partage le liste quand même.
Se passer du second appel
Transmettez distribution à l’ouverture de la session et le serveur lance la distribution dès que le fichier est complet. Vérifiez data.distribution dans la réponse qui complète le fichier : started: true signifie que la tâche est en file d’attente (uploadJobId, shareSlug). Avec started: false et deferred: true, rien n’est encore en file d’attente, volontairement — voir ci-dessous. Avec started: false sans deferred, l’envoi a bien réussi mais la distribution n’a pas pu démarrer (error indique pourquoi) : appelez POST /api/v1/mirror-tasks/start avec le fileId. Un error accompagné de deferred: true signale un échec temporaire (par exemple, tous les hébergeurs sont occupés ou en maintenance) : n’appelez pas start et ne renvoyez pas le fichier — le serveur retentera lui-même de lancer la distribution à partir de autoStartAt (jusqu’à 5 tentatives). Appelez hold-distribution pour l’arrêter.
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": "…" } }Ajoutez deferred: true à distribution pour bénéficier d’un délai de grâce : la réponse finale est { started: false, deferred: true, autoStartAt } et le serveur lance lui-même la distribution à autoStartAt (environ 2 minutes plus tard), sauf si vous appelez start avant. Pour empêcher le démarrage automatique, appelez POST /api/v1/upload-sessions/{id}/hold-distribution (sans corps ; autoStartAt passe à null et c’est à vous de lancer la distribution). Pour modifier plutôt le plan, appelez PUT /api/v1/upload-sessions/{id}/distribution-intent avec les mêmes champs que distribution (providerSlugs, minSuccess, expiresInDays, sharePassword) : cela remplace le plan et lève une suspension, et une fois l’envoi terminé, le démarrage automatique est repoussé à au moins 2 minutes après l’appel. Si la distribution a déjà démarré, les deux répondent 200 et distribution-intent indique alreadyStarted: true.
Lancez la distribution dans les 30 minutes. Lorsqu’un envoi se termine sans qu’aucune distribution ne soit lancée, notre copie du fichier est supprimée au bout de 30 minutes (au bout de 72 heures au maximum si un plan de distribution attend encore que des hébergeurs redeviennent disponibles ; les envois par URL ne sont pas concernés). Passé ce délai, start et distribution-intent répondent 409 SOURCE_GONE et le fichier doit être envoyé à nouveau.
Si la réponse finale se perd
Appelez GET /api/v1/upload-sessions/{id} : un fileId signifie que le fichier existe ; finalizable: true signifie que tous les octets sont arrivés et que POST /api/v1/upload-sessions/{id}/complete le finalise. Cet appel peut être relancé sans risque et ne crée jamais de second fichier. Un offset incohérent reçoit 409 CHUNK_OFFSET_CONFLICT — envoyez HEAD sur la session et reprenez à partir de son en-tête Upload-Offset. Rappeler start pour une tâche en cours n’est pas une erreur : vous recevez 200 avec alreadyStarted: true.
Envoyer depuis une URL
POST /api/v1/remote-uploads accepte { "urls": [...] } et récupère chaque fichier pour vous (portée upload:write). Seuls les liens http et https sont récupérés, les adresses de réseaux privés sont refusées et seul un nombre limité de redirections est suivi. Une requête contient au plus 10 URL (valeur renvoyée par GET /api/v1/platform) ; découpez les listes plus longues.
La taille maximale par fichier dépend de la source. Si elle indique la taille du fichier, chaque fichier peut atteindre 5,00 GB (limits.remoteUploadPassthroughMaxBytes) ; sinon, 100,0 MB (limits.remoteUploadMaxBytes). Le nom du fichier provient de l’en-tête Content-Disposition de la source lorsqu’elle en envoie un ; un nom sans extension en reçoit une d’après le type du fichier.
La requête attend pendant le téléchargement des fichiers. Si la connexion coupe avant, le fichier arrive quand même dans votre compte — retrouvez-le avec GET /api/v1/files. Chaque fileId est ensuite distribué avec POST /api/v1/mirror-tasks/start, comme ci-dessus.
Lorsque le stockage temporaire est plein, la requête entière reçoit 503 TEMPORARILY_UNAVAILABLE avec details.reason: "staging_full" et un en-tête Retry-After. Si une seule URL ne passe pas, l’entrée correspondante de results[] contient ok: false et le même code ; un résultat par URL n’a pas d’en-tête, le délai d’attente en secondes se trouve donc dans 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.Gérer les fichiers
Vos fichiers restent dans votre compte après l’envoi. Listez-les avec GET /api/v1/files (limit jusqu’à 100 ; passez le nextCursor de la réponse comme cursor pour la page suivante, q recherche par nom). GET /api/v1/files/{id} renvoie un fichier avec sa tâche, ses paramètres de partage et ses statistiques de vues ; GET /api/v1/files/{id}/mirrors liste chaque copie avec son lien, son état et ses clics.
PATCH /api/v1/files/{id}/share (portée file:write) modifie la page de partage : password (4 à 128 caractères, null le supprime — il n’est jamais renvoyé, seul passwordProtected l’est), expiresAt (date ISO, null pour aucune expiration), visibility et hideDownloadCount. N’envoyez que les champs à modifier. DELETE /api/v1/files/{id} (portée file:delete) supprime le fichier et met en file d’attente la suppression de ses copies chez les hébergeurs ; ajoutez ?keepMirrors=true pour les conserver. Certains hébergeurs ne permettent pas la suppression ; une copie peut donc y subsister.
bash, nécessite jq ; définissez FILE_ID
API=https://api.mirroruploadx.com
H="x-api-key: $MUX_API_KEY"
# List your files, newest first (20 per page; pass ?cursor=<nextCursor> for more)
curl -sS "$API/api/v1/files?limit=20" -H "$H" | jq '.data.items[] | {id, name, mirrorCount, shareSlug}'
# One file, then every copy of it
curl -sS "$API/api/v1/files/$FILE_ID" -H "$H"
curl -sS "$API/api/v1/files/$FILE_ID/mirrors" -H "$H" | jq '.data.mirrors[] | {providerSlug, status, url}'
# Share settings: a password and an expiry date (null removes either)
curl -sS -X PATCH "$API/api/v1/files/$FILE_ID/share" -H "$H" -H "content-type: application/json" \
-d '{"password":"correct-horse","expiresAt":"2026-12-31T23:59:59Z"}'
# Delete the file and its copies on hosts (?keepMirrors=true keeps the copies)
curl -sS -X DELETE "$API/api/v1/files/$FILE_ID" -H "$H"requests ; définissez FILE_ID
import os, requests
API = "https://api.mirroruploadx.com"
H = {"x-api-key": os.environ["MUX_API_KEY"]}
file_id = os.environ["FILE_ID"]
def call(method, path, **kw):
body = requests.request(method, API + path, headers=H, timeout=60, **kw).json()
if not body.get("success"):
raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
return body["data"]
# List your files, page by page
cursor = None
while True:
page = call("GET", "/api/v1/files", params={"limit": 100, **({"cursor": cursor} if cursor else {})})
for f in page["items"]:
print(f["id"], f["name"], f"{f['mirrorCount']}/{f['mirrorTotal']} mirrors")
cursor = page["nextCursor"]
if not cursor:
break
# One file, then every copy of it
print(call("GET", f"/api/v1/files/{file_id}")["share"])
for m in call("GET", f"/api/v1/files/{file_id}/mirrors")["mirrors"]:
print(m["providerSlug"], m["status"], m["url"])
# Share settings: a password and an expiry date (None removes either)
print(call("PATCH", f"/api/v1/files/{file_id}/share",
json={"password": "correct-horse", "expiresAt": "2026-12-31T23:59:59Z"}))
# Delete the file and its copies on hosts
print(call("DELETE", f"/api/v1/files/{file_id}")["note"])Node.js 18+, module ES ; définissez FILE_ID
const API = 'https://api.mirroruploadx.com';
const KEY = process.env.MUX_API_KEY;
const fileId = process.env.FILE_ID;
async function call(method, path, json) {
const res = await fetch(API + path, {
method,
headers: { 'x-api-key': KEY, ...(json ? { 'content-type': 'application/json' } : {}) },
body: json ? JSON.stringify(json) : undefined,
});
const out = await res.json();
if (!out.success) throw new Error(`${res.status} ${out.error.code}: ${out.error.message}`);
return out.data;
}
// List your files, page by page
let cursor = null;
do {
const page = await call('GET', `/api/v1/files?limit=100${cursor ? `&cursor=${cursor}` : ''}`);
for (const f of page.items) console.log(f.id, f.name, `${f.mirrorCount}/${f.mirrorTotal} mirrors`);
cursor = page.nextCursor;
} while (cursor);
// One file, then every copy of it
console.log((await call('GET', `/api/v1/files/${fileId}`)).share);
for (const m of (await call('GET', `/api/v1/files/${fileId}/mirrors`)).mirrors) {
console.log(m.providerSlug, m.status, m.url);
}
// Share settings: a password and an expiry date (null removes either)
console.log(await call('PATCH', `/api/v1/files/${fileId}/share`, {
password: 'correct-horse',
expiresAt: '2026-12-31T23:59:59Z',
}));
// Delete the file and its copies on hosts
console.log((await call('DELETE', `/api/v1/files/${fileId}`)).note);PHP 8.1+, ext-curl ; définissez FILE_ID
<?php
// PHP 8.1+, built-in ext-curl and ext-json only (no Composer)
declare(strict_types=1);
const API = 'https://api.mirroruploadx.com';
$fileId = getenv('FILE_ID');
function call(string $method, string $path, ?array $json = null, ?string $body = null, array $headers = []): array
{
$h = ['x-api-key: ' . getenv('MUX_API_KEY'), 'expect:']; // no 100-continue round trip
if ($json !== null) {
$h[] = 'content-type: application/json';
$body = json_encode($json, JSON_THROW_ON_ERROR);
}
foreach ($headers as $k => $v) {
$h[] = "$k: $v";
}
$ch = curl_init(API . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $h,
CURLOPT_RETURNTRANSFER => true,
// no total cap (a large part can take minutes); give up on a stalled transfer instead
CURLOPT_TIMEOUT => 0,
CURLOPT_CONNECTTIMEOUT => 15,
CURLOPT_LOW_SPEED_LIMIT => 1024, // bytes per second
CURLOPT_LOW_SPEED_TIME => 60,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
}
$raw = curl_exec($ch);
if ($raw === false) {
throw new RuntimeException('network error: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$out = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (empty($out['success'])) {
$err = $out['error'];
throw new RuntimeException("$status {$err['code']}: {$err['message']}");
}
return $out['data'];
}
// List your files, page by page (http_build_query drops a null cursor)
$cursor = null;
do {
$page = call('GET', '/api/v1/files?' . http_build_query(['limit' => 100, 'cursor' => $cursor]));
foreach ($page['items'] as $f) {
echo "{$f['id']} {$f['name']} {$f['mirrorCount']}/{$f['mirrorTotal']} mirrors\n";
}
$cursor = $page['nextCursor'];
} while ($cursor);
// One file, then every copy of it
print_r(call('GET', "/api/v1/files/$fileId")['share']);
foreach (call('GET', "/api/v1/files/$fileId/mirrors")['mirrors'] as $m) {
echo "{$m['providerSlug']} {$m['status']} {$m['url']}\n";
}
// Share settings: a password and an expiry date (null removes either)
print_r(call('PATCH', "/api/v1/files/$fileId/share",
json: ['password' => 'correct-horse', 'expiresAt' => '2026-12-31T23:59:59Z']));
// Delete the file and its copies on hosts
echo call('DELETE', "/api/v1/files/$fileId")['note'], "\n";{
"success": true,
"data": {
"stagingDeleted": true,
"mirrorsQueued": true,
"mirrorsPurgeDeferred": false,
"note": "File removed. Copies on providers are being deleted; some may remain on providers that do not support deletion."
}
}Webhooks
Ajoutez un endpoint sur la page Webhooks. L’URL doit utiliser https:// ; son secret de signature (whsec_…) n’est affiché qu’une fois, à sa création. Un endpoint sans événement sélectionné les reçoit tous.
| Événement | Quand |
|---|---|
upload.completed | Tous les hébergeurs ont accepté le fichier, et au moins minSuccess l’ont fait — les hébergeurs qui ont refusé ce fichier (rejected) ou ont été annulés ne sont pas comptés |
upload.partially_completed | Au moins minSuccess hébergeurs ont accepté le fichier, mais au moins un autre hébergeur a échoué |
upload.failed | Moins de minSuccess hébergeurs ont accepté le fichier (minSuccess 0 compte comme 1) |
upload.quarantined | L’analyse antivirus a signalé le fichier (uniquement lorsque l’analyse est activée) |
provider.upload_succeeded | Un hébergeur a accepté le fichier — envoyé une fois par hébergeur |
provider.upload_failed | Un hébergeur a renoncé au fichier — envoyé une fois par hébergeur |
webhook.test | Vous avez cliqué sur Tester sur la page Webhooks |
Chaque livraison est un POST unique avec un corps JSON et les en-têtes X-MUX-Event et X-MUX-Signature. Toute réponse 2xx en moins de 10 secondes compte comme livrée ; les redirections ne sont pas suivies. Une livraison échouée (erreur réseau, délai dépassé, 408, 425, 429 ou 5xx) est relancée après 1, 5 et 30 minutes avec le même corps ; les autres 4xx et les redirections ne le sont pas. Chaque tentative porte X-MUX-Delivery-Attempt (1–4) et une nouvelle signature : dédoublonnez donc d’après le corps. L’ordre de livraison n’est pas garanti (un événement relancé peut arriver après un plus récent) ; comparez data et createdAt avant d’agir. Utilisez GET /api/v1/mirror-tasks/{uploadJobId} pour vous resynchroniser. Après 15 livraisons consécutives dont la dernière tentative a échoué, ou une heure d’échecs sans un seul succès, l’endpoint est suspendu ; le réactiver remet le compteur à zéro. Une livraison webhook.test (le bouton Tester) est envoyée une seule fois, avec X-MUX-Delivery-Attempt: 1, et n’est jamais relancée.
{
"event": "provider.upload_succeeded",
"createdAt": "2026-09-25T12:00:00.000Z",
"data": {
"uploadJobId": "…",
"fileId": "…",
"provider": "gofile",
"providerName": "Gofile",
"status": "succeeded",
"mirrorUrl": "https://…"
}
}Les événements upload.* contiennent uploadJobId, fileId et status ; provider.upload_failed contient errorCode au lieu de mirrorUrl.
Vérifier la signature
L’en-tête ressemble à t=1727265600,v1=5f2b… : t est l’heure de signature en secondes Unix, v1 est le HMAC-SHA256 hexadécimal de <t>.<raw body> calculé avec le secret de votre endpoint. Hachez les octets bruts exactement tels que reçus, comparez en temps constant et rejetez les horodatages de plus de 5 minutes.
Express
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(
header.split(',').map((kv) => {
const i = kv.indexOf('=');
return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
}),
);
const t = Number(parts.t);
if (!Number.isFinite(t) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // too old: replay
const expected = createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest();
const got = Buffer.from(parts.v1, 'hex');
return got.length === expected.length && timingSafeEqual(got, expected);
}
const app = express();
// Raw bytes, not parsed JSON: the signature covers the body exactly as sent.
app.post('/hooks/mirroruploadx', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(req.body, req.get('x-mux-signature') ?? '', process.env.MUX_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const { event, data } = JSON.parse(req.body);
console.log(event, data.uploadJobId);
res.sendStatus(204); // any 2xx counts as delivered
});
app.listen(3000);Flask
import hashlib, hmac, os, time
from flask import Flask, abort, request
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(kv.strip().split("=", 1) for kv in header.split(",") if "=" in kv)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or not v1 or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
app = Flask(__name__)
@app.post("/hooks/mirroruploadx")
def hook():
# get_data(): the raw bytes, exactly as signed
if not verify(request.get_data(), request.headers.get("X-MUX-Signature", ""),
os.environ["MUX_WEBHOOK_SECRET"]):
abort(401)
payload = request.get_json()
print(payload["event"], payload["data"].get("uploadJobId"))
return "", 204 # any 2xx counts as deliveredPHP 8.1+ natif
<?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 deliveredLimites de débit
Les limites sont comptées par clé API, et non par adresse IP. Chaque réponse d’un endpoint limité contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes epoch). En cas de dépassement, la réponse est 429 RATE_LIMITED avec un en-tête Retry-After — attendez ce nombre de secondes. L’envoi des morceaux dispose d’un budget large ; les limites étroites portent sur l’ouverture des sessions et le lancement des distributions.
| Catégorie | Endpoints | Par clé | Fenêtre |
|---|---|---|---|
| Démarrage des envois | POST /POST /DELETE / | 60 | 1 minute |
| Envoi des morceaux | PATCH / | 600 | 1 minute |
| Suivi de la progression | GET /HEAD /GET /GET / | 600 | 1 minute |
| Paramètres de distribution d’un envoi | POST /PUT / | 300 | 1 minute |
| Lancement de la distribution | POST / | 30 | 1 minute |
| Envois distants (URL) | POST / | 20 | 10 minutes |
| Lecture des fichiers | GET /GET /GET / | 300 | 1 minute |
| Modification des fichiers | PATCH /DELETE / | 60 | 1 minute |
| Catalogue public | GET /GET /GET /GET / | 300 | 1 minute |
Ce sont les valeurs par défaut. L’exploitant peut les modifier ; les en-têtes ci-dessus font donc toujours foi. Les valeurs exactes pour vos clés, et la part que vous en avez utilisée à cet instant, figurent sur la page Clés API. Les requêtes sans clé sont comptées par adresse IP et bénéficient de budgets réduits pour démarrage des envois (10 au lieu de 60), envoi des morceaux (300 au lieu de 600), suivi de la progression (300 au lieu de 600), paramètres de distribution d’un envoi (60 au lieu de 300), lancement de la distribution (10 au lieu de 30), et du même budget pour envois distants (URL) et catalogue public. Lecture des fichiers et modification des fichiers nécessitent toujours une clé.
Erreurs
Les réponses réussies prennent la forme { "success": true, "data": … }. Les erreurs utilisent une forme unique, accompagnée du statut HTTP. code est stable — basez votre logique dessus ; message est destiné aux humains et peut changer. details est ajouté lorsqu’il y a plus de contexte, retryable indique si relancer la même requête peut aider, et requestId nous aide à retrouver votre requête si vous contactez le support.
{
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "This endpoint needs one of these API key scopes: upload:write.",
"requestId": "…",
"retryable": false
}
}| Code | HTTP | Relancer ? | Signification |
|---|---|---|---|
NO_TOKEN | 401 | Non | Aucune clé API n’a été envoyée |
INVALID_API_KEY | 401 | Non | La clé est incorrecte ou révoquée |
INSUFFICIENT_SCOPE | 403 | Non | La clé n’a pas la portée requise par cet endpoint |
API_KEY_NOT_ALLOWED | 403 | Non | Cet endpoint ne peut pas être utilisé avec une clé API |
EMAIL_NOT_VERIFIED | 403 | Non | Vérifiez d’abord l’e-mail du compte ; les sessions ouvertes continuent de fonctionner |
SESSION_REVOKED | 401 | Non | La session de connexion a pris fin (réinitialisation ou changement du mot de passe, déconnexion) ; reconnectez-vous |
ACCOUNT_INACTIVE | 403 | Non | Le compte est suspendu ou en cours de suppression |
ACCOUNT_DISABLED | 401 / 409 | Non | Le compte a été suspendu : 401 lors de la vérification de la clé, 409 si ce changement est survenu pendant la requête |
ACCOUNT_PENDING_DELETION | 409 | Non | La suppression du compte a été programmée pendant la requête ; rien de nouveau n’est lancé |
VALIDATION_ERROR | 400 | Non | Le corps ou un paramètre n’est pas valide ; voir details |
FILE_REJECTED | 400 | Non | Le type ou la taille du fichier n’est pas autorisé ; details.reason précise lequel |
TOO_MANY_MIRRORS | 400 | Non | Plus d’hébergeurs que ce qu’un fichier peut avoir |
NO_CONNECTED_PROVIDERS | 400 | Non | Chaque hébergeur sélectionné nécessite votre propre compte et aucun n’est connecté |
PROVIDER_REJECTS_FILE | 400 | Non | Aucun hébergeur sélectionné n’accepte ce type ou cette taille de fichier |
NO_AVAILABLE_PROVIDERS | 400 | Non | Aucun des hébergeurs sélectionnés n’accepte d’envois pour le moment ; choisissez-en d’autres ou réessayez plus tard. `details.waiting` liste les hébergeurs seulement en pause (par exemple une limite quotidienne, levée sous 24 heures) : pour eux, réessayer plus tard fonctionne même si `retryable` vaut false |
NO_VALID_PROVIDERS | 400 | Non | Aucune valeur de providerSlugs ne correspond à un hébergeur activé ; voir GET /api/v1/providers |
INVALID_JOB_STATE | 400 | Non | La tâche ne peut pas être lancée dans son état actuel |
JOB_NOT_READY | 400 | Non | Le fichier n’a pas encore de tâche de distribution |
FILE_TOO_LARGE_FOR_UPLOAD | 400 | Non | Le fichier ne tient pas dans 10 000 morceaux de la taille de morceau de la session ; details.limitBytes |
MISSING_OFFSET | 400 | Non | Un morceau a été envoyé sans en-tête upload-offset numérique |
RAW_BODY_REQUIRED | 400 | Non | Le corps d’un morceau doit être constitué d’octets bruts avec le content-type application/offset+octet-stream |
TOO_MANY_URLS | 400 | Non | Plus d’URL que le nombre autorisé dans une requête remote-uploads |
FILE_NOT_FOUND | 404 | Non | Ce fichier n’existe pas dans votre compte (ou a été supprimé) |
JOB_NOT_FOUND | 404 | Non | Cette tâche de distribution n’existe pas dans votre compte |
SESSION_NOT_FOUND | 404 | Non | Cette session d’envoi n’existe pas dans votre compte |
SHARE_NOT_FOUND | 404 | Non | Le fichier n’a pas encore de page de partage |
QUOTA_EXCEEDED | 409 | Non | Limite d’envoi quotidienne ou simultanée atteinte ; details.retryAt indique quand elle se libère |
CHUNK_OFFSET_CONFLICT | 409 | Non | upload-offset ne correspond pas aux octets reçus ; reprenez à partir de HEAD |
CHUNK_TOO_SMALL | 409 | Non | Un morceau autre que le dernier fait moins de 5 MiB |
CHUNK_TOO_MANY_PARTS | 409 | Non | Plus de 10 000 morceaux ; envoyez-en de plus gros |
CHUNK_MISALIGNED | 409 | Non | Le morceau n’est pas une tranche complète de chunkSize commençant à un multiple de chunkSize : c’est obligatoire pour un morceau envoyé en avance et, si le premier morceau était une tranche complète de chunkSize, pour chaque morceau suivant aussi (dans l’ordre ou en avance) ; ou bien un morceau a été envoyé en avance dans une session qui n’accepte les morceaux que dans l’ordre |
CHUNK_OUT_OF_WINDOW | 409 | Non | Un morceau commence plus de maxChunksAhead morceaux après uploadedBytes, ou au-delà tout court avant que le premier morceau ait été accepté ; renvoyez-le après les précédents |
CHUNK_EXCEEDS_DECLARED_SIZE | 409 | Non | Le morceau dépasse la taille de fichier déclarée à la création de la session |
CHUNK_EMPTY | 409 | Non | Le morceau ne contient aucun octet |
CHUNK_NOT_RECEIVABLE | 409 | Non | La session n’accepte plus de données (elle a été finalisée, annulée ou a expiré) ; ouvrez-en une nouvelle |
SESSION_EXPIRED | 409 | Non | La session d’envoi a expiré ; ouvrez-en une nouvelle |
SESSION_NOT_RECEIVABLE | 409 | Non | La session a été annulée ou a expiré et n’accepte plus de modifications |
SESSION_COMPLETED | 409 | Non | L’envoi est déjà terminé ; supprimez plutôt le fichier |
UPLOAD_INCOMPLETE | 409 | Non | Tous les octets ne sont pas arrivés ; envoyez d’abord les morceaux restants (details contient les comptes) |
IDEMPOTENCY_KEY_CONFLICT | 409 | Non | Cet idempotencyKey est déjà utilisé par un autre envoi ; utilisez une clé unique par envoi |
SOURCE_GONE | 409 | Non | Notre copie du fichier a déjà été supprimée ; il ne peut donc pas être envoyé aux hébergeurs sur lesquels il n’a pas encore été tenté : envoyez-le à nouveau pour ceux-là. Notre copie est supprimée dès qu’une tâche de distribution se termine (terminée, partiellement terminée ou échouée), et un envoi dont la distribution n’est jamais lancée est supprimé 30 minutes après sa fin (jusqu’à 72 heures si son plan de distribution attend encore des hébergeurs ; envois par URL exceptés). Rappeler mirror-tasks/start pour une tâche terminée avec uniquement des hébergeurs déjà tentés applique simplement les paramètres de partage (alreadyStarted: true) |
JOB_NOT_DISTRIBUTABLE | 409 | Non | La tâche a échoué, a été annulée ou se trouve dans un état qui ne permet plus la distribution |
SHARE_TAKEN_DOWN | 409 | Non | La page de partage du fichier a été retirée ; il ne peut donc pas être envoyé à d’autres hébergeurs |
FINALIZING | 409 | Oui | Une autre requête est en train d’assembler le fichier ; redemandez dans quelques secondes |
CONFLICT | 409 | Oui | Conflit avec une autre modification en cours ; relancez la même requête |
TEMPORARILY_UNAVAILABLE | 503 | Oui, après Retry-After | Le serveur est très sollicité en ce moment ; réessayez après le délai Retry-After. details.reason "staging_full" : le stockage temporaire est plein, aucun nouvel envoi n’a été accepté (Retry-After d’environ 10 minutes) ; les envois déjà en cours continuent de fonctionner |
PAYLOAD_TOO_LARGE | 413 | Non | Le corps de la requête (ou un morceau) dépasse la taille acceptée par le serveur |
REMOTE_TOO_LARGE | par URL | Non | Dans un résultat remote-uploads : le fichier dépasse la limite d’envoi par URL |
RATE_LIMITED | 429 | Oui, après Retry-After | Trop de requêtes pour cette catégorie |
INTERNAL_ERROR | 500 | Oui | Erreur serveur ; les détails sont journalisés, jamais renvoyés |
MAINTENANCE | 503 | Oui, après Retry-After | Les nouveaux envois sont suspendus pour le moment ; les lectures continuent de fonctionner |
UPLOADS_TEMPORARILY_UNAVAILABLE | 503 | Oui, après Retry-After | Notre compteur d’envois n’a pas pu être lu ; aucune session n’a été ouverte |
SHUTTING_DOWN | 503 | Oui, après Retry-After | Le serveur redémarre (Retry-After de 5 secondes) ; patientez et renvoyez la même requête — rien n’a été traité |
Pourquoi un hébergeur a été ignoré
Ce ne sont pas des erreurs : ces motifs arrivent dans skipped[].reason d’un start réussi (et de distribution dans la réponse qui complète le fichier). Les autres hébergeurs reçoivent quand même le fichier. L’appel n’échoue que si aucun hébergeur sélectionné ne peut l’accepter : PROVIDER_REJECTS_FILE (aucun n’accepte ce fichier), NO_CONNECTED_PROVIDERS (tous nécessitent votre propre compte), NO_AVAILABLE_PROVIDERS (aucun n’accepte d’envois pour le moment) ou NO_VALID_PROVIDERS (aucun slug ne correspond à un hébergeur activé).
| Motif | Signification |
|---|---|
UNKNOWN_PROVIDER | Aucun hébergeur ne porte ce slug — vérifiez l’orthographe avec GET /api/v1/providers |
PROVIDER_DISABLED | L’hébergeur est désactivé ou en maintenance pour le moment |
ACCOUNT_REQUIRED | L’hébergeur n’accepte que les envois vers votre propre compte — connectez-le sur la page Connexions |
GUEST_UPLOAD_OFF | L’hébergeur n’accepte pas d’envois pour le moment et ne peut pas être connecté à un compte |
DAILY_LIMIT_REACHED | La limite quotidienne de l’hébergeur pour les envois sans compte est épuisée pour le moment (jusqu’à 24 h) — connectez votre propre compte pour pouvoir y envoyer malgré tout |
FILE_TOO_LARGE | Le fichier dépasse la taille maximale de cet hébergeur |
MIME_NOT_ALLOWED | L’hébergeur n’accepte pas ce type de fichier |
ALREADY_ATTEMPTED | Cet hébergeur a déjà été essayé pour ce fichier ; il n’y est pas renvoyé |
La référence de l’API liste les codes que chaque endpoint peut renvoyer.