Aller au contenu

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_…
  1. 1Ouvrir une session

    POST /api/v1/upload-sessions

    filename + sizeBytes ; récupérez sessionId et chunkSize

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

  3. 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éeAccès
upload:writeSessions 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:readListe des fichiers, détails des fichiers, état des miroirs et des tâches
file:writeParamètres de partage d’un fichier
file:deleteSuppression 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éthodeCheminPortéeRôle
POST/api/v1/upload-sessionsupload:writeOuvrir une session d’envoi (avec un plan de distribution facultatif)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeEnvoyer le morceau d’octets suivant
HEAD/api/v1/upload-sessions/{id}upload:writeOù reprendre : l’en-tête Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readÉtat de la session : octets reçus, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readVos limites d’envoi, votre utilisation et vos sessions inachevées
POST/api/v1/upload-sessions/{id}/completeupload:writeFinaliser un envoi dont la réponse finale s’est perdue (relance sans risque)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeEmpêcher une distribution différée de démarrer d’elle-même
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeRemplacer le plan de distribution d’un envoi
DELETE/api/v1/upload-sessions/{id}upload:writeAnnuler un envoi inachevé et libérer sa place
POST/api/v1/remote-uploadsupload:writeRécupérer des fichiers depuis des URL http(s) dans votre compte
POST/api/v1/mirror-tasks/startupload:writeEnvoyer un fichier aux hébergeurs choisis
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readÉtat de la tâche, chaque hébergeur et le lien de partage (shareTakenDown signale une page retirée)
GET/api/v1/filesfile:readLister vos fichiers (pagination par curseur, recherche, filtres)
GET/api/v1/files/{id}file:readUn fichier : taille, somme de contrôle, tâche, paramètres de partage, statistiques
GET/api/v1/files/{id}/mirrorsfile:readToutes les copies d’un fichier : hébergeur, lien, état, clics
PATCH/api/v1/files/{id}/sharefile:writeMot de passe, expiration et visibilité du partage
DELETE/api/v1/files/{id}file:deleteSupprimer un fichier et (par défaut) ses copies chez les hébergeurs
GET/api/v1/platformaucune (public)Limites actuelles : fichier le plus volumineux, hébergeurs par fichier, plafonds d’envoi par URL
GET/api/v1/providersaucune (public)Le catalogue des hébergeurs, avec les slugs à envoyer dans providerSlugs
GET/api/v1/providers/statusaucune (public)Taux de réussite des envois mesuré par hébergeur
GET/api/v1/stats/publicaucune (public)Totaux de la plateforme sur les 30 derniers jours : fichiers, miroirs en ligne, taux de réussite

Envoyer un fichier et le distribuer

  1. Ouvrez une session avec POST /api/v1/upload-sessions. filename et sizeBytes (la longueur exacte en octets) sont obligatoires ; mimeType et un idempotencyKey UUID 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 contient data.sessionId (et non id) et data.chunkSize.
  2. Envoyez les octets avec PATCH /api/v1/upload-sessions/{id}/chunks : octets bruts, type de contenu application/offset+octet-stream, et position de début du morceau dans l’en-tête upload-offset. Les morceaux sont envoyés dans l’ordre, ou jusqu’à maxChunksAhead morceaux en avance ; en envoi ordonné, utilisez data.uploadedBytes de chaque réponse comme offset suivant. Envoyez des morceaux de chunkSize octets ; 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 contient data.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 de data.maxChunksAhead (4 si le premier morceau était une tranche complète de chunkSize, 0 = ordre strict uniquement). Si le premier morceau était une tranche complète de chunkSize, chaque morceau suivant doit l’être aussi (dans l’ordre ou en avance) : il commence à un multiple de chunkSize et fait exactement chunkSize octets (le dernier : le reste du fichier). Un morceau envoyé en avance sur uploadedBytes doit être une telle tranche et commencer au plus data.maxChunksAhead morceaux en avance, sinon il reçoit 409 CHUNK_MISALIGNED ou 409 CHUNK_OUT_OF_WINDOW. uploadedBytes ne 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 avec fileId. Renvoyer un morceau déjà arrivé est un succès sans conséquence.
  3. Distribuez avec POST /api/v1/mirror-tasks/start : fileId et providerSlugs sont obligatoires (les slugs proviennent de GET /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’est completed que si tous les hébergeurs l’ont aussi accepté, sinon partially_completed. Les hébergeurs qui refusent ce type de fichier ne sont pas comptés), sharePassword, expiresInDays ou expiresAt. La réponse contient uploadJobId, taskCount, shareSlug, alreadyStarted et skipped[] — un hébergeur qui ne peut pas accepter ce fichier est ignoré, pas en échec ; lisez donc skipped[] (les motifs sont listés ci-dessous). Un fichier peut actuellement être envoyé vers 50 hébergeurs au maximum.
  4. Suivez la fin de l’opération avec GET /api/v1/mirror-tasks/{uploadJobId} toutes les quelques secondes, jusqu’à ce que data.terminal vaille true. La réponse liste chaque hébergeur dans tasks[] (providerSlug, status, mirrorUrl, errorCode) et le lien de partage dans data.shareUrl. data.shareTakenDown vaut true lorsque 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.json

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

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

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

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

Webhooks

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énementQuand
upload.completedTous 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_completedAu moins minSuccess hébergeurs ont accepté le fichier, mais au moins un autre hébergeur a échoué
upload.failedMoins de minSuccess hébergeurs ont accepté le fichier (minSuccess 0 compte comme 1)
upload.quarantinedL’analyse antivirus a signalé le fichier (uniquement lorsque l’analyse est activée)
provider.upload_succeededUn hébergeur a accepté le fichier — envoyé une fois par hébergeur
provider.upload_failedUn hébergeur a renoncé au fichier — envoyé une fois par hébergeur
webhook.testVous 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.

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

Limites 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égorieEndpointsPar cléFenêtre
Démarrage des envoisPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 minute
Envoi des morceauxPATCH /api/v1/upload-sessions/{id}/chunks6001 minute
Suivi de la progressionGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 minute
Paramètres de distribution d’un envoiPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 minute
Lancement de la distributionPOST /api/v1/mirror-tasks/start301 minute
Envois distants (URL)POST /api/v1/remote-uploads2010 minutes
Lecture des fichiersGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 minute
Modification des fichiersPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 minute
Catalogue publicGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 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.

Erreur
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CodeHTTPRelancer ?Signification
NO_TOKEN401NonAucune clé API n’a été envoyée
INVALID_API_KEY401NonLa clé est incorrecte ou révoquée
INSUFFICIENT_SCOPE403NonLa clé n’a pas la portée requise par cet endpoint
API_KEY_NOT_ALLOWED403NonCet endpoint ne peut pas être utilisé avec une clé API
EMAIL_NOT_VERIFIED403NonVérifiez d’abord l’e-mail du compte ; les sessions ouvertes continuent de fonctionner
SESSION_REVOKED401NonLa session de connexion a pris fin (réinitialisation ou changement du mot de passe, déconnexion) ; reconnectez-vous
ACCOUNT_INACTIVE403NonLe compte est suspendu ou en cours de suppression
ACCOUNT_DISABLED401 / 409NonLe 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_DELETION409NonLa suppression du compte a été programmée pendant la requête ; rien de nouveau n’est lancé
VALIDATION_ERROR400NonLe corps ou un paramètre n’est pas valide ; voir details
FILE_REJECTED400NonLe type ou la taille du fichier n’est pas autorisé ; details.reason précise lequel
TOO_MANY_MIRRORS400NonPlus d’hébergeurs que ce qu’un fichier peut avoir
NO_CONNECTED_PROVIDERS400NonChaque hébergeur sélectionné nécessite votre propre compte et aucun n’est connecté
PROVIDER_REJECTS_FILE400NonAucun hébergeur sélectionné n’accepte ce type ou cette taille de fichier
NO_AVAILABLE_PROVIDERS400NonAucun 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_PROVIDERS400NonAucune valeur de providerSlugs ne correspond à un hébergeur activé ; voir GET /api/v1/providers
INVALID_JOB_STATE400NonLa tâche ne peut pas être lancée dans son état actuel
JOB_NOT_READY400NonLe fichier n’a pas encore de tâche de distribution
FILE_TOO_LARGE_FOR_UPLOAD400NonLe fichier ne tient pas dans 10 000 morceaux de la taille de morceau de la session ; details.limitBytes
MISSING_OFFSET400NonUn morceau a été envoyé sans en-tête upload-offset numérique
RAW_BODY_REQUIRED400NonLe corps d’un morceau doit être constitué d’octets bruts avec le content-type application/offset+octet-stream
TOO_MANY_URLS400NonPlus d’URL que le nombre autorisé dans une requête remote-uploads
FILE_NOT_FOUND404NonCe fichier n’existe pas dans votre compte (ou a été supprimé)
JOB_NOT_FOUND404NonCette tâche de distribution n’existe pas dans votre compte
SESSION_NOT_FOUND404NonCette session d’envoi n’existe pas dans votre compte
SHARE_NOT_FOUND404NonLe fichier n’a pas encore de page de partage
QUOTA_EXCEEDED409NonLimite d’envoi quotidienne ou simultanée atteinte ; details.retryAt indique quand elle se libère
CHUNK_OFFSET_CONFLICT409Nonupload-offset ne correspond pas aux octets reçus ; reprenez à partir de HEAD
CHUNK_TOO_SMALL409NonUn morceau autre que le dernier fait moins de 5 MiB
CHUNK_TOO_MANY_PARTS409NonPlus de 10 000 morceaux ; envoyez-en de plus gros
CHUNK_MISALIGNED409NonLe 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_WINDOW409NonUn 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_SIZE409NonLe morceau dépasse la taille de fichier déclarée à la création de la session
CHUNK_EMPTY409NonLe morceau ne contient aucun octet
CHUNK_NOT_RECEIVABLE409NonLa session n’accepte plus de données (elle a été finalisée, annulée ou a expiré) ; ouvrez-en une nouvelle
SESSION_EXPIRED409NonLa session d’envoi a expiré ; ouvrez-en une nouvelle
SESSION_NOT_RECEIVABLE409NonLa session a été annulée ou a expiré et n’accepte plus de modifications
SESSION_COMPLETED409NonL’envoi est déjà terminé ; supprimez plutôt le fichier
UPLOAD_INCOMPLETE409NonTous les octets ne sont pas arrivés ; envoyez d’abord les morceaux restants (details contient les comptes)
IDEMPOTENCY_KEY_CONFLICT409NonCet idempotencyKey est déjà utilisé par un autre envoi ; utilisez une clé unique par envoi
SOURCE_GONE409NonNotre 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_DISTRIBUTABLE409NonLa tâche a échoué, a été annulée ou se trouve dans un état qui ne permet plus la distribution
SHARE_TAKEN_DOWN409NonLa page de partage du fichier a été retirée ; il ne peut donc pas être envoyé à d’autres hébergeurs
FINALIZING409OuiUne autre requête est en train d’assembler le fichier ; redemandez dans quelques secondes
CONFLICT409OuiConflit avec une autre modification en cours ; relancez la même requête
TEMPORARILY_UNAVAILABLE503Oui, après Retry-AfterLe 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_LARGE413NonLe corps de la requête (ou un morceau) dépasse la taille acceptée par le serveur
REMOTE_TOO_LARGEpar URLNonDans un résultat remote-uploads : le fichier dépasse la limite d’envoi par URL
RATE_LIMITED429Oui, après Retry-AfterTrop de requêtes pour cette catégorie
INTERNAL_ERROR500OuiErreur serveur ; les détails sont journalisés, jamais renvoyés
MAINTENANCE503Oui, après Retry-AfterLes nouveaux envois sont suspendus pour le moment ; les lectures continuent de fonctionner
UPLOADS_TEMPORARILY_UNAVAILABLE503Oui, après Retry-AfterNotre compteur d’envois n’a pas pu être lu ; aucune session n’a été ouverte
SHUTTING_DOWN503Oui, après Retry-AfterLe 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é).

MotifSignification
UNKNOWN_PROVIDERAucun hébergeur ne porte ce slug — vérifiez l’orthographe avec GET /api/v1/providers
PROVIDER_DISABLEDL’hébergeur est désactivé ou en maintenance pour le moment
ACCOUNT_REQUIREDL’hébergeur n’accepte que les envois vers votre propre compte — connectez-le sur la page Connexions
GUEST_UPLOAD_OFFL’hébergeur n’accepte pas d’envois pour le moment et ne peut pas être connecté à un compte
DAILY_LIMIT_REACHEDLa 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_LARGELe fichier dépasse la taille maximale de cet hébergeur
MIME_NOT_ALLOWEDL’hébergeur n’accepte pas ce type de fichier
ALREADY_ATTEMPTEDCet 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.