> This page is for Plate-forme, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 expérimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Hérité: 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. # Liens de médias Frame.io stocke et traite les fichiers que vous chargez dans vos projets : images, vidéos, fichiers PDF, etc. Lorsque vous récupérez un fichier via l’API, la réponse de base comprend des métadonnées essentielles telles que le nom du fichier, son statut et une `view_url` permettant de l’ouvrir dans l’application Frame.io. Pour accéder au contenu du fichier proprement dit (qu’il s’agisse de l’original, d’un aperçu ou de rendus de qualité différente), utilisez **includes**. Ce guide explique les liens de médias disponibles sur les points d’entrée **Liste des fichiers** et **Obtenir un fichier**, ce qu’ils renvoient respectivement et quand les utiliser. ## Que désignent les « includes » ? Les « includes » sont des champs facultatifs que vous pouvez demander en plus d’un fichier de réponse. Par défaut, l’API ne renvoie que les métadonnées essentielles du fichier : nom, statut, type, heure et date et `view_url`. Les « includes » vous permettent de choisir de recevoir des données supplémentaires, et donc de limiter le nombre de réponses lorsque vous n’avez pas besoin de toutes les informations. ### Comment ajouter des « includes » ? Fournissez une liste de noms de fichiers « include » séparés par des virgules en tant que paramètre de requête `include` sur n’importe quelle requête **Obtenir un fichier** ou **Répertorier des fichiers** : **`Include unique`** ```bash title="Include unique" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` **`Includes multiples`** ```bash title="Includes multiples" GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original ``` **`Includes sur Répertorier des fichiers`** ```bash title="Includes sur Répertorier des fichiers" GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail ``` Les « includes » fonctionnent de la même manière pour les points d’entrée de type fichier unique que pour ceux de type liste. Utilisés avec la Liste des fichiers, les « includes » sont traités pour chaque fichier de la réponse. ### Exemples de 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); ``` Les « includes » non demandés sont totalement omis de la réponse. ## Vue d’ensemble des includes de liens de médias #### media\_links.original Fichier d’origine, tel qu’il a été chargé. #### media\_links.thumbnail Image d’aperçu au format PNG à des fins d’affichage. #### media\_links.high\_quality Meilleur rendu traité disponible. #### media\_links.efficient Rendu le plus compact disponible pour les cas d’utilisation à faible bande passante. #### media\_links.video\_h264\_180 Transcodage vidéo H.264 en basse résolution (180p) pour le streaming et la lecture. #### media\_links.scrub\_sheet Feuille de sprites WebP contenant des miniatures d’images vidéo pour la création d’une interface utilisateur de défilement. ## media\_links.original Renvoie des URL signées pointant vers le **fichier d’origine tel qu’il a été chargé**, sans aucun traitement ni conversion. ### Champs | Champ | Type | Description | | | -------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- | | `download_url` | chaîne \\ | null | URL signée qui force le téléchargement d’un fichier (`Content-Disposition: attachment`) | | `inline_url` | chaîne \\ | null | URL signée qui ouvre le fichier directement dans le navigateur (`Content-Disposition: inline; filename=`) | ### Quand les utiliser ? Utilisez `media_links.original` lorsque vous avez besoin du fichier source, par exemple, pour permettre à un utilisateur de télécharger le fichier MOV, MP4, MXF, AVI, PSD, PNG ou TIFF d’origine, ou pour transmettre les octets d’origine à un autre système. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original ``` ### Exemple de réponse ```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** > > Ces URL sont des **URL S3 signées temporaires** : elles ont une durée de validité limitée. Ne les mettez pas en cache et ne les enregistrez pas ; demandez une nouvelle URL chaque fois que vous en avez besoin. ## media\_links.thumbnail Renvoie une **image d’aperçu au format PNG** de la ressource, dont la hauteur est limitée à 540 pixels. Il s’agit d’un rendu traité (et non du fichier d’origine) et des filigranes peuvent y figurer en fonction des paramètres de votre compte. ### Champs | Champ | Type | Description | | | -------------- | --------- | ----------- | ------------------------------------------------------------------------------------ | | `download_url` | chaîne \\ | null | URL signée qui force le téléchargement de la miniature au format PNG. | | `url` | chaîne \\ | null | URL signée qui fournit la miniature PNG en ligne sans en-tête `Content-Disposition`. | ### Quand les utiliser ? Utilisez `media_links.thumbnail` lorsque vous souhaitez **afficher un aperçu visuel** du fichier, par exemple dans une grille, une galerie ou un sélecteur de fichiers. Il se charge plus rapidement que l’original et est toujours au format PNG compatible avec le Web. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail ``` ### Exemple de réponse ```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 Renvoie une URL de téléchargement pour le **meilleur rendu traité disponible** de la ressource. Frame.io traite les fichiers chargés selon une échelle de résolution dont la limite maximale est de 2160p. L’API renvoie le rendu de la plus haute résolution disponible **au moment de la requête**. Ainsi, si seul un rendu en 540p a été traité lorsque vous effectuez la requête, l’API renvoie ce rendu en 540p jusqu’à ce que des rendus de plus haute résolution soient disponibles. ### Champs | Champ | Type | Description | | | -------------- | --------- | ----------- | ------------------------------------------------------------------------------------- | | `download_url` | chaîne \\ | null | URL signée permettant d’obtenir le meilleur rendu disponible au moment de la requête. | ### Quand les utiliser ? Utilisez `media_links.high_quality` lorsque vous souhaitez obtenir la version de la **meilleure qualité sans avoir besoin de l’original**, par exemple, pour exporter un rendu haute résolution en vue d’un traitement ultérieur ou pour afficher un aperçu en pleine résolution. Si vous avez besoin d’une qualité optimale, vérifiez le champ `status` du fichier et demandez d’inclure ce fichier dès qu’il est `ready`, afin de vous assurer que la gamme de résolutions a bien été traitée. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality ``` ### Exemple de réponse ```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 Renvoie l’URL de téléchargement du **plus petit rendu traité**. C’est l’inverse de `high_quality` : Frame.io sélectionne le rendu avec la résolution la plus basse disponible. ### Champs | Champ | Type | Description | | | -------------- | --------- | ----------- | ---------------------------------------------------------- | | `download_url` | chaîne \\ | null | URL signée pour le rendu le plus compact/le plus efficace. | ### Quand les utiliser ? Utilisez `media_links.efficient` lorsque la **bande passante ou la taille des fichiers prime sur la qualité**, par exemple, pour générer des aperçus rapides dans un environnement à faible bande passante, ou pour alimenter un pipeline de miniatures qui ne nécessite pas la pleine résolution. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient ``` ### Exemple de réponse ```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 Renvoie les URL de streaming et de téléchargement d’une **version transcodée en H.264 à basse résolution (180p)** du fichier. > **Warning** > > Il s’agit d’un include hérité. Il sera `null` si aucun transcodage en 180p n’a été généré pour la ressource. Dans la plupart des cas, privilégiez l’option `media_links.efficient`, qui sélectionne le meilleur rendu de basse qualité disponible plutôt que de dépendre de l’existence d’un transcodage spécifique. ### Champs | Champ | Type | Description | | | -------------- | --------- | ----------- | ------------------------------------------------------- | | `download_url` | chaîne \\ | null | URL signée pour télécharger la vidéo H.264 en 180p. | | `url` | chaîne \\ | null | URL signée pour le streaming de la vidéo H.264 en 180p. | ### Quand les utiliser ? Utilisez `media_links.video_h264_180` lorsque vous avez spécifiquement besoin d’un transcodage H264 en 180p garanti, par exemple pour l’intégration avec un lecteur ou un pipeline existant qui nécessite précisément ce format. Si le transcodage n’existe pas pour un élément donné, les deux URL seront `null`. > **Warning** > > Le fichier video\_h264\_180 ne contient pas de piste audio. Il est conçu pour permettre des aperçus très rapides en cas de besoin. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180 ``` ### Exemple de réponse ```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 Renvoie une **feuille de sprites WebP**, c’est-à-dire une image unique contenant une grille de miniatures représentant des images de la vidéo, prélevées à intervalles réguliers tout au long de celle-ci. Cette fonctionnalité sert à créer une interface utilisateur permettant de parcourir une vidéo, dans laquelle le lecteur affiche une image d’aperçu lorsque l’utilisateur fait glisser le curseur sur le montage. > **Info** > > Les feuilles de scrub ne sont générées **que pour les ressources vidéo**. Cet include renverra des URL `null` pour les images, les fichiers PDF et les autres fichiers non vidéo. ### Champs | Champ | Type | Description | | | ----------------------- | --------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `download_url` | chaîne \\ | null | URL signée pour télécharger la feuille de sprites WebP. | | `url` | chaîne \\ | null | URL signée pour charger la feuille de sprites WebP en ligne. | | `metadata` | objet \\ | null | Informations sur la disposition des tuiles pour l’extraction d’images individuelles (API expérimentale uniquement). | | Champs **`metadata` :** | | | | | Champ | Type | Description | | | --- | --- | --- | | | `tile_x` | entier | Nombre de colonnes de miniatures dans la grille. | | | `tile_y` | entier | Nombre de lignes de miniatures dans la grille. | | | `thumb_width` | entier | Largeur de chaque miniature en pixels. | | | `thumb_height` | entier | Hauteur de chaque miniature en pixels. | | | `padding` | entier | Espacement en pixels entre les miniatures. | | | `frames` | entier | Nombre total d’images échantillonnées dans la feuille. | | ### Quand les utiliser ? Utilisez `media_links.scrub_sheet` lorsque vous développez un lecteur vidéo personnalisé ou une interface utilisateur de montage qui doit afficher une miniature d’aperçu lorsque l’utilisateur fait défiler la vidéo. Au lieu d’envoyer une requête distincte pour chaque image, la feuille de sprites regroupe toutes les images d’aperçu en un seul téléchargement. ### Exemple de requête ```bash GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet ``` ### Exemple de réponse ```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 } } } } } ``` ### Extraction d’une image de la feuille de sprites Cette feuille de sprites est une grille de `tile_x` colonnes × `tile_y` rangées. Pour afficher la miniature correspondant à un indice d’image donné (compté à partir de zéro), calculez sa position dans l’image : ```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, }; } ``` Vous pouvez ensuite utiliser la propriété CSS `background-position` pour afficher la tuile souhaitée à partir de la feuille 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`; } ``` Pour associer une position de lecture (en secondes) à un index d’image, utilisez la durée totale de la vidéo et le nombre d’images indiqués dans la feuille : ```javascript function positionToFrameIndex(currentSeconds, durationSeconds, metadata) { const progress = currentSeconds / durationSeconds; return Math.min( Math.floor(progress * metadata.frames), metadata.frames - 1 ); } ``` > **Info** > > Le champ `metadata` n’est disponible que dans la version expérimentale de l’API. Dans l’API stable v4, `scrub_sheet` renvoie uniquement `download_url` et `url`. ## Combiner plusieurs includes Vous pouvez présenter plusieurs requêtes d’includes en un seul appel 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/..." } } } } ``` ## Choisir le bon include | Objectif | Include à utiliser | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Afficher une image d’aperçu dans votre interface utilisateur | `media_links.thumbnail` | | Permettre à un utilisateur de télécharger le fichier d’origine | `media_links.original` | | Ouvrir le fichier d’origine directement dans le navigateur | `media_links.original` → `inline_url` | | Obtenir un rendu de la meilleure qualité possible pour l’exportation | `media_links.high_quality` | | Obtenir un rendu allégé pour les connexions à faible débit | `media_links.efficient` | | Regarder en streaming ou télécharger une vidéo en basse résolution (hérité) | `media_links.video_h264_180` | | Créer une interface utilisateur permettant de parcourir une vidéo avec des aperçus d’images | `media_links.scrub_sheet` | | Rediriger un utilisateur vers le fichier dans Frame.io | Utiliser `view_url` à partir de la réponse du fichier de base | > **Info** > > `view_url` (disponible dans chaque réponse de fichier sans avoir besoin d’un include) est un lien direct permanent vers l’application web Frame.io. Il **ne s’agit pas** d’une URL de médias ; elle ouvre l’interface utilisateur de Frame.io et n’a pas de date d’expiration. Utilisez-la lorsque vous souhaitez inviter un utilisateur à consulter ou à commenter un fichier directement dans Frame.io, et non lorsque vous devez diffuser ou télécharger le fichier par programmation. ## Disponibilité des includes Les includes de liens de médias n’apparaissent qu’une fois que Frame.io a fini de traiter le fichier chargé. Si vous demandez un include immédiatement après avoir chargé le fichier, les URL peuvent être `null` tant que le transcodage est en cours. Vérifiez le champ `status` de l’objet fichier : les includes seront disponibles dès que le statut indiquera `ready`.