Colección de Postman | Frame.io API Documentation

Esta guía cubre los aspectos básicos de la colección oficial de Postman de la API para desarrolladores de Frame.io, un conjunto de solicitudes prediseñadas que puede usar para empezar a trabajar con la API V4 de Frame.io.

La colección cubre toda la variedad de puntos finales de la API V4, divididos en categorías estable y experimental. Los puntos finales estables están listos para producción, mientras que los extremos experimentales son incorporaciones más recientes que funcionan, pero pueden cambiar en función de los comentarios antes de promocionarse a estables.

Introducción a Postman

En esta guía se presupone que ha generado credenciales para la API. Si aún no lo ha hecho, empiece aquí primero

Creación de una cuenta de Postman y elección de la configuración

Cree una cuenta de Postman en postman.com, y elija su configuración. Puede descargar la aplicación de Postman aquí o usar Postman en la web.

Importación de la colección de Postman de la API para desarrolladores de Frame.io

Frame.io Developer API Collection

Haga un fork o descárguela aquí

Configuración del entorno

Frame.io Developer API Collection tiene un entorno predeterminado con varias variables de entorno definidas. Los valores BASE_URL e IMS_BASE_URL son estáticos. Se pueden configurar variables de entorno adicionales según la información de la cuenta.

A continuación, se muestra una tabla con una descripción de cada variable incluida en los entornos Default y Stage de la colección:

Variable	Descripción	Cómo obtenerla	Entorno
`BASE_URL`	URL base para todas las solicitudes de la API V4	Preconfigurada, no la edite	Predeterminado
`IMS_BASE_URL`	URL base de autenticación de Adobe IMS	Preconfigurada, no la edite	Default, Stage
`IMS_CLIENT_ID`	ID de cliente de la aplicación de Frame.io	Página de credenciales de Adobe Developer Console	Stage
`IMS_CLIENT_SECRET`	Secreto de cliente de la aplicación de Frame.io	Página de credenciales de Adobe Developer Console	Stage
`FOLDER_ID`	ID único de la carpeta de destino	Se devuelve en el objeto de respuesta de carpeta	Predeterminado
`WEBHOOK_ID`	ID único de un webhook configurado	Se devuelve en el objeto de respuesta de webhook	Predeterminado
`ASSET_ID`	ID único de un activo de archivo o carpeta	Se devuelve en el objeto de respuesta de archivo o carpeta	Predeterminado
`SHARE_ID`	ID único de un enlace de uso compartido	Se devuelve en el objeto de respuesta de elemento de uso compartido	Predeterminado

Configuración de la autorización

Esta guía utiliza OAuth 2.0 para la autenticación con la API Frame.io V4. Para obtener información acerca de otros métodos de autenticación, como Servidor a servidor (S2S), consulte la Guía de autenticación.

Las variables de entorno IMS_CLIENT_ID e IMS_CLIENT_SECRET deben establecerse con los valores obtenidos de los detalles de Credenciales del proyecto en Adobe Developer Console.

En la sección Credential’s details de su proyecto, establezca Redirect URI y Redirect URL Pattern en el punto final de devolución de llamada público de Postman: Redirect URI

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

Patrón de URI de redireccionamiento

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

Una vez definidas y guardadas las variables del entorno, el siguiente paso es configurar los ajustes de autorización. Para ello, haga clic en el icono de Colecciones en la parte superior de la barra lateral izquierda para abrir el explorador de colecciones. En el explorador de colecciones, seleccione la raíz de la colección de API de desarrollador de Frame.io V4 (normalmente llamada “Frame.io Developer API Collection” seguida del nombre de fork) y seleccione la ficha Authorization. alt image Ámbitos OAuth ámbitos OAuth están preconfigurados en la colección. Con las variables de entorno definidas, utilice el botón <strong>Get New Access Token** para iniciar el flujo de OAuth 2.0. Se abrirá una ventana del navegador para completar el proceso de autenticación y devolver el token a Postman. Para comprobar la configuración de autorización, seleccione la solicitud GET user details en la carpeta Users y haga clic en Send. Una respuesta 200 OK confirma que su colección está configurada correctamente y que se ha autenticado en la cuenta correcta. Si encuentra un error, consulte ****](</span)esta sección de la Guía de introducción para obtener información sobre errores y advertencias. Ejemplo de respuesta

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

Obtención del ID de Account

account_id es un parámetro de ruta obligatorio para la mayoría de los puntos finales de la API V4 y lo necesitará para probar otras solicitudes. Puede obtener su account_id con la solicitud GET List accounts, ubicada en la carpeta Accounts de la colección. Respuesta de ejemplo de la referencia de API

{
  "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 tiene varias cuentas de Frame.io, cada una aparecerá como un objeto independiente en la respuesta

Una vez que haya obtenido el ID de Account, copie el valor id de la respuesta y guárdelo como variable de entorno. Hará referencia a él como account_id de parámetro de ruta mediante {{ACCOUNT_ID}} en futuras solicitudes.

Operaciones de Workspace y Project

Los archivos de Frame.io se almacenan en carpetas, organizadas en Projects dentro de Workspaces. Para obtener una descripción completa de la jerarquía de recursos de V4, consulte <strong>](</span)esta guía**.

Enumeración de Workspaces

La solicitud GET list workspaces de la carpeta Workspaces llama a /v4/accounts/:account_id/workspaces y devuelve una lista de Workspaces a los que puede acceder la cuenta. Algunas operaciones de Project requieren workspace_id como parámetro de ruta, por lo que debe guardar primero el ID de Workspace si tiene previsto enumerar o recuperar Projects. Una solicitud correcta devolverá el estado 200 OK y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Creación de un Workspace

La solicitud POST create workspace llama a /v4/accounts/:account_id/workspaces para crear un nuevo Workspace para su cuenta. En el editor de solicitudes, seleccione la pestaña Body para definir el nombre del Workspace dentro del objeto data. Una solicitud correcta devolverá el estado 201 Created y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Actualización de un Workspace

La solicitud PATCH update workspace llama a /v4/accounts/:account_id/workspaces/:workspace_id para actualizar el nombre de un Workspace. En el editor de solicitudes, seleccione la pestaña Body para definir el nuevo nombre del Workspace dentro del objeto data. Una solicitud correcta devolverá el estado 200 OK y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Creación de un proyecto

La solicitud POST create project llama a /v4/accounts/:account_id/workspaces/:workspace_id/projects para crear un nuevo Project en un Workspace determinado. En el editor de solicitudes, seleccione la pestaña Body para definir el nombre del Project dentro del objeto data. La propiedad opcional restricted es un valor booleano que se usa para crear un Project restringido. Una solicitud correcta devolverá el estado 201 Created y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Copie el root_folder_id de la respuesta y defínalo como valor de la variable de entorno FOLDER_ID. Lo necesitará para las secciones restantes de esta guía.

Puede añadir un usuario a un Project restringido recién creado con una solicitud posterior PATCH Update user role in a Project ubicada en la carpeta Project Permissions. (Referencia de API)

Operaciones de Folder y File

Enumeración de elementos secundarios de Folder

La solicitud GET list folder children llama a /v4/accounts/:account_id/folders/:folder_id/children para enumerar los elementos secundarios de una Folder determinada. En este caso, se trata de la carpeta raíz del Project definida como variable de entorno FOLDER_ID.

Puede usar los siguientes parámetros de consulta opcionales para ajustar la respuesta:

Parámetro	Tipo	Descripción
`page_size`	Integer	Limita el número de Folders devueltas, de 1 a 100. El valor predeterminado es 50
`type`	String	Filtra los elementos secundarios de Folder por tipo de recurso: `file` o `folder`
`after`	String	Cursor opaco para solicitudes que devuelven resultados paginados. Se genera automáticamente y se devuelve en el objeto `links` de la respuesta anterior. No está pensado para que pueda leerse.
`include_total_count`	Boolean	Devuelve el recuento total de todas las entidades El valor predeterminado es False
`include`	Enum	Añade datos adicionales a cada objeto devuelto, como `creator`, `proyecto` o `media_links`. Para obtener una lista completa de los parámetros admitidos, consulte Referencia de API

Una solicitud correcta devolverá el estado 200 OK y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Prueba del parámetro after

Si va a probar resultados paginados, busque el objeto links en la respuesta:

Desde la URL de la propiedad next, copie solo el valor de cadena que aparece después de after=

Defina este valor como valor del parámetro de consulta after en la siguiente solicitud.

Tenga cuidado con la doble codificación. Si la URL contiene caracteres codificados (por ejemplo, %3D%3D), sustitúyalos por la versión sin codificar (==). Postman interpreta la entrada literalmente y puede codificar dos veces estos caracteres, lo que provocaría un error 422

Creación de un File: carga local

La solicitud POST create file - local upload llama a /v4/accounts/:account_id/folders/:folder_id/files/local_upload para cargar un archivo local en una Folder especificada.

Las cargas locales requieren dos o más solicitudes en función del tamaño del archivo. Para la primera prueba, use un archivo pequeño (de menos de 10 MB) para limitar el proceso a una sola URL de carga.

Creación de un recurso de File marcador de posición

En el editor de solicitudes, seleccione la pestaña Body para definir el nombre y el tamaño del archivo (especificado en bytes) dentro del objeto data. Una solicitud correcta devolverá el estado 201 Created y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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

Esta llamada ha creado un recurso de File marcador de posición en la Folder especificada. Use la URL de carga con firma previa de la matriz upload_urls de la respuesta para completar la carga en el paso siguiente.

Carga del contenido del archivo

Haga clic en la URL de la matriz upload_urls de la respuesta para abrir una pestaña de solicitud nueva en Postman. Cambie el método de solicitud a PUT. En el editor de solicitudes, seleccione la pestaña Headers para añadir los siguientes encabezados a la solicitud:

x-amz-acl:private

Content-Type: debe coincidir exactamente con el tipo de extensión especificado en el nombre de archivo (por ejemplo, un archivo llamado IMG.png debe usar image/png)

alt image En el editor de solicitudes, seleccione la pestaña Body y haga clic en la opción binary para seleccionar el archivo. Una vez seleccionado, haga clic en Send para completar la solicitud. Una solicitud correcta devolverá el estado 200 OK, lo que confirma que el archivo se ha cargado.

Una vez cargado el archivo, la canalización multimedia de Frame.io gestiona automáticamente la transcodificación y la generación de miniaturas. En el caso de archivos de mayor tamaño, el archivo puede tardar unos instantes en pasar del estado created al estado ready.

Creación de un File: carga remota

La solicitud POST create file - remote upload llama a v4/accounts/:account_id/folders/:folder_id/files/remote_upload para traer un archivo externo a una Folder especificada mediante una URL de origen proporcionada. En el editor de solicitudes, seleccione la pestaña Body para definir el nombre y la URL de origen del archivo dentro del objeto data. Una solicitud correcta devolverá el estado 202 Accepted y un cuerpo de respuesta similar al ejemplo siguiente. Ejemplo de respuesta

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