> This page is for Piattaforma, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: 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. # Link multimediali Frame.io conserva ed elabora i file caricati sui progetti, tra cui immagini, video, PDF e altro ancora. Quando recuperi un file tramite l'API, la risposta di base include metadati essenziali come nome del file, stato e `view_url` per aprirlo nell'app Frame.io. Per accedere al contenuto effettivo del file (originale, anteprima o rappresentazioni di qualità diversa), devi usare **includes**. Questa guida spiega quali sono le inclusioni disponibili dei link multimediali negli endpoint **List Files** e **Get File**, cosa restituisce ciascuno e quando utilizzarli. ## Cosa sono le inclusioni? Le inclusioni (includes) sono campi facoltativi che puoi richiedere insieme a una risposta del file. Per impostazione predefinita, l'API restituisce solo i metadati essenziali del file: nome, stato, tipo, marca temporale e `view_url`. Le inclusioni ti permettono di scegliere dati aggiuntivi, semplificando le risposte se non hai bisogno di tutte le informazioni. ### Come aggiungere le inclusioni Passa un elenco separato da virgole di nomi di inclusioni come parametro di richiesta `include` in qualsiasi richiesta **Get File** o **List Files**: **`Inclusione singola`** ```bash title="Inclusione singola" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` **`Inclusioni multiple`** ```bash title="Inclusioni multiple" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` **`Inclusioni su List Files`** ```bash title="Inclusioni su List Files" GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail ``` Le inclusioni funzionano allo stesso modo sia sull'endpoint per singolo file che su quello di elenco. Se utilizzate su List Files, le inclusioni vengono risolte per ogni file nella risposta. ### Esempi SDK **`SDK Python`** ```python title="SDK 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 TypeScript`** ```typescript title="SDK 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); ``` Le inclusioni non richieste vengono omesse completamente dalla risposta. ## Panoramica delle inclusioni dei link multimediali #### media\_links.original Il file originale caricato, esattamente come è stato caricato #### media\_links.thumbnail Un'immagine di anteprima PNG per scopi di visualizzazione #### media\_links.high\_quality La migliore rappresentazione elaborata disponibile #### media\_links.efficient La rappresentazione più piccola disponibile per casi d'uso con larghezza di banda ridotta #### media\_links.video\_h264\_180 Una transcodifica video H264 a bassa risoluzione 180p per lo streaming e la riproduzione #### media\_links.scrub\_sheet Un foglio sprite WebP di miniature di fotogrammi video per creare un'interfaccia a scorrimento ## media\_links.original Restituisce URL firmati che puntano al **file originale esattamente come è stato caricato**, senza elaborazione e senza conversione. ### Campi | Campo | Tipo | Descrizione | | | -------------- | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato che forza il download del file (`Content-Disposition: attachment`) | | `inline_url` | stringa \\ | null | URL firmato che apre il file direttamente nel browser (`Content-Disposition: inline; filename=`) | ### Quando utilizzarlo Utilizza `media_links.original` quando hai bisogno del file di origine, ad esempio per permettere a un utente di scaricare il file MOV, MP4, MXF, AVI, PSD, PNG o TIFF originale oppure per passare i byte originali a un altro sistema. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original ``` ### Risposta di esempio ```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** > > Questi URL sono **URL S3 firmati temporanei** (scadono). Non memorizzarli nella cache e non archiviarli; richiedi un URL nuovo ogni volta che ne hai bisogno. ## media\_links.thumbnail Restituisce un'**immagine di anteprima PNG** della risorsa, limitata a 540px di altezza. Questa è una rappresentazione elaborata (non il file originale) e le filigrane possono essere applicate a seconda delle impostazioni dell'account. ### Campi | Campo | Tipo | Descrizione | | | -------------- | ---------- | ----------- | ------------------------------------------------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato che forza il download della miniatura PNG | | `url` | stringa \\ | null | URL firmato che visualizza la miniatura PNG inline senza intestazione `Content-Disposition` | ### Quando utilizzarlo Usa `media_links.thumbnail` quando devi **mostrare un'anteprima visiva** della risorsa, ad esempio in una vista a griglia, una galleria o un selettore di file. Si carica più velocemente dell'originale ed è sempre in formato PNG compatibile con il web. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` ### Risposta di esempio ```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 Restituisce un URL di download per la **migliore rappresentazione elaborata disponibile** della risorsa. Frame.io elabora i caricamenti attraverso una scala di risoluzione che arriva fino a 2160p. L'API restituisce la rappresentazione più alta disponibile **al momento della richiesta**. Se, perciò, l'elaborazione è terminata solo per una rappresentazione a 540p quando fai la richiesta, l'API restituisce 540p fino a quando non sono pronte delle rappresentazioni superiori. ### Campi | Campo | Tipo | Descrizione | | | -------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato per la rappresentazione con la qualità più alta disponibile al momento della richiesta | ### Quando utilizzarlo Usa `media_links.high_quality` quando desideri la **versione di qualità migliore senza aver bisogno dell'originale**, ad esempio esportando una rappresentazione ad alta risoluzione per l'elaborazione a valle o presentando un'anteprima con risoluzione completa. Se hai bisogno della qualità più alta possibile, controlla il campo `status` del file e richiedi questa inclusione una volta che il file è pronto (`ready`), in modo da assicurarti che la scala di risoluzione completa sia stata elaborata. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality ``` ### Risposta di esempio ```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 Restituisce un URL di download per la **rappresentazione elaborata più piccola disponibile**. È l'opposto di `high_quality`: Frame.io seleziona la rappresentazione con la risoluzione più bassa disponibile. ### Campi | Campo | Tipo | Descrizione | | | -------------- | ---------- | ----------- | ------------------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato per la rappresentazione più piccola ed efficiente | ### Quando utilizzarlo Usa `media_links.efficient` quando **la larghezza di banda o la dimensione del file conta più della qualità**, ad esempio per generare anteprime rapide in un ambiente con larghezza di banda limitata o per alimentare una pipeline di miniature che non ha bisogno della risoluzione completa. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient ``` ### Risposta di esempio ```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 Restituisce gli URL di streaming e download per una **transcodifica video a bassa risoluzione H264 a 180p** della risorsa. > **Warning** > > Questa è un'inclusione legacy. Sarà `null` se non è stata generata una transcodifica a 180p per la risorsa. Per la maggior parte dei casi d'uso è preferibile `media_links.efficient`, che seleziona la migliore rappresentazione di bassa qualità disponibile invece di fare affidamento sull'esistenza di una transcodifica specifica. ### Campi | Campo | Tipo | Descrizione | | | -------------- | ---------- | ----------- | -------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato per scaricare il video H264 a 180p | | `url` | stringa \\ | null | URL firmato per lo streaming del video H264 a 180p | ### Quando utilizzarlo Usa `media_links.video_h264_180` quando hai bisogno specificamente di una transcodifica H264 garantita a 180p, ad esempio per l'integrazione con un lettore o una pipeline legacy che richiede esattamente questo formato. Se la transcodifica non esiste per una determinata risorsa, entrambi gli URL saranno `null`. > **Warning** > > Nel file video\_h264\_180 non è incluso l'audio. È progettato per anteprime molto efficienti, quando necessario. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180 ``` ### Risposta di esempio ```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 Restituisce un **foglio sprite WebP**, ovvero una singola immagine contenente una griglia di miniature dei fotogrammi video campionati uniformemente per tutta la durata del video. Viene utilizzato per creare l'interfaccia utente di scorrimento video, dove il lettore mostra un fotogramma di anteprima mentre l'utente trascina sulla timeline. > **Info** > > I fogli scrub vengono generati **solo per le risorse video**. L'inclusione restituirà degli URL `null` per immagini, PDF e altri file non video. ### Campi | Campo | Tipo | Descrizione | | | --------------------- | ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `download_url` | stringa \\ | null | URL firmato per scaricare il foglio sprite WebP | | `url` | stringa \\ | null | URL firmato per caricare il foglio sprite WebP inline | | `metadata` | object \\ | null | Informazioni sul layout delle sezioni per estrarre i singoli fotogrammi (solo API sperimentale) | | **Campi `metadata`:** | | | | | Campo | Tipo | Descrizione | | | --- | --- | --- | | | `tile_x` | numero intero | Numero di colonne di miniature nella griglia | | | `tile_y` | numero intero | Numero di righe di miniature nella griglia | | | `thumb_width` | numero intero | Larghezza di ogni miniatura in pixel | | | `thumb_height` | numero intero | Altezza di ogni miniatura in pixel | | | `padding` | numero intero | Spaziatura interna in pixel tra le miniature | | | `frames` | numero intero | Numero totale di fotogrammi campionati nel foglio | | ### Quando utilizzarlo Usa `media_links.scrub_sheet` quando crei un lettore video personalizzato o un'interfaccia timeline che deve mostrare una miniatura di anteprima mentre l'utente scorre. Invece di fare una richiesta separata per ogni fotogramma, il foglio sprite raggruppa tutti i fotogrammi di anteprima in un unico download di immagine. ### Richiesta di esempio ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet ``` ### Risposta di esempio ```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 } } } } } ``` ### Estrazione di un fotogramma dal foglio sprite Il foglio sprite è una griglia di colonne `tile_x` × righe `tile_y`. Per visualizzare la miniatura per un determinato indice di fotogramma (con base zero), calcola la sua posizione all'interno dell'immagine: ```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, }; } ``` Puoi quindi utilizzare `background-position` di CSS per mostrare la sezione corretta dal foglio sprite: ```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`; } ``` Per mappare una posizione di riproduzione (in secondi) a un indice di fotogrammi, usa la durata totale del video e il numero di fotogrammi nel foglio: ```javascript function positionToFrameIndex(currentSeconds, durationSeconds, metadata) { const progress = currentSeconds / durationSeconds; return Math.min( Math.floor(progress * metadata.frames), metadata.frames - 1 ); } ``` > **Info** > > Il campo `metadata` è disponibile solo nella versione sperimentale dell'API. Nell'API v4 stabile, `scrub_sheet` restituisce solo `download_url` e `url`. ## Combinare più inclusioni Puoi richiedere più inclusioni in una singola chiamata 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/..." } } } } ``` ## Scelta dell'inclusione giusta | Obiettivo | Inclusione da usare | | ---------------------------------------------------------------------------------------- | ---------------------------------------------- | | Mostra un'immagine di anteprima nell'interfaccia utente | `media_links.thumbnail` | | Consenti all'utente di scaricare il file originale | `media_links.original` | | Apri il file originale direttamente nel browser | `media_links.original` → `inline_url` | | Ottieni la migliore qualità di rendering per l'esportazione | `media_links.high_quality` | | Ottieni un rendering di piccole dimensioni per casi d'uso con larghezza di banda ridotta | `media_links.efficient` | | Trasmetti in streaming o scarica un video a bassa risoluzione (legacy) | `media_links.video_h264_180` | | Crea un'interfaccia utente di scorrimento video con anteprime dei fotogrammi | `media_links.scrub_sheet` | | Indirizza un utente al file in Frame.io | Usa `view_url` dalla risposta del file di base | > **Info** > > `view_url` (disponibile in ogni risposta di file senza bisogno di un'inclusione) è un link diretto permanente nella web app di Frame.io. **Non è** un URL media; apre l'interfaccia utente di Frame.io e non ha nessuna scadenza. Usalo quando vuoi indirizzare un utente a rivedere o commentare una risorsa direttamente in Frame.io, non quando devi fornire o scaricare il file a livello programmatico. ## Disponibilità delle inclusioni I link multimediali vengono popolati solo dopo che Frame.io ha terminato l'elaborazione del file caricato. Se richiedi un'inclusione subito dopo il caricamento, gli URL potrebbero essere `null` mentre la transcodifica è in corso. Controlla il campo `status` nell'oggetto del file: le inclusioni saranno disponibili quando lo stato sarà `ready`.