Archivos

Usa Archivos para gestionar contenido subido, grabado y procesado. Registra un archivo, crea una variante, cópialo al almacenamiento configurado o elimínalo.

Qué haceGestionar un archivo multimedia

Elige este módulo cuandoEl contenido ya existe como archivo y debe subirse, procesarse, copiarse o eliminarse.

Usa otro módulo cuandoUsa Grabaciones si la fuente está en directo; Almacenamientos solo registra el destino externo.

1Añade o busca el archivo2Procesa si es necesario3Reutiliza o exporta

POST /api/files/create

Filtrar endpoints11 endpoints

Antes de empezar

Todos los métodos requieren un x-access-token válido. La instancia necesita espacio local suficiente para la subida y el procesamiento, además de un recurso de Almacenamiento configurado antes de copiar a un almacenamiento de objetos.

Qué puedes hacer

upload y create añaden un recurso multimedia.
getAll, getCount y getById consultan el inventario de archivos.
update modifica los metadatos compatibles del archivo.
copyTo inicia una copia al almacenamiento y getCopyProgress devuelve su progreso.
getStat consulta el estado de procesamiento disponible.
remove o removeByPath eliminan un recurso.

Flujo de ejemplo

Sube un clip corto de prueba y conserva el identificador de archivo devuelto.
Crea la variante necesaria o actualiza sus metadatos.
Inicia copyTo para un destino de archivo configurado.
Consulta getCopyProgress hasta que termine la transferencia.
Comprueba la copia de archivo antes de eliminar el archivo local.

Casos de uso habituales

Mover las grabaciones finalizadas de un evento a un almacenamiento de objetos.
Crear una variante lista para reproducción a partir de un máster subido.
Limpiar contenido local después de completar las comprobaciones de retención y archivo.

Límites y resolución de problemas

Las subidas y copias grandes son asíncronas y pueden fallar por falta de espacio, credenciales, capacidad de red o una ruta no válida. No elimines la fuente hasta comprobar el destino. Trata las rutas y nombres de archivo proporcionados por usuarios como datos no confiables.

Siguientes pasos

Configura Almacenamientos para una retención duradera o Reproductores web si el recurso debe publicarse para su reproducción en el navegador.

Receta de solución REST

Procesar un archivo y copiarlo al almacenamiento

Crea o sube el archivo, supervisa el procesamiento y copia el recurso terminado a un almacenamiento configurado.

Crear el derivadoElige la fuente, el formato y el procesamiento necesario.POST /api/files/create
Supervisar procesamientoEspera a que termine el proceso en segundo plano.POST /api/files/getStat
Copiar al almacenamientoEnvía el archivo terminado a un destino registrado.POST /api/files/copyTo
Verificar la copiaConserva la fuente hasta que la respuesta confirme la finalización.POST /api/files/getCopyProgressById

No elimines la fuente hasta completar procesamiento y copia y verificar el objeto de destino.

POST

/api/files/create

Requiere token de API

Guarda un archivo gestionado en el administrador de medios. Úsalo para convertir una carga en un recurso con nombre, una variante procesada o un archivo reutilizable para reproducción u overlays.

No se limita a guardar metadatos. Si output_format o los ajustes de transcodificación difieren del original, Callaba inicia la conversión necesaria.

Los ejemplos por plantilla muestran cómo conservar un MP4, crear un MP3 o generar un paquete HLS.

Registro directo del recurso

Utiliza este preajuste cuando un archivo mezzanine subido deba convertirse en un recurso gestionado reutilizable sin conversión adicional.

Archivo MP4 subido

Es el flujo más directo del gestor de archivos: primero se sube el archivo y después se registra el recurso con sus metadatos, visibilidad y un registro persistente.

Archivo MP4 subido

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Guardado y conversión

Utiliza este preajuste cuando el recurso almacenado deba convertirse a un formato de audio más sencillo durante el guardado.

Archivo subido a variante MP3

Primero se crea el registro del archivo. Después, el proceso de transcodificación en segundo plano genera el resultado derivado y expone su progreso mediante getStat.

Archivo subido a variante MP3

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage audio extract",
  "file_visibility": "private",
  "file_description": "Audio-only derivative prepared from the uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp3",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "mp3",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Salida segmentada

Utiliza este preajuste cuando el recurso resultante deba generarse como un paquete HLS en lugar de como un único archivo.

Archivo subido a paquete HLS

Resulta útil cuando el archivo gestionado se enviará a un flujo de reproducción o entrega que espera un directorio de salida HLS.

Archivo subido a paquete HLS

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage HLS package",
  "file_visibility": "private",
  "file_description": "Segmented HLS output prepared from an uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "m3u8",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "h264",
    "audio_transcoding": "aac",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Parámetros del cuerpo de la solicitud

Identidad

file_name

string

Etiqueta del panel: Nombre.

Nombre descriptivo del recurso que se guarda en el gestor de archivos.

Ruta del recurso

file_path

string

Etiqueta del panel: Archivo.

Ruta generada por uploadFile o ya conocida por la plataforma.

file_unique_id

string

Identificador de correlación que vincula una carga en curso con el registro de archivo guardado.

Política

file_visibility

string

Etiqueta del panel: Visibilidad.

Define si los flujos posteriores de la interfaz deben tratar el archivo almacenado como público o privado.

file_description

string

Descripción opcional almacenada en la fila de archivos.

Procesamiento

output_format

string

Etiqueta del panel: Formato de salida.

Si el formato solicitado no coincide con la extensión cargada, el backend inicia una conversión en segundo plano.

transcoding

object

Ajustes opcionales de transcodificación para convertir el archivo a otro formato de entrega.

Contexto

module_name

string

Contexto de origen opcional para flujos iniciados desde la interfaz. En la práctica, el gestor suele guardar los registros bajo MODULE_FILES.

Crear archivo

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Respuesta

Identidad

_id / id / file_name

mixed

Identificadores de archivos guardados y el nombre de archivo persistido.

Ruta del recurso

file_path / file_unique_id

mixed

Ubicación del archivo almacenado e identificador de correlación de la carga.

Política

file_visibility / file_description

mixed

Visibilidad guardada y metadatos descriptivos para el activo.

Procesamiento

output_format / transcoding / overlay

mixed

Estado de procesamiento y formato de salida almacenado con la fila de archivos.

Runtime

size_bytes / duration_ms / created

mixed

Métricas calculadas del contenido multimedia y marcas de tiempo gestionadas por el backend.

Respuesta: Crear archivo

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/uploadFile

Requiere token de API

POST

/api/files/getCount

Requiere token de API

POST

/api/files/getAll

Requiere token de API

Devuelve los archivos visibles para el filtro actual. Úsalo como inventario de recursos reutilizables, archivos generados y resultados de grabaciones gestionadas.

Parámetros del cuerpo de la solicitud

limit

integer

Tamaño de página opcional para las consultas de listado del gestor de archivos.

skip

integer

Desplazamiento opcional para recorrer el listado paginado de archivos.

sort

object

Descriptor de ordenación opcional. El panel utiliza { created: -1 } de forma predeterminada.

filter

object

Objeto de filtro opcional. La interfaz lo utiliza para búsquedas de texto libre y para subconjuntos vinculados a una grabación.

Listar archivos

Respuesta

array of file objects

array

El backend devuelve directamente una lista de registros de archivo, sin envolverla en otro objeto.

Respuesta: Listar archivos

JSON

[
  {
    "_id": "680100000000000000000001",
    "id": "680100000000000000000001",
    "file_name": "Main stage mezzanine",
    "file_unique_id": "file_01abc",
    "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
    "file_path": "uploaded/f-01abc-main-stage.mp4",
    "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
    "storage_id": null,
    "file_visibility": "private",
    "module_name": "MODULE_FILES",
    "entity_name": "",
    "entity_id": null,
    "output_format": "mp4",
    "transcoding": {
      "video_transcoding": "Disabled",
      "audio_transcoding": "Disabled",
      "output_audio_bitrate": 128,
      "sample_rate": 44100
    },
    "overlay": {
      "type": "DISABLED"
    },
    "duration_ms": 612000,
    "size_bytes": 832640000,
    "created": "2026-03-24T18:55:00.000Z"
  }
]

POST

/api/files/getById

Requiere token de API

Obtén un archivo guardado mediante su ID. Úsalo cuando un formulario, selector o proceso downstream necesite todos los metadatos y el estado de procesamiento de un recurso.

Parámetros del cuerpo de la solicitud

string

Identificador de la fila de archivos que desea inspeccionar.

Obtener archivo por ID

Respuesta

file object

object

La fila de archivos guardada incluyendo metadatos actuales, métricas de medios y ajustes de procesamiento.

Respuesta: Obtener archivo por ID

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/update

Requiere token de API

Actualiza un recurso gestionado. Los cambios de metadatos son inmediatos; los cambios de formato o transcodificación pueden iniciar un nuevo procesamiento para generar la variante solicitada.

Parámetros del cuerpo de la solicitud

string

Identificador del registro de archivo que se desea actualizar.

file payload fields

mixed

El contrato de actualización reproduce el de create y también puede iniciar una conversión en segundo plano si cambia el formato o la transcodificación.

Actualizar archivo

curl --request POST \
  --url http://localhost/api/files/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine updated",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "id": "680100000000000000000001"
}'

Respuesta

updated file object

object

El backend devuelve el registro de archivo actualizado después de completar el guardado.

Respuesta: Actualizar archivo

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine updated",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/remove

Requiere token de API

POST

/api/files/removeByPath

Requiere token de API

POST

/api/files/copyTo

Requiere token de API

POST

/api/files/getCopyProgressById

Requiere token de API

POST

/api/files/getStat

Requiere token de API

Devuelve el progreso en directo de una conversión o reescritura. Complementa a los métodos de creación y actualización cuando necesitas saber si el archivo sigue procesándose, está a punto de terminar o se ha detenido.

Los campos más útiles son bitrate, FPS, tiempo de salida, velocidad y estado de progreso.

Parámetros del cuerpo de la solicitud

Este método no tiene parámetros

Obtener progreso de procesamiento del archivo

Respuesta

processData[]

array

Estadísticas actuales del proceso de transcodificación en segundo plano que expone el sondeo del gestor de archivos.

processData[].bitrate / bitrate_kbits

mixed

Bitrate actual de FFmpeg para el proceso de reescritura activo.

processData[].fps / out_time_ms / speed / progress

mixed

Campos de progreso que el panel muestra al operador mientras se está convirtiendo un archivo.

Respuesta: Obtener progreso de procesamiento del archivo

JSON

AnteriorGrabaciones SiguienteReproductores web