Liens média | Frame.io API Documentation

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

Includes multiples

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

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

import frameio
client = frameio.Frameio(auth="<YOUR_TOKEN>")
file = client.files.get(
    file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
    include=["media_links.thumbnail", "media_links.original"]
)
print(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
`inline_url`	chaîne \	null

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original

Exemple de réponse

{
  "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/..."
      }
    }
  }
}

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`	chaîne \	null

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

Exemple de réponse

{
  "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

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality

Exemple de réponse

{
  "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

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient

Exemple de réponse

{
  "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.

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`	chaîne \	null

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.

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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180

Exemple de réponse

{
  "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.

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`	chaîne \	null
`metadata`	objet \	null
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

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet

Exemple de réponse

{
  "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 :

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 :

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 :

function positionToFrameIndex(currentSeconds, durationSeconds, metadata) {
  const progress = currentSeconds / durationSeconds;
  return Math.min(
    Math.floor(progress * metadata.frames),
    metadata.frames - 1
  );
}

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 :

GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

{
  "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

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.