Saltar al contenido

Documentación de la API

Sube un archivo una vez, envíalo a los hosts de archivos que elijas y recibe un solo enlace para compartir, todo desde tu propio código.

Actualizado

Una API REST versionada: sube un archivo por partes, envíalo a los hosts que elijas y todas las copias se reúnen en una sola página para compartir con estado en vivo.

URL base
https://api.mirroruploadx.com/api/v1
Autenticación
x-api-key: mux_…
  1. 1Abre una sesión

    POST /api/v1/upload-sessions

    filename + sizeBytes; obtienes sessionId y chunkSize

  2. 2Envía las partes

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

    bytes sin procesar, en orden; la respuesta que completa el archivo incluye fileId

  3. 3Distribuye

    POST /api/v1/mirror-tasks/start

    fileId + providerSlugs; luego consulta el trabajo

Crea una clave en la página Claves de API. Guía completa con código en Subir y distribuir.

Autenticación

Crea una clave en la página Claves de API de tu panel. La clave completa (empieza por mux_) solo se muestra una vez, así que guárdala de inmediato. Envíala en la cabecera x-api-key en cada solicitud; Authorization: Bearer mux_… se acepta de la misma forma para los clientes que solo trabajan con tokens bearer.

Las claves tienen permisos: una clave solo llega a los endpoints que cubren sus permisos, y una llamada con el permiso incorrecto devuelve 403 INSUFFICIENT_SCOPE con el permiso necesario en el mensaje. Los ajustes de la cuenta, la gestión de claves y los webhooks no son accesibles con una clave de API (API_KEY_NOT_ALLOWED).

PermisoDa acceso a
upload:writeSesiones de subida (crear, partes, completar, cancelar), tu cuota de subida, retener o cambiar la distribución automática de una subida (hold-distribution, distribution-intent), subidas desde URL remotas, iniciar la distribución
file:readListado de archivos, detalles de archivos, estado de espejos y trabajos
file:writeAjustes de compartir de un archivo
file:deleteEliminar un archivo y sus espejos

Endpoints

Todo lo que una clave de API puede alcanzar, además de los endpoints públicos que no necesitan clave. Cuando la columna de permisos indica dos permisos, basta con uno de ellos. Los esquemas de solicitud y respuesta de cada uno están en la referencia de la API.

MétodoRutaPermisoQué hace
POST/api/v1/upload-sessionsupload:writeAbre una sesión de subida (opcionalmente con un plan de distribución)
PATCH/api/v1/upload-sessions/{id}/chunksupload:writeEnvía la siguiente parte de bytes
HEAD/api/v1/upload-sessions/{id}upload:writeDónde reanudar: la cabecera Upload-Offset
GET/api/v1/upload-sessions/{id}upload:writefile:readEstado de la sesión: bytes recibidos, fileId, finalizable
GET/api/v1/upload-sessions/quotaupload:writefile:readTus límites de subida, uso y sesiones sin terminar
POST/api/v1/upload-sessions/{id}/completeupload:writeTermina una subida cuya respuesta final se perdió (se puede reintentar sin riesgo)
POST/api/v1/upload-sessions/{id}/hold-distributionupload:writeImpide que una distribución diferida empiece sola
PUT/api/v1/upload-sessions/{id}/distribution-intentupload:writeReemplaza el plan de distribución de una subida
DELETE/api/v1/upload-sessions/{id}upload:writeCancela una subida sin terminar y libera su espacio
POST/api/v1/remote-uploadsupload:writeDescarga archivos desde URL http(s) a tu cuenta
POST/api/v1/mirror-tasks/startupload:writeEnvía un archivo a los hosts que elijas
GET/api/v1/mirror-tasks/{uploadJobId}upload:writefile:readEstado del trabajo, cada host y el enlace para compartir (shareTakenDown indica una página retirada)
GET/api/v1/filesfile:readLista tus archivos (paginación por cursor, búsqueda, filtros)
GET/api/v1/files/{id}file:readUn archivo: tamaño, suma de verificación, trabajo, ajustes de compartir, estadísticas
GET/api/v1/files/{id}/mirrorsfile:readTodas las copias de un archivo: host, enlace, estado, clics
PATCH/api/v1/files/{id}/sharefile:writeContraseña, caducidad y visibilidad del enlace compartido
DELETE/api/v1/files/{id}file:deleteElimina un archivo y (por defecto) sus copias en los hosts
GET/api/v1/platformninguno (público)Límites actuales: archivo más grande, hosts por archivo, topes de subida desde URL
GET/api/v1/providersninguno (público)El catálogo de hosts, con los slugs que envías en providerSlugs
GET/api/v1/providers/statusninguno (público)Éxito de subida medido por host
GET/api/v1/stats/publicninguno (público)Totales de la plataforma en los últimos 30 días: archivos, espejos en línea, tasa de éxito

Subir un archivo y distribuirlo

  1. Abre una sesión con POST /api/v1/upload-sessions. filename y sizeBytes (la longitud exacta en bytes) son obligatorios; mimeType y un idempotencyKey UUID son opcionales: repetir una solicitud con la misma clave devuelve la sesión existente en lugar de abrir una segunda. La respuesta incluye data.sessionId (no id) y data.chunkSize.
  2. Envía los bytes con PATCH /api/v1/upload-sessions/{id}/chunks: bytes sin procesar, tipo de contenido application/offset+octet-stream y la posición inicial de la parte en la cabecera upload-offset. Las partes van en orden, o hasta maxChunksAhead partes por delante; si envías en orden, usa data.uploadedBytes de cada respuesta como el siguiente desplazamiento. Envía partes de chunkSize bytes; todas las partes excepto la última deben tener al menos 5 MiB, y una subida puede tener como máximo 10 000 partes. La respuesta que completa el archivo incluye data.fileId. Para ganar velocidad, puedes tener 2 o 3 partes del mismo archivo en curso a la vez. Envía la primera parte sola; su respuesta indica el valor real de data.maxChunksAhead (4 si la primera parte era un fragmento completo de chunkSize, 0 = solo en orden). Si la primera parte era un fragmento completo de chunkSize, todas las partes posteriores también deben serlo (en orden o por delante): empiezan en un múltiplo de chunkSize y miden exactamente chunkSize bytes (la última: el resto del archivo). Una parte enviada por delante de uploadedBytes debe ser un fragmento así y empezar como máximo data.maxChunksAhead partes por delante; de lo contrario, recibe 409 CHUNK_MISALIGNED o 409 CHUNK_OUT_OF_WINDOW. uploadedBytes solo cuenta los bytes recibidos sin huecos, y la parte que complete el archivo, sea cual sea, recibe la respuesta con fileId. Volver a enviar una parte que ya llegó es un éxito inofensivo.
  3. Distribuye con POST /api/v1/mirror-tasks/start: fileId y providerSlugs son obligatorios (los slugs se obtienen de GET /api/v1/providers). Opcionales: minSuccess (por defecto 1: cuántos hosts deben aceptar el archivo para que el trabajo no falle; solo es completed cuando todos los hosts lo aceptaron, si no, partially_completed. Los hosts que rechazan este tipo de archivo no cuentan), sharePassword, expiresInDays o expiresAt. La respuesta incluye uploadJobId, taskCount, shareSlug, alreadyStarted y skipped[]: un host que no puede aceptar este archivo se omite, no falla, así que lee skipped[] (los motivos se enumeran más abajo). Ahora mismo, un archivo puede ir como máximo a 50 hosts.
  4. Sigue su progreso con GET /api/v1/mirror-tasks/{uploadJobId} cada pocos segundos hasta que data.terminal sea true. La respuesta enumera cada host en tasks[] (providerSlug, status, mirrorUrl, errorCode) y el enlace para compartir en data.shareUrl. data.shareTakenDown es true cuando esa página para compartir se retiró y ya no se abre.

El archivo más grande que se acepta ahora mismo es de 5,00 GB.

bash, requiere 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

Respuestas de ejemplo

Abrir una sesión responde 201. Cada parte salvo la última responde { uploadedBytes, completed: false, expiresAt }; la última incluye el archivo. distribution solo aparece si pasaste un plan al abrir la sesión (ver más abajo).

POST /upload-sessions → 201
{
  "success": true,
  "data": {
    "sessionId": "…",
    "uploadedBytes": 0,
    "chunkSize": 8388608,
    "maxChunksAhead": 0
  }
}
PATCH …/chunks (completa el archivo) → 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 primer start correcto responde 202; volver a llamarlo para un trabajo que ya está en curso responde 200 con alreadyStarted: true. Cuando el enlace de un host se mantiene privado por política, mirrorUrl es null y mirrorHidden es true; la página para compartir sigue mostrándolo.

Ahórrate la segunda llamada

Pasa distribution al abrir la sesión y el servidor empezará a distribuir en cuanto el archivo esté completo. Comprueba data.distribution en la respuesta que completa el archivo: started: true significa que el trabajo está en cola (uploadJobId, shareSlug). Con started: false y deferred: true, todavía no hay nada en cola a propósito; ver más abajo. Con started: false y sin deferred, la subida se completó pero la distribución no pudo empezar (error indica por qué): llama a POST /api/v1/mirror-tasks/start con el fileId. Un error junto con deferred: true significa un fallo temporal (por ejemplo, todos los hosts están ocupados o en mantenimiento): no llames a start ni vuelvas a subir el archivo; el propio servidor reintentará iniciar la distribución a partir de autoStartAt (hasta 5 intentos). Llama a hold-distribution para detenerlo.

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

Añade deferred: true a distribution para tener un periodo de gracia: la respuesta final es { started: false, deferred: true, autoStartAt } y el propio servidor inicia la distribución en autoStartAt (unos 2 minutos después), salvo que llames antes a start. Para detener el inicio automático, llama a POST /api/v1/upload-sessions/{id}/hold-distribution (sin cuerpo; autoStartAt pasa a null y la inicias tú). Para cambiar el plan, llama a PUT /api/v1/upload-sessions/{id}/distribution-intent con los mismos campos que distribution (providerSlugs, minSuccess, expiresInDays, sharePassword): reemplaza el plan y levanta la retención, y una vez terminada la subida el inicio automático se aplaza al menos 2 minutos después de la llamada. Si la distribución ya ha empezado, ambas responden 200 y distribution-intent indica alreadyStarted: true.

Inicia la distribución en menos de 30 minutos. Cuando termina una subida y no se inicia ninguna distribución, nuestra copia del archivo se elimina al cabo de 30 minutos (si hay un plan de distribución esperando a que los hosts estén disponibles, como máximo al cabo de 72 horas; las subidas desde URL remotas no se ven afectadas). A partir de entonces, start y distribution-intent responden 409 SOURCE_GONE y hay que volver a subir el archivo.

Si se pierde la respuesta final

Llama a GET /api/v1/upload-sessions/{id}: un fileId significa que el archivo existe; finalizable: true significa que llegaron todos los bytes y POST /api/v1/upload-sessions/{id}/complete lo termina. Esa llamada se puede reintentar sin riesgo y nunca crea un segundo archivo. Un desplazamiento que no coincide recibe 409 CHUNK_OFFSET_CONFLICT: envía HEAD a la sesión y reanuda desde su cabecera Upload-Offset. Volver a llamar a start para un trabajo en curso no es un error: recibes 200 con alreadyStarted: true.

Subir desde una URL

POST /api/v1/remote-uploads recibe { "urls": [...] } y descarga cada archivo por ti (permiso upload:write). Solo se descargan enlaces http y https, las direcciones de redes privadas se rechazan y solo se sigue un número limitado de redirecciones. Una solicitud admite como máximo 10 URL (lo devuelve GET /api/v1/platform); divide las listas más largas.

El límite de tamaño por archivo depende del origen. Cuando indica el tamaño del archivo, cada archivo puede ocupar hasta 5,00 GB (limits.remoteUploadPassthroughMaxBytes); cuando no lo indica, hasta 100,0 MB (limits.remoteUploadMaxBytes). El nombre del archivo se toma de la cabecera Content-Disposition del origen cuando la envía; a un nombre sin extensión se le añade una según el tipo del archivo.

La solicitud espera mientras se descargan los archivos. Si la conexión se corta antes, el archivo llega igualmente a tu cuenta: encuéntralo con GET /api/v1/files. Después, cada fileId se distribuye con POST /api/v1/mirror-tasks/start, como se explica arriba.

Cuando el almacenamiento temporal está lleno, toda la solicitud recibe 503 TEMPORARILY_UNAVAILABLE con details.reason: "staging_full" y una cabecera Retry-After. Si solo una URL no cabe, esa entrada de results[] tiene ok: false y el mismo código; un resultado por URL no tiene cabecera, así que la espera en segundos está en 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.

Gestionar archivos

Tus archivos permanecen en tu cuenta después de la subida. Lístalos con GET /api/v1/files (limit hasta 100; pasa el nextCursor de la respuesta como cursor para la página siguiente; q busca por nombre). GET /api/v1/files/{id} devuelve un archivo con su trabajo, sus ajustes de compartir y sus estadísticas de visitas; GET /api/v1/files/{id}/mirrors enumera cada copia con su enlace, su estado y sus clics.

PATCH /api/v1/files/{id}/share (permiso file:write) cambia la página para compartir: password (de 4 a 128 caracteres; null la quita; nunca se devuelve, solo passwordProtected), expiresAt (fecha ISO, null para que no caduque), visibility y hideDownloadCount. Envía solo los campos que quieras cambiar. DELETE /api/v1/files/{id} (permiso file:delete) elimina el archivo y pone en cola la eliminación de sus copias en los hosts; añade ?keepMirrors=true para conservarlas. Algunos hosts no permiten borrar, así que puede quedar una copia allí.

bash, requiere jq; define 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

Añade un endpoint en la página Webhooks. La URL debe usar https://; su secreto de firma (whsec_…) se muestra una sola vez, al crearlo. Un endpoint sin eventos seleccionados los recibe todos.

EventoCuándo
upload.completedTodos los hosts aceptaron el archivo, y al menos minSuccess lo hicieron; no cuentan los hosts que rechazaron este archivo (rejected) ni los que se cancelaron
upload.partially_completedAl menos minSuccess hosts aceptaron el archivo, pero al menos otro host falló
upload.failedMenos de minSuccess hosts aceptaron el archivo (minSuccess 0 cuenta como 1)
upload.quarantinedEl análisis de malware marcó el archivo (solo cuando el análisis está activado)
provider.upload_succeededUn host aceptó el archivo; se envía una vez por host
provider.upload_failedUn host se dio por vencido con el archivo; se envía una vez por host
webhook.testPulsaste Probar en la página Webhooks

Cada entrega es un POST con un cuerpo JSON y las cabeceras X-MUX-Event y X-MUX-Signature. Cualquier respuesta 2xx en 10 segundos cuenta como entregada; las redirecciones no se siguen. Una entrega fallida (error de red, tiempo de espera agotado, 408, 425, 429 o 5xx) se reintenta tras 1, 5 y 30 minutos con el mismo cuerpo; los demás 4xx y las redirecciones no. Cada intento incluye X-MUX-Delivery-Attempt (1–4) y una firma nueva, así que elimina los duplicados a partir del cuerpo. El orden de entrega no está garantizado (un evento reintentado puede llegar después de uno más reciente); compara data y createdAt antes de actuar. Usa GET /api/v1/mirror-tasks/{uploadJobId} para ponerte al día. Tras 15 entregas seguidas cuyo último intento falló, o una hora de fallos sin un solo éxito, el endpoint se pone en pausa; al reactivarlo, el recuento se reinicia. Una entrega webhook.test (el botón Probar) se envía una sola vez, con X-MUX-Delivery-Attempt: 1, y nunca se reintenta.

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

Los eventos upload.* incluyen uploadJobId, fileId y status; provider.upload_failed incluye errorCode en lugar de mirrorUrl.

Verificar la firma

La cabecera tiene este aspecto: t=1727265600,v1=5f2b…. t es el momento de la firma en segundos Unix y v1 es el HMAC-SHA256 en hexadecimal de <t>.<raw body>, con el secreto de tu endpoint como clave. Calcula el hash de los bytes sin procesar exactamente como se recibieron, compara en tiempo constante y rechaza las marcas de tiempo con más de 5 minutos de antigüedad.

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

Límites de solicitudes

Los límites se cuentan por clave de API, no por dirección IP. Cada respuesta de un endpoint limitado incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos desde epoch). Si superas el límite, se devuelve 429 RATE_LIMITED con una cabecera Retry-After: espera esa cantidad de segundos. La subida de partes tiene un margen amplio; los límites estrictos están en la apertura de sesiones y el inicio de distribuciones.

GrupoEndpointsPor clavePeriodo
Inicio de subidasPOST /api/v1/upload-sessionsPOST /api/v1/upload-sessions/{id}/completeDELETE /api/v1/upload-sessions/{id}601 minuto
Subida de partesPATCH /api/v1/upload-sessions/{id}/chunks6001 minuto
Consulta del progresoGET /api/v1/upload-sessions/{id}HEAD /api/v1/upload-sessions/{id}GET /api/v1/upload-sessions/quotaGET /api/v1/mirror-tasks/{uploadJobId}6001 minuto
Ajustes de distribución de una subidaPOST /api/v1/upload-sessions/{id}/hold-distributionPUT /api/v1/upload-sessions/{id}/distribution-intent3001 minuto
Inicio de la distribuciónPOST /api/v1/mirror-tasks/start301 minuto
Subidas remotas (URL)POST /api/v1/remote-uploads2010 minutos
Lectura de archivosGET /api/v1/filesGET /api/v1/files/{id}GET /api/v1/files/{id}/mirrors3001 minuto
Modificación de archivosPATCH /api/v1/files/{id}/shareDELETE /api/v1/files/{id}601 minuto
Catálogo públicoGET /api/v1/platformGET /api/v1/providersGET /api/v1/providers/statusGET /api/v1/stats/public3001 minuto

Estas son las cifras predeterminadas. El operador puede cambiarlas, así que las cabeceras anteriores son siempre la fuente fiable. Las cifras exactas de tus claves, y cuánto has usado de cada una ahora mismo, están en la página Claves de API. Las solicitudes sin clave se cuentan por dirección IP y tienen márgenes menores para el inicio de subidas (10 en lugar de 60), la subida de partes (300 en lugar de 600), la consulta del progreso (300 en lugar de 600), los ajustes de distribución de una subida (60 en lugar de 300), el inicio de la distribución (10 en lugar de 30) y el mismo margen para las subidas remotas (URL) y el catálogo público. Lectura de archivos y la modificación de archivos: siempre se necesita una clave.

Errores

Las respuestas correctas tienen la forma { "success": true, "data": … }. Los errores usan una única forma, junto al estado HTTP. code es estable: toma decisiones según él; message es para personas y puede cambiar. details se añade cuando hay más contexto, retryable indica si repetir la misma solicitud puede servir de algo y requestId nos ayuda a encontrar tu solicitud si contactas con soporte.

Error
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint needs one of these API key scopes: upload:write.",
    "requestId": "…",
    "retryable": false
  }
}
CódigoHTTP¿Reintentar?Significado
NO_TOKEN401NoNo se envió ninguna clave de API
INVALID_API_KEY401NoLa clave es incorrecta o está revocada
INSUFFICIENT_SCOPE403NoLa clave no tiene el permiso que necesita este endpoint
API_KEY_NOT_ALLOWED403NoEste endpoint no se puede usar con una clave de API
EMAIL_NOT_VERIFIED403NoPrimero verifica el correo de la cuenta; las sesiones abiertas siguen funcionando
SESSION_REVOKED401NoLa sesión se cerró (restablecimiento o cambio de contraseña, cierre de sesión); vuelve a iniciar sesión
ACCOUNT_INACTIVE403NoLa cuenta está suspendida o programada para su eliminación
ACCOUNT_DISABLED401 / 409NoLa cuenta se suspendió: 401 en la comprobación de la clave, 409 si cambió mientras se procesaba la solicitud
ACCOUNT_PENDING_DELETION409NoLa cuenta pasó a estar programada para su eliminación mientras se procesaba la solicitud; no se inicia nada nuevo
VALIDATION_ERROR400NoEl cuerpo o un parámetro no es válido; consulta details
FILE_REJECTED400NoEl tipo o el tamaño del archivo no está permitido; details.reason indica cuál
TOO_MANY_MIRRORS400NoMás hosts de los que puede tener un archivo
NO_CONNECTED_PROVIDERS400NoTodos los hosts seleccionados necesitan tu propia cuenta y ninguno está conectado
PROVIDER_REJECTS_FILE400NoNingún host seleccionado acepta este tipo o tamaño de archivo
NO_AVAILABLE_PROVIDERS400NoNinguno de los hosts seleccionados acepta subidas ahora mismo; elige otros o inténtalo más tarde. `details.waiting` enumera los hosts solo pausados (por ejemplo, un límite diario que se levanta en 24 horas): para ellos reintentar más tarde funciona aunque `retryable` sea false
NO_VALID_PROVIDERS400NoNingún valor de providerSlugs coincide con un host activado; consulta GET /api/v1/providers
INVALID_JOB_STATE400NoEl trabajo no se puede iniciar en su estado actual
JOB_NOT_READY400NoEl archivo aún no tiene un trabajo de distribución
FILE_TOO_LARGE_FOR_UPLOAD400NoEl archivo no cabe en 10 000 partes del tamaño de parte de la sesión; details.limitBytes
MISSING_OFFSET400NoSe envió una parte sin una cabecera upload-offset numérica
RAW_BODY_REQUIRED400NoEl cuerpo de una parte debe ser bytes sin procesar con content-type application/offset+octet-stream
TOO_MANY_URLS400NoMás URL de las permitidas en una solicitud remote-uploads
FILE_NOT_FOUND404NoEse archivo no existe en tu cuenta (o se eliminó)
JOB_NOT_FOUND404NoEse trabajo de distribución no existe en tu cuenta
SESSION_NOT_FOUND404NoEsa sesión de subida no existe en tu cuenta
SHARE_NOT_FOUND404NoEl archivo aún no tiene página para compartir
QUOTA_EXCEEDED409NoUn límite de subidas diario o simultáneo; details.retryAt indica cuándo se libera
CHUNK_OFFSET_CONFLICT409Noupload-offset no coincide con los bytes recibidos; reanuda a partir de HEAD
CHUNK_TOO_SMALL409NoUna parte que no es la última mide menos de 5 MiB
CHUNK_TOO_MANY_PARTS409NoMás de 10 000 partes; envía partes más grandes
CHUNK_MISALIGNED409NoLa parte no es un fragmento completo de chunkSize que empiece en un múltiplo de chunkSize: es obligatorio para una parte enviada por delante y, si la primera parte era un fragmento completo de chunkSize, también para todas las posteriores (en orden o por delante); o se envió una parte por delante en una sesión que solo acepta partes en orden
CHUNK_OUT_OF_WINDOW409NoUna parte empieza más de maxChunksAhead partes por delante de uploadedBytes, o simplemente por delante antes de que se haya aceptado la primera parte; vuelve a enviarla después de las anteriores
CHUNK_EXCEEDS_DECLARED_SIZE409NoLa parte supera el tamaño de archivo declarado al crear la sesión
CHUNK_EMPTY409NoLa parte no tiene bytes
CHUNK_NOT_RECEIVABLE409NoLa sesión ya no acepta datos (se completó, se canceló o caducó); abre una nueva
SESSION_EXPIRED409NoLa sesión de subida caducó; abre una nueva
SESSION_NOT_RECEIVABLE409NoLa sesión se canceló o caducó y no admite más cambios
SESSION_COMPLETED409NoLa subida ya terminó; elimina el archivo en su lugar
UPLOAD_INCOMPLETE409NoNo han llegado todos los bytes; envía primero las partes restantes (details incluye los recuentos)
IDEMPOTENCY_KEY_CONFLICT409NoEste idempotencyKey ya lo usa otra subida; usa una clave única por subida
SOURCE_GONE409NoNuestra copia del archivo ya se eliminó, así que no se puede enviar a los hosts en los que aún no se ha intentado; vuelve a subirlo para esos. Nuestra copia se elimina en cuanto termina un trabajo de distribución (completado, completado parcialmente o fallido), y una subida cuya distribución nunca se inicia se elimina 30 minutos después de terminar (hasta 72 horas cuando su plan de distribución sigue esperando a los hosts; salvo las subidas desde URL remotas). Volver a llamar a mirror-tasks/start para un trabajo terminado solo con hosts ya intentados se limita a aplicar los ajustes de compartir (alreadyStarted: true)
JOB_NOT_DISTRIBUTABLE409NoEl trabajo falló, se canceló o está en un estado que ya no se puede distribuir
SHARE_TAKEN_DOWN409NoLa página para compartir del archivo se retiró, así que no se puede enviar a más hosts
FINALIZING409SíOtra solicitud está ensamblando el archivo; vuelve a preguntar en unos segundos
CONFLICT409SíCoincidió con otro cambio en curso; reintenta la misma solicitud
TEMPORARILY_UNAVAILABLE503Sí, tras Retry-AfterEl servidor está ocupado ahora mismo; reintenta tras el plazo de Retry-After. details.reason "staging_full": el almacenamiento temporal está lleno y no se aceptó ninguna subida nueva (Retry-After de unos 10 minutos); las subidas ya en curso siguen funcionando
PAYLOAD_TOO_LARGE413NoEl cuerpo de la solicitud (o una parte) es más grande de lo que acepta el servidor
REMOTE_TOO_LARGEpor URLNoEn un resultado de remote-uploads: el archivo supera el límite de subida desde URL
RATE_LIMITED429Sí, tras Retry-AfterDemasiadas solicitudes para este grupo
INTERNAL_ERROR500SíError del servidor; los detalles se registran, nunca se devuelven
MAINTENANCE503Sí, tras Retry-AfterLas nuevas subidas están en pausa por ahora; las lecturas siguen funcionando
UPLOADS_TEMPORARILY_UNAVAILABLE503Sí, tras Retry-AfterNo se pudo leer nuestro contador de subidas; no se abrió ninguna sesión
SHUTTING_DOWN503Sí, tras Retry-AfterEl servidor se está reiniciando (Retry-After de 5 segundos); espera y envía la misma solicitud de nuevo: no se procesó nada

Por qué se omitió un host

No son errores: llegan en skipped[].reason de un start correcto (y de distribution en la respuesta que completa el archivo). Los demás hosts reciben el archivo igualmente. La llamada solo falla cuando ningún host seleccionado puede aceptarlo: PROVIDER_REJECTS_FILE (ninguno acepta este archivo), NO_CONNECTED_PROVIDERS (todos necesitan tu propia cuenta), NO_AVAILABLE_PROVIDERS (ninguno acepta subidas ahora mismo) o NO_VALID_PROVIDERS (ningún slug coincide con un host activado).

MotivoSignificado
UNKNOWN_PROVIDERNo existe ningún host con este slug: comprueba cómo se escribe en GET /api/v1/providers
PROVIDER_DISABLEDEl host está desactivado o en mantenimiento ahora mismo
ACCOUNT_REQUIREDEl host solo acepta subidas a tu propia cuenta: conéctalo en la página Conexiones
GUEST_UPLOAD_OFFEl host no acepta subidas ahora mismo y no se puede conectar a una cuenta
DAILY_LIMIT_REACHEDEl límite diario del host para subidas sin cuenta está agotado por ahora (hasta 24 h): conecta tu propia cuenta para poder subir igualmente
FILE_TOO_LARGEEl archivo supera el límite de tamaño de este host
MIME_NOT_ALLOWEDEl host no acepta este tipo de archivo
ALREADY_ATTEMPTEDEste host ya se intentó para este archivo, así que no se vuelve a enviar allí

La referencia de la API enumera los códigos que puede devolver cada endpoint.