> This page is for Plataforma, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Heredado: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Vínculos multimedia Frame.io almacena y procesa archivos cargados en los Projects: imágenes, vídeos, PDF, etc. Cuando recupera un archivo mediante la API, la respuesta base incluye metadatos principales como el nombre del archivo, el estado y un `view_url` para abrirlo en la aplicación Frame.io. Para acceder al contenido real del archivo, como el original, una previsualización o representaciones con distintos niveles de calidad, se usan **includes**. Esta guía explica los includes de vínculos multimedia disponibles en los extremos **List Files** y **Get File**, qué devuelve cada uno y cuándo debe usarse. ## ¿Qué son los includes? Los includes son campos opcionales que se pueden solicitar junto con una respuesta de archivo. De forma predeterminada, la API solo devuelve los metadatos principales del archivo: nombre, estado, tipo, marcas de tiempo y `view_url`. Los includes permiten solicitar datos adicionales solo cuando se necesitan, lo que mantiene las respuestas ligeras cuando no hace falta todo. ### Cómo añadir includes Pase una lista separada por comas de nombres de `include` como parámetro de consulta include en cualquier solicitud **Get File** o **List Files**: **`Un solo include`** ```bash title="Un solo include" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` **`Varios includes`** ```bash title="Varios includes" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` **`Includes en List Files`** ```bash title="Includes en List Files" GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail ``` Los includes funcionan del mismo modo en los puntos finales de archivo único y de lista. Cuando se usan en List Files, los includes se resuelven para todos los archivos de la respuesta. ### Ejemplos de SDK **`SDK para Python`** ```python title="SDK para Python" import frameio client = frameio.Frameio(auth="") file = client.files.get( file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", include=["media_links.thumbnail", "media_links.original"] ) print(file.media_links.thumbnail.url) ``` **`SDK para TypeScript`** ```typescript title="SDK para TypeScript" import Frameio from "frameio"; const client = new Frameio({ auth: "" }); const file = await client.files.get("93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", { include: ["media_links.thumbnail", "media_links.original"], }); console.log(file.media_links?.thumbnail?.url); ``` Los includes que no se soliciten se omiten por completo de la respuesta. ## Información general de includes de vínculos multimedia #### media\_links.original Archivo original cargado, exactamente tal como se cargó #### media\_links.thumbnail Imagen de previsualización PNG para visualización #### media\_links.high\_quality Mejor representación procesada disponible #### media\_links.efficient Representación más pequeña disponible para casos de uso con poco ancho de banda #### media\_links.video\_h264\_180 Transcodificación de vídeo H.264 de baja resolución a 180p para streaming y reproducción #### media\_links.scrub\_sheet Hoja de sprites WebP con miniaturas de fotogramas de vídeo para crear IU de barrido ## media\_links.original Devuelve URL firmadas que apuntan al **archivo original exactamente tal como se cargó**, sin procesamiento ni conversión. ### Campos | Campo | Tipo | Descripción | | | -------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL firmada que fuerza la descarga de un archivo (`Content-Disposition: attachment`) | | `inline_url` | string \\ | null | URL firmada que abre el archivo directamente en el explorador (`Content-Disposition: inline; filename=`) | ### Cuándo usarlo Use `media_links.original` cuando necesite el archivo de origen, por ejemplo, para permitir que un usuario descargue el archivo MOV, MP4, MXF, AVI, PSD, PNG o TIFF original, o para pasar los bytes originales a otro sistema. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "original": { "download_url": "https://s3.amazonaws.com/...", "inline_url": "https://s3.amazonaws.com/..." } } } } ``` > **Warning** > > Estas URL son **URL de S3 firmadas temporales** y caducan. No las almacene ni las guarde en caché; solicite una URL nueva cada vez que necesite una. ## media\_links.thumbnail Devuelve una **imagen de vista previa PNG** del activo, limitada a 540 px de alto. Es una representación procesada, no el archivo original, y es posible que se apliquen marcas de agua en función de la configuración de la cuenta. ### Campos | Campo | Tipo | Descripción | | | -------------- | --------- | ----------- | ------------------------------------------------------------------------------------ | | `download_url` | string \\ | null | URL firmada que fuerza la descarga de la miniatura PNG | | `url` | string \\ | null | URL firmada que sirve la miniatura PNG en línea sin encabezado `Content-Disposition` | ### Cuándo usarlo Use `media_links.thumbnail` cuando necesite **mostrar una vista previa** del activo, por ejemplo, en una vista de cuadrícula, una galería o un selector de archivos. Se carga más rápido que el original y siempre tiene formato PNG seguro para web. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "thumbnail": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.high\_quality Devuelve una URL de descarga para la **mejor representación procesada disponible** del activo. Frame.io procesa las cargas mediante una escala de resoluciones que alcanza un máximo de 2160p. La API devuelve la representación de mayor calidad disponible **en el momento de la solicitud**. Por tanto, si solo ha terminado de procesarse una representación a 540p al realizar la solicitud, la API devuelve 540p hasta que las representaciones superiores estén listas. ### Campos | Campo | Tipo | Descripción | | | -------------- | --------- | ----------- | ------------------------------------------------------------------------------------------ | | `download_url` | string \\ | null | URL firmada de la representación de mayor calidad disponible en el momento de la solicitud | ### Cuándo usarlo Use `media_links.high_quality` cuando quiera la versión de **mejor calidad sin necesitar el original**, por ejemplo, para exportar una representación de alta resolución para procesamiento posterior o para presentar una previsualización a resolución completa. Si necesita la máxima calidad posible, compruebe el campo `status` del archivo y solicite este include cuando el archivo esté `listo` para asegurarse de que se haya procesado toda la escala de resoluciones. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "high_quality": { "download_url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.efficient Devuelve una URL de descarga para la **representación procesada más pequeña disponible**. Es lo contrario de `high_quality`: Frame.io selecciona la representación de menor resolución disponible. ### Campos | Campo | Tipo | Descripción | | | -------------- | --------- | ----------- | -------------------------------------------------------- | | `download_url` | string \\ | null | URL firmada de la representación más pequeña y eficiente | ### Cuándo usarlo Use `media_links.efficient` cuando el **ancho de banda o el tamaño del archivo sean más importantes que la calidad**, por ejemplo, para generar previsualizaciones rápidas en un entorno con poco ancho de banda o alimentar una canalización de miniaturas que no necesita resolución completa. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "efficient": { "download_url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.video\_h264\_180 Devuelve URL de streaming y descarga para una **transcodificación de vídeo H.264 de baja resolución a 180p** del activo. > **Warning** > > Es un include heredado. Será `null` si no se ha generado una transcodificación a 180p para el activo. En la mayoría de los casos de uso, se recomienda `media_links.efficient`, que selecciona la mejor representación de baja calidad disponible en lugar de depender de que exista una transcodificación específica. ### Campos | Campo | Tipo | Descripción | | | -------------- | --------- | ----------- | ------------------------------------------------- | | `download_url` | string \\ | null | URL firmada para descargar el vídeo H.264 a 180p | | `url` | string \\ | null | URL firmada para streaming del vídeo H.264 a 180p | ### Cuándo usarlo Use `media_links.video_h264_180` cuando necesite específicamente una transcodificación H.264 a 180p garantizada, por ejemplo, para integrarse con un reproductor o una canalización heredados que requieran este formato exacto. Si la transcodificación no existe para un activo determinado, ambas URL serán `null`. > **Warning** > > El archivo video\_h264\_180 no incluye audio. Está pensado para previsualizaciones muy eficientes cuando sean necesarias. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180 ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "interview-clip.mp4", "type": "file", "media_links": { "video_h264_180": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." } } } } ``` ## media\_links.scrub\_sheet Devuelve una **hoja de sprites WebP**, es decir, una sola imagen que contiene una cuadrícula de miniaturas de fotogramas de vídeo muestreados de forma uniforme a lo largo de la duración del vídeo. Se usa para crear IU de barrido de vídeo, donde el reproductor muestra un fotograma de previsualización cuando el usuario arrastra el control por la línea de tiempo. > **Info** > > Las hojas de barrido solo se generan para **activos de vídeo**. El include devolverá URL `null` para imágenes, PDF y otros archivos que no sean de vídeo. ### Campos | Campo | Tipo | Descripción | | | -------------------------- | --------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `download_url` | string \\ | null | URL firmada para descargar la hoja de sprites WebP | | `url` | string \\ | null | URL firmada para cargar la hoja de sprites WebP en línea | | `metadata` | object \\ | null | Información de diseño de mosaicos para extraer fotogramas individuales (solo en la API experimental) | | **`Campos de` metadatos:** | | | | | Campo | Tipo | Descripción | | | --- | --- | --- | | | `tile_x` | integer | Número de columnas de miniaturas en la cuadrícula | | | `tile_y` | integer | Número de filas de miniaturas en la cuadrícula | | | `thumb_width` | integer | Anchura de cada miniatura en píxeles | | | `thumb_height` | integer | Altura de cada miniatura en píxeles | | | `padding` | integer | Separación en píxeles entre miniaturas | | | `frames` | integer | Número total de fotogramas muestreados en la hoja | | ### Cuándo usarlo Use `media_links.scrub_sheet` al crear un reproductor de vídeo personalizado o una IU de línea de tiempo que necesite mostrar una miniatura de previsualización cuando el usuario realice un barrido. En lugar de realizar una solicitud independiente por cada fotograma, la hoja de sprites agrupa todos los fotogramas de previsualización en una sola descarga de imagen. ### Ejemplo de solicitud ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet ``` ### Ejemplo de respuesta ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "interview-clip.mp4", "type": "file", "media_links": { "scrub_sheet": { "download_url": "https://assets.frame.io/...", "url": "https://assets.frame.io/...", "metadata": { "tile_x": 10, "tile_y": 10, "thumb_width": 160, "thumb_height": 90, "padding": 1, "frames": 100 } } } } } ``` ### Extracción de un fotograma de la hoja de sprites La hoja de sprites es una cuadrícula de columnas `tile_x` × filas `tile_y`. Para mostrar la miniatura de un índice de fotograma determinado, basado en cero, calcule su posición dentro de la imagen: ```javascript function getFrameOffset(frameIndex, metadata) { const { tile_x, thumb_width, thumb_height, padding } = metadata; const col = frameIndex % tile_x; const row = Math.floor(frameIndex / tile_x); return { x: col * (thumb_width + padding), y: row * (thumb_height + padding), width: thumb_width, height: thumb_height, }; } ``` A continuación, puede usar `background-position` de CSS para mostrar el mosaico correcto de la hoja de sprites: ```javascript function applyFrameToElement(el, frameIndex, scrubSheet) { const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata); el.style.backgroundImage = `url(${scrubSheet.url})`; el.style.backgroundPosition = `-${x}px -${y}px`; el.style.width = `${width}px`; el.style.height = `${height}px`; } ``` Para asignar una posición de reproducción (en segundos) a un índice de fotograma, use la duración total del vídeo y el número de fotogramas de la hoja: ```javascript function positionToFrameIndex(currentSeconds, durationSeconds, metadata) { const progress = currentSeconds / durationSeconds; return Math.min( Math.floor(progress * metadata.frames), metadata.frames - 1 ); } ``` > **Info** > > El campo `metadata` solo está disponible en la versión de API experimental. En la API v4 estable, `scrub_sheet` devuelve solo `download_url` y `url`. ## Combinación de varios includes Puede solicitar varios includes en una sola llamada de API: ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` ```json { "data": { "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e", "name": "hero-banner.png", "type": "file", "media_links": { "thumbnail": { "download_url": "https://s3.amazonaws.com/...", "url": "https://s3.amazonaws.com/..." }, "original": { "download_url": "https://s3.amazonaws.com/...", "inline_url": "https://s3.amazonaws.com/..." } } } } ``` ## Elección del include adecuado | Objetivo | include que se debe usar | | --------------------------------------------------------------------- | ----------------------------------------------- | | Mostrar una imagen de previsualización en la IU | `media_links.thumbnail` | | Permitir que un usuario descargue el archivo original | `media_links.original` | | Abrir el archivo original directamente en el explorador | `media_links.original` → `inline_url` | | Obtener la representación de mejor calidad para exportación | `media_links.high_quality` | | Obtener una representación pequeña para uso con poco ancho de banda | `media_links.efficient` | | Transmitir o descargar un vídeo de baja resolución (heredado) | `media_links.video_h264_180` | | Crear una IU de barrido de vídeo con previsualizaciones de fotogramas | `media_links.scrub_sheet` | | Dirigir a un usuario al archivo en Frame.io | Use `view_url` de la respuesta base del archivo | > **Info** > > `View_url,`, disponible en todas las respuestas de archivo sin necesidad de include, es un vínculo profundo permanente a la aplicación web de Frame.io. **No** es una URL multimedia; abre la IU de Frame.io y no caduca. Úselo cuando quiera dirigir a un usuario para que revise o comente un activo directamente en Frame.io, no cuando necesite servir o descargar el archivo mediante programación. ## Disponibilidad de includes Los includes de vínculos multimedia solo se rellenan cuando Frame.io ha terminado de procesar el archivo cargado. Si solicita un include inmediatamente después de la carga, las URL pueden ser `null` mientras la transcodificación está en curso. Compruebe el campo `status` del objeto de archivo; los includes estarán disponibles cuando status sea `ready`.