Collection Postman | Frame.io API Documentation

Ce guide présente les principes de base de la collection Postman officielle de l’API de développement Frame.io, un ensemble de requêtes prédéfinies que vous pouvez utiliser pour vous familiariser avec l’API Frame.io V4.

Cette collection couvre l’ensemble des points d’entrée de l’API V4, répartis en deux catégories : les points d’entrée stables et les points d’entrée expérimentaux. Les points d’entrée stables sont prêts pour la production, tandis que les points d’entrée expérimentaux sont des ajouts récents qui sont fonctionnels, mais susceptibles d’évoluer en fonction des retours d’expérience avant d’être promus au statut de points d’entrée stables.

Prise en main de Postman

Ce guide part du principe que vous avez déjà généré des informations d’identification pour l’API. Si ce n’est pas le cas, commencez par là.

Créer un compte Postman + choisir votre configuration

Créez votre compte Postman sur postman.com, puis choisissez votre configuration. Vous pouvez télécharger l’application Postman ici ou utiliser Postman sur le Web.

Importer la collection Postman de l’API de développement Frame.io

Collection de l’API de développement Frame.io

Forker ou télécharger ici

Configuration de votre environnement

La collection de l’API de développement de Frame.io possède un environnement avec plusieurs variables d’environnement définies. La valeur BASE_URL et la valeur IMS_BASE_URL sont statiques. D’autres variables d’environnement peuvent être configurées en fonction des informations de votre compte.

Vous trouverez ci-dessous un tableau avec la description de chaque variable présente dans les environnements par défaut et d’évaluation de la collection :

Variable	Description	Pour la récupérer	Environnement
`BASE_URL`	URL de base pour toutes les requêtes API V4	Prédéfinie, ne pas modifier	défaut
`IMS_BASE_URL`	URL de base pour l’authentification Adobe IMS	Prédéfinie, ne pas modifier	Par défaut, d’évaluation
`IMS_CLIENT_ID`	Votre ID client de l’application Frame.io	Pages des informations d’identification dans l’Adobe Developer Console	D’évaluation
`IMS_CLIENT_SECRET`	Votre secret client de l’application Frame.io	Pages des informations d’identification dans l’Adobe Developer Console	D’évaluation
`FOLDER_ID`	ID unique du dossier de destination	Renvoyé dans l’objet de réponse du dossier	défaut
`WEBHOOK_ID`	ID unique d’un webhook configuré	Renvoyé dans l’objet de réponse du webhook	défaut
`ASSET_ID`	ID unique d’un fichier ou d’un dossier	Renvoyé dans l’objet de réponse du fichier ou du dossier	défaut
`SHARE_ID`	ID unique d’un lien de partage	Renvoyé dans l’objet de réponse de la requête	défaut

Configuration d’une autorisation

Ce guide utilise OAuth 2.0 pour les authentifications à l’aide de l’API Frame.io V4. Pour plus d’informations sur d’autres méthodes d’authentification, telles que Serveur à serveur (S2S), consultez le Guide d’authentification.

Les variables d’environnement IMS_CLIENT_ID et IMS_CLIENT_SECRET doivent être définies sur les valeurs récupérées dans les Détails des informations d’identification de votre projet dans l’Adobe Developer Console.

Dans la section Détails des informations d’identification de votre projet, définissez l’URI de redirection et le Motif d’URL de redirection sur le point d’entrée de rappel public de Postman : URI de redirection

https://oauth/pstmn.io/v1/callback

Motif d’URI de redirection

https://oauth\\.pstmn\\.io

Une fois les variables d’environnement définies et enregistrées, l’étape suivante consiste à configurer les paramètres d’autorisation. Pour ce faire, cliquez sur l’icône Collections en haut de la barre latérale gauche pour ouvrir le navigateur de collections. Dans le navigateur de collections, sélectionnez la racine de la collection de l’API de développement Frame.io (généralement intitulée « Collection de l’API de développement Frame.io » suivie du nom de votre fourche) et sélectionnez l’onglet Autorisation. alt image OAuth portées sont préconfigurés dans la collection. Avec les variables d’environnement définies, utilisez le bouton <strong>Obtenir un nouveau jeton d’accès** pour démarrer le flux OAuth 2.0. Cela ouvrira une fenêtre du navigateur pour terminer le processus d’authentification et renvoyer le jeton à Postman. Pour vérifier la configuration d’autorisation, sélectionnez la requête GET Informations sur l’utilisateur dans le dossier Users et cliquez sur Envoyer. Une réponse 200 OK confirme que la collection est configurée correctement et que vous vous êtes authentifié sur le compte approprié. Si vous rencontrez une erreur, consultez ****](</span)cette section du Guide de prise en main pour plus d’informations sur les erreurs et avertissements. Exemple de réponse

{
  "data": {
    "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
    "email": "user_email@example.com",
    "id": "00000000-1111-2222-3333-444444444444",
    "name": "Name"
  }
}

Obtention de votre ID de compte

account_id est un paramètre de chemin obligatoire pour la plupart des points d’entrée de l’API V4, et vous en aurez besoin pour tester d’autres requêtes. Vous pouvez obtenir votre account_id à l’aide de la requête GET Répertorier les comptes, située dans le dossier Comptes de la collection. Pages de référence de l’API Exemple de réponse

{
  "data": [
    {
      "created_at": "2023-09-25T19:18:29.614189Z",
      "display_name": "Integration Account",
      "id": "11111111-2222-3333-4444-555555555555",
      "roles": [
        "admin"
      ],
      "storage_limit": 300,
      "storage_usage": 300,
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "image": null
    }
  ],
  "links": {
    "next": "/v4/accounts"
  }
}

Si vous disposez de plusieurs comptes Frame.io, chacun d’entre eux apparaîtra comme un élément distinct dans la réponse.

Une fois que vous avez obtenu votre ID de compte, copiez la valeur de cet id dans la réponse et enregistrez-la en tant que variable d’environnement. Vous l’indiquerez comme paramètre de chemin account_id paramètre de chemin en utilisant {{ACCOUNT_ID}} dans vos futures requêtes.

Opérations dans les espaces de travail et projets

Vos fichiers Frame.io sont stockés dans des dossiers, regroupés en projets au sein d’espaces de travail. Pour un aperçu complet de la hiérarchie des ressources V4, consultez <strong>](</span)ce guide**.

Répertorier les espaces de travail

La requête GET Répertorier les espaces de travail dans le dossier Espaces de travail appelle /v4/accounts/:account_id/workspaces et renvoie une liste des espaces de travail auxquels votre compte a accès. Certaines opérations liées aux projets nécessitent le paramètre workspace_id dans l’URL ; veillez donc à enregistrer au préalable l’identifiant de votre espace de travail si vous prévoyez de lister ou de récupérer des projets. Une requête réussie renvoie un statut 200 OK et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
  "data": [
    {
      "account_id": "11111111-2222-3333-4444-555555555555",
      "created_at": "2024-01-25T19:18:29.614189Z",
      "id": "88888888-bbbb-4444-aaaa-ffffffffffff",
      "name": "My Workspace",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "creator": {
        "active": true,
        "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
        "email": "user_email@example.com",
        "id": "196C1A5777BF4CV00A49411B@176719f5667d82g5594324.e",
        "name": "Name"
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/workspaces"
  }
}

Création d’un espace de travail

La requête POST Créer un espace de travail appelle /v4/accounts/:account_id/workspaces pour créer un nouvel espace de travail pour votre compte. Dans l’éditeur de requêtes, sélectionnez l’onglet Corps pour définir le nom de votre espace de travail au sein de l’objet data. Une requête réussie renvoie un statut 201 Created et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
  "data": {
    "account_id": "11111111-2222-3333-4444-555555555555",
    "created_at": "2024-01-25T19:18:29.614189Z",
    "id": "77777777-999-4444-8888-000000000000",
    "name": "My New Workspace",
    "updated_at": "2024-02-07T16:44:41.986478Z"
  }
}

Mise à jour d’un espace de travail

La requête PATCH Mettre à jour un espace de travail appelle /v4/accounts/:account_id/workspaces/:workspace_id pour mettre à jour le nom d’un espace de travail. Dans l’éditeur de requêtes, sélectionnez l’onglet Corps pour définir le nouveau nom de votre espace de travail au sein de l’objet data. Une requête réussie renvoie un statut 200 OK et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
    "data": {
        "id": "77777777-9999-4444-8888-000000000000",
        "name": "New Workspace Name",
        "updated_at": "2026-05-01T02:42:00.462467Z",
        "account_id": "11111111-2222-3333-4444-555555555555",
        "created_at": "2025-09-22T19:17:02.565496Z"
    }
}

Création d’un projet

La requête POST Créer un projet appelle /v4/accounts/:account_id/workspaces/:workspace_id/projects pour créer un nouveau projet dans un espace de travail donné. Dans l’éditeur de requêtes, sélectionnez l’onglet Corps pour définir le nom de votre projet au sein de l’objet data. La propriété facultative restricted est une valeur booléenne qui sert à créer un projet restreint. Une requête réussie renvoie un statut 201 Created et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
    "data": {
        "id": "fd26defb-8bdf-5c39-9746-24d38f109cc3",
        "name": "test",
        "status": "active",
        "restricted": true,
        "updated_at": "2026-05-01T03:39:58.910884Z",
        "storage": 0,
        "workspace_id": "77777777-999-4444-8888-000000000000",
        "created_at": "2026-05-01T03:39:58.853797Z",
        "root_folder_id": "d4fca8b4-5fd8-4a94-90aa-de13de4b2021",
        "view_url": "https://next.frame.io/project/fd26defb-8bdg-5c39-9746-24d38f109cc3"
    }
}

Copiez le root_folder_id à partir de la réponse et définissez-le comme valeur pour votre variable d’environnement**FOLDER_ID**. Vous en aurez besoin pour les sections suivantes de ce guide.

Vous pouvez ajouter un utilisateur à un projet restreint nouvellement créé avec une autre requête PATCH Mettre à jour les rôles des utilisateurs du projet indiqué dans le dossier Autorisations sur le projet. (Pages de référence de l’API)

Opérations sur les dossiers et les fichiers

Répertorier les éléments enfants du dossier

La requête GET Répertorier les éléments enfants du dossier appelle /v4/accounts/:account_id/folders/:folder_id/children pour répertorier les enfants dans un dossier donné. Dans ce cas, le dossier racine du projet correspond à la valeur de votre variable d’environnement FOLDER_ID.

Vous pouvez utiliser les paramètres de requête facultatifs suivants pour affiner votre réponse :

Paramètre	Type	Description
`page_size`	Entier	Limite le nombre de dossiers renvoyés 1-100. Par défaut : 50
`type`	Chaîne	Filtre les éléments du dossier en fonction du type de ressource : `fichier` ou `dossier`
`after`	Chaîne	Opaque Cursor pour les requêtes renvoyant des résultats paginés. Cette valeur est générée automatiquement et incluse dans les objets `links` d’une réponse précédente. Elle n’est pas destinée à être lisible par un humain.
`include_total_count`	Booléen	Renvoie le nombre total de toutes les entités. La valeur par défaut est Faux.
`include`	Énumération	Ajoute des données supplémentaires à chaque objet renvoyé, telles que `creator`, `project`, `media_links`. Pour obtenir la liste complète des paramètres pris en charge, consultez les pages de référence de l’API

Une requête réussie renvoie un statut 200 OK et un corps de réponse semblable à l’exemple ci-dessous. Exemple de réponse

{
  "data": [
    {
      "type": "file",
      "created_at": "2023-09-25T19:18:29.614189Z",
      "file_size": 1137444,
      "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
      "media_type": "image/png",
      "name": "asset.png",
      "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
      "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
      "status": "created",
      "updated_at": "2024-02-07T16:44:41.986478Z",
      "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
      "creator": {
        "active": true,
        "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
        "email": "user_email@example.com",
        "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e",
        "name": "Jon Doe"
      },
      "media_links": {
        "high_quality": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN"
        },
        "original": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "inline_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=inline%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragSDFXDFh&1Key-Pair-Id=KKI497NESTHMN"
        },
        "thumbnail": {
          "download_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "url": "https://picture2.frame.io/image/s3://frameio-assets-development/image/cd58cb8e-24b3-4498-8d0f-9532fcd04d11/image_full.png?alg=HS256&sig=0_u7w_wz2MwQHOXp000ibbQSMRijujyaUu8V3YYPxu4&exp=1729857600"
        }
      },
      "metadata": [
        {
          "field_type": "select",
          "field_definition_id": "b859ccec-9536-4bf2-bc6f-5e9206e26606",
          "field_definition_name": "Fields definition name",
          "mutable": true,
          "value": [
            {
              "display_name": "Display name",
              "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8"
            }
          ],
          "field_options": [
            {
              "display_name": "Display name",
              "id": "212add59-6527-4fd2-ac30-55ea94a8b5f8"
            },
            {
              "display_name": "Display name 2",
              "id": "c6eb873f-125b-4317-b857-1a22eb3dbf22"
            }
          ]
        }
      ],
      "project": {
        "created_at": "2024-01-25T19:18:29.614189Z",
        "description": "Project Description",
        "id": "e0e30b1d-c3aa-44ee-926e-c6c326fb10dc",
        "name": "My Project",
        "root_folder_id": "be733511-6f15-4d97-8ee7-bc23b2fb0bd7",
        "status": "active",
        "storage": 15000,
        "updated_at": "2024-02-07T16:44:41.986478Z",
        "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/",
        "workspace_id": "91b10e83-5874-44de-9b57-41c937b87256",
        "owner": {
          "active": true,
          "avatar_url": "https://assets.frame.io/uploads/cd58cb8e-24b3-4448-8d0f-9532fcd04d11/original.png?response-content-disposition=attachment%3B+filename%3D%22foo.png&Expires=1729857600&Signature=L09h0pi82dCrMYjr9lMHBragByWYh1&Key-Pair-Id=KKI497NESTHMN",
          "email": "user_email@example.com",
          "id": "196C1A5666BF4EB00A49411B@176719f5667c82b4494214.e",
          "name": "Jon Doe"
        },
        "restricted": false
      }
    }
  ],
  "links": {
    "next": "/v4/accounts/123/folders/123/folders"
  },
  "total_count": 10
}

Test du paramètre after

Si vous testez des résultats paginés, repérez l’objet links dans votre réponse :

À partir de l’URL de la propriété next, copiez uniquement la chaîne de caractères qui suit after=.

Définissez cette valeur pour le paramètre after de votre prochaine requête.

Attention au double encodage ! Si l’URL contient des caractères encodés (par exemple : %3D%3D), remplacez-les par leur version brute (==). Postman interprète vos entrées à la lettre et peut les encoder deux fois, ce qui entraîne une erreur 422.

Création d’un fichier (chargement local)

La requête POST Créer un fichier (chargement local) appelle /v4/accounts/:account_id/folders/:folder_id/files/local_upload pour charger un fichier local dans un dossier donné.

Les chargements locaux nécessitent au moins deux requêtes, selon la taille du fichier. Pour votre premier test, utilisez un petit fichier (moins de 10 Mo) afin de limiter le processus à une seule URL pour charger le fichier.

Créer un espace réservé de ressource de fichier

Dans l’éditeur de requêtes, sélectionnez l’onglet Corps pour définir le nom et la taille de votre fichier (en octets) dans l’objet data. Une requête réussie renvoie un statut 201 Created et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
  "data": {
    "created_at": "2023-09-25T19:18:29.614189Z",
    "file_size": 1137444,
    "media_type": "image/png",
    "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
    "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
    "status": "created",
    "type": "file",
    "updated_at": "2024-02-07T16:44:41.986478Z",
    "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
    "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
    "name": "asset.png",
    "upload_urls": [
      {
        "size": 20000000,
        "url": "https://my.fileupload.url.dev"
      }
    ]
  }
}

Cet appel a créé un espace réservé de ressource de fichier dans le dossier indiqué. Utilisez l’URL de chargement pré-signée figurant dans le tableau upload_urls de la réponse pour terminer le chargement à l’étape suivante.

Charger le contenu du fichier

Cliquez sur l’URL figurant dans le tableau upload_urls de votre réponse pour ouvrir un nouvel onglet de requête dans Postman. Modifiez la méthode de requête en la remplaçant par PUT. Dans l’éditeur de requêtes, sélectionnez l’onglet En-têtes pour ajouter les en-têtes suivants à votre requête :

x-amz-acl :private

Content-Type : doit correspondre exactement au type d’extension indiqué dans le nom du fichier (p. ex. : un fichier nommé IMG.png doit utiliser image/png).

alt image Dans l’éditeur de requêtes, sélectionnez l’onglet En-têtes et cliquez sur l’option binaire pour sélectionner votre fichier. Une fois votre choix effectué, cliquez sur Envoyer pour valider votre requête. Une requête réussie renvoie un statut 200 OK pour confirmer que votre fichier a bien été chargé.

Une fois votre fichier chargé, le pipeline de médias de Frame.io se charge automatiquement du transcodage et de la création des miniatures. Pour les fichiers plus volumineux, le passage du fichier du statut de created à ready peut prendre quelques instants.

Création d’un fichier (chargement à distance)

La requête POST Créer un fichier (chargement à distance) appelle /v4/accounts/:account_id/folders/:folder_id/files/remote_upload pour télécharger un fichier externe dans un dossier spécifié à partir d’une URL source fournie. Dans l’éditeur de requêtes, sélectionnez l’onglet Corps pour définir le nom et l’URL source de votre fichier au sein de l’objet data. Une requête réussie renvoie un statut 202 Accepted et un corps de réponse similaire à l’exemple ci-dessous. Exemple de réponse

{
  "data": {
    "created_at": "2023-09-25T19:18:29.614189Z",
    "file_size": 1137444,
    "media_type": "image/png",
    "parent_id": "2559e2c4-9bb9-4284-b616-a97700a579a4",
    "project_id": "955c0511-656a-4859-b824-ebdbfdcb615b",
    "status": "created",
    "type": "file",
    "updated_at": "2024-02-07T16:44:41.986478Z",
    "view_url": "https://next.frame.io/project/d5e6011c-2bc9-4596-be05-77d562627112/view/5a89a9fb-0900-4b23-826b-127b90e4db4c",
    "id": "cba3b1c5-c644-4592-91c5-0d0b91f4895d",
    "name": "asset.png"
  },
  "links": {
    "status": "/v4/accounts/fb4dd62f-8a89-4e98-8fa1-ad4b29a0094f/files/eab70952-966c-4d99-949b-f0a947ca5754/status"
  }
}