Sube archivos tú mismo

Desde el panel

Archivos y luego Subir un archivo. Lo que elijas cae en la carpeta que estás viendo y recibes el enlace. Los bytes idénticos se guardan una vez, así que resubir el mismo archivo no cuesta nada.

Crea un token

Tokens y luego Nuevo token. Átalo a un servidor en vez de a todo el espacio de trabajo, para que una clave filtrada no pueda escribir en todas partes. El secreto se muestra una sola vez.

El token de API empieza por fd_live_. No es la clave de agente fda_live_ que va en server.cfg: esa solo conecta el recurso fivedock, y la API de subida no la acepta.

files:write sube, files:read lee, files:delete borra, folders:write crea carpetas, usage:read consulta almacenamiento y tráfico. logs:write es para enviar errores desde una aplicación, no para archivos.

Subir por HTTP

Envía el archivo como multipart/form-data a POST /api/v3/file, la misma dirección que usa Fivemanage. path es la carpeta, que se crea al vuelo, y filename reemplaza el nombre del archivo de la parte.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=/branding"

{
  "status": "ok",
  "data": { "id": "8Kq2nR4t", "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png" },
  "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
  "filename": "logo.png",
  "mime_type": "image/png",
  "size": 48213,
  "fivedock": {
    "fileUrl": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
    "deduplicated": false,
    "folder": "/branding"
  }
}

url es el enlace de la CDN, listo para pegar en una pantalla de carga o en un embed de Discord, y funciona en cuanto llega la respuesta. fivedock.deduplicated te dice que esos bytes ya estaban guardados, así que no se facturó nada nuevo. La respuesta de arriba está recortada.

Archivos con nombre y enlaces estables

Dale a un archivo una clave, como items/burger.png, y se sirve en un enlace que nunca cambia: https://cdn.fivedock.dev/o/my-city/items/burger.png, donde my-city es el nombre corto de tu espacio de trabajo. Si vuelves a subir con la misma clave, se reemplaza el archivo detrás del enlace, así que un icono de inventario o una imagen de pantalla de carga cambian sin tocar ningún script ni la base de datos.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "key=items/burger.png"

# served at https://cdn.fivedock.dev/o/my-city/items/burger.png
# run it again with a new burger.png and the same link shows the new file

Las claves salen del campo key de la API de subida, de «Mantener nombres de archivo» en el panel, de los archivos comprimidos y del endpoint S3, donde un objeto en s3://my-city/items/burger.png es el archivo con clave items/burger.png. En el panel, un archivo con clave aparece en la carpeta de su clave, aquí /items.

El archivo que reemplazas se conserva 7 días y después se purga. Los enlaces con clave se guardan en caché 5 minutos, así que los jugadores ven la nueva versión en unos 5 minutos. Cada archivo conserva además su propio enlace /f/, cuyo contenido nunca cambia.

Las claves que salen de nombres de archivo se limpian por ti: los espacios pasan a ser - y cualquier otro carácter que una clave no admite pasa a ser _. Una clave que mandas tú a la API ya tiene que cumplir las reglas, o se rechaza.

Sube una carpeta entera como .zip o .rar

Suelta un .zip o un .rar en la zona de subida del panel, o envíalo a POST /api/v3/file/archive, y se guarda cada archivo que contiene. «Mantener nombres de archivo» está activado por defecto para archivos comprimidos, así que burger.png descomprimido en items recibe el enlace estable …/o/my-city/items/burger.png. Las carpetas del comprimido se conservan.

curl -X POST https://api.fivedock.dev/api/v3/file/archive \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=items"

Un archivo comprimido puede pesar hasta 512 MiB, con 5000 archivos como máximo y 4 GiB descomprimido. Los archivos que no podemos guardar, como los de un tipo que no aceptamos o los protegidos con contraseña, vuelven en una lista con el motivo. Para conjuntos más grandes, sincroniza por el endpoint S3.

Desde tu propio uploader en HTML y JS

Nunca pongas un token en JavaScript del navegador: cualquiera que abra la página lo lee y sube a tu espacio de trabajo. Recibe el archivo en tu propio servidor y guarda el token ahí.

// your server, never the browser: the token stays here
app.post('/upload', upload.single('file'), async (req, res) => {
  const body = new FormData();
  body.append('file', new Blob([req.file.buffer]), req.file.originalname);
  body.append('path', '/player-shots');

  const answer = await fetch('https://api.fivedock.dev/api/v3/file', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.FIVEDOCK_TOKEN}` },
    body,
  });
  res.json(await answer.json());
});

// your page talks to your server, which holds the token
const body = new FormData();
body.append('file', input.files[0]);

const answer = await fetch('/upload', { method: 'POST', body });
const file = await answer.json();
image.src = file.url;

Si el archivo nace en un navegador o en una página NUI de FiveM, tu servidor puede crear en su lugar un enlace de subida de un solo uso y pasar ese enlace. El navegador sube directo a FiveDock y nunca ve el token.

Si lo que quieres es que los jugadores te manden archivos sin escribir código, usa un portal de subida: es una página pública, limitada por dirección, con tope diario y moderación por delante.

El endpoint compatible con S3

El mismo token también es una credencial S3, así que rclone, la CLI de aws y casi cualquier herramienta de copia pueden escribir ahí. Usa direccionamiento path-style.

rclone config create fivedock s3 \
  provider=Other \
  endpoint=https://s3.fivedock.dev \
  access_key_id=AKFD… \
  secret_access_key=… \
  force_path_style=true \
  region=auto

rclone copy ./branding fivedock:my-city/branding

aws --endpoint-url https://s3.fivedock.dev \
  s3 cp logo.png s3://my-city/branding/logo.png

Cada objeto que subes es un archivo con clave, así que s3://my-city/branding/logo.png se sirve en https://cdn.fivedock.dev/o/my-city/branding/logo.png.

Carpetas y retención

Crea carpetas en el panel y mueve archivos entre ellas. La clave de un archivo se mueve con él: items/a.png movido a /icons pasa a ser icons/a.png, y si esa clave ya está ocupada, se rechaza el movimiento de ese archivo. La lista de archivos tiene vista de lista y de cuadrícula, búsqueda por nombre y filtros por tipo y por fecha de subida: últimas 24 horas, 7 días, 30 días o desde siempre.

Cada carpeta tiene una regla de retención que decide cuándo se borran sus archivos.

Servir lo que subiste

Cada archivo recibe un enlace de CDN que funciona en cuanto la subida responde. Los archivos se aprueban al subirse; si moderación retira uno más tarde, su enlace responde 404. En Ajustes limitas con una lista qué sitios pueden incrustar tus archivos.