Postman 集合 | Frame.io API Documentation

本指南介绍了官方 Frame.io Developer API Postman 集合的基础知识，这是一组预构建的请求，您可以将其用于 Frame.io V4 API 使用入门。

该集合涵盖了 V4 API 端点的完整范围，分为稳定和实验性两个类别。稳定端点可随时投产，实验性端点是功能完整的新增部分，但可能会根据反馈进行更改，然后才会升级为稳定版本。

Postman 使用入门

本指南假设您已为该 API 生成了凭据。如果尚未生成，请先从此处开始

创建 Postman 帐户 + 选择您的设置

在 postman.com 创建您的 Postman 帐户，然后选择您的设置。您可以在此处下载 Postman 应用程序或使用 web 上的 Postman。

导入 Frame.io Developer API Postman 集合

Frame.io Developer API 集合

在此处 Fork 或下载

设置您的环境

Frame.io Developer API 集合有一个默认环境，其中定义了多个环境变量。BASE_URL 和 IMS_BASE_URL 值是静态的。您可以根据帐户信息配置其他环境变量。

下表是集合的默认环境和暂存环境中每个变量的说明：

变量	描述	如何检索	环境
`BASE_URL`	所有 V4 API 请求的基础 URL	预配置，请勿编辑	默认
`IMS_BASE_URL`	Adobe IMS 身份验证基础 URL	预配置，请勿编辑	默认，暂存
`IMS_CLIENT_ID`	您的 Frame.io 应用程序客户端 ID	Adobe Developer Console 中的凭据页面	暂存
`IMS_CLIENT_SECRET`	您的 Frame.io 应用程序客户端密钥	Adobe Developer Console 中的凭据页面	暂存
`FOLDER_ID`	目标文件夹的唯一 ID	在文件夹响应对象中返回	默认
`WEBHOOK_ID`	已配置 Webhook 的唯一 ID	在 Webhook 响应对象中返回	默认
`ASSET_ID`	文件或文件夹资产的唯一 ID	在文件或文件夹响应对象中返回	默认
`SHARE_ID`	共享链接的唯一 ID	在共享响应对象中返回	默认

设置授权

本指南使用 OAuth 2.0 通过 Frame.io V4 API 进行身份验证。有关其他身份验证方法（例如服务器到服务器 (S2S)）的信息，请参阅身份验证指南。

IMS_CLIENT_ID 和 IMS_CLIENT_SECRET 环境变量应设置为从 Adobe Developer Console 中项目的凭据详情中检索到的值。

在项目的凭据详情部分中，将重定向 URI 和重定向 URL 模式设置为 Postman 的公共回调端点：重定向 URI

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

重定向 URI 模式

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

设置并保存环境变量后，下一步是配置授权设置。为此，请点击左侧边栏顶部的集合图标以打开您的集合浏览器。

在集合浏览器中，选择 Frame.io V4 Developer API 集合的根目录（通常标题为 Frame.io Developer API Collection，后跟您的分支名称），然后选择授权选项卡。 alt image

OAuth 权限范围已在收藏集中预配置。设置环境变量后，使用获取新的访问令牌按钮来启动 OAuth 2.0 流程。此时将打开一个浏览器窗口以完成身份验证流程，并将令牌返回到 Postman。

要验证您的授权配置，请在用户文件夹中选择**获取用户详情请求，然后单击发送**。

收到 200 OK 响应，即确认了您的集合配置正确，并且您已通过正确帐户的身份验证。如果遇到错误，请参阅快速入门指南中的**此部分**，了解错误和警告信息。

示例响应

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

获取您的帐户 ID

account_id 是大多数 V4 API 端点的必需路径参数，您需要使用它来测试其他请求。您可以通过 GET List accounts 请求获取您的 account_id，该请求位于集合的 Accounts 文件夹中。 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"
  }
}

如果您有多个 Frame.io 帐户，每个帐户都会在响应中显示为单独的对象

获得帐户 ID 后，从响应中复制 id 值并将其保存为环境变量。将其作为 account_id 路径参数，在未来的请求中使用 {{ACCOUNT_ID}}。

工作区和项目操作

您的 Frame.io 文件存储在文件夹中，按工作区内的项目进行组织。有关 V4 资源层级的完整概述，请参阅<strong>](</span)此指南**。

列出工作区

工作区文件夹中的 GET list workspaces 请求调用 /v4/accounts/:account_id/workspaces，并返回您的帐户有权访问的工作区列表。某些项目操作需要 workspace_id 作为路径参数，因此如果您计划列出或检索项目，请先保存您的工作区 ID。成功的请求将返回 200 OK 状态和类似于以下示例的响应体。 示例响应

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

创建工作区

POST create workspace 请求调用 /v4/accounts/:account_id/workspaces 为您的帐户创建新的工作区。在请求编辑器中，选择请求体选项卡，在 data 对象内设置工作区的名称。成功的请求将返回 201 Created 状态和类似于以下示例的响应体。 示例响应

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

更新工作区

PATCH update workspace 请求调用 /v4/accounts/:account_id/workspaces/:workspace_id 来更新工作区的名称。在请求编辑器中，选择请求体选项卡，在 data 对象内设置工作区的新名称。成功的请求将返回 200 OK 状态和类似于以下示例的响应体。 示例响应

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

创建项目

POST create project 请求调用 /v4/accounts/:account_id/workspaces/:workspace_id/projects，以在给定的工作区中创建新项目。在请求编辑器中，选择请求体选项卡，在 data 对象内设置项目的名称。可选的 restricted 属性是一个布尔值，用于创建受限项目。成功的请求将返回 201 Created 状态和类似于以下示例的响应体。 示例响应

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

从响应中复制 root_folder_id 并将其设置为您的 FOLDER_ID 环境变量的值。您将需要此信息来完成本指南的其余部分。

您可以使用位于项目权限文件夹中的后续 PATCH 更新项目中的用户角色请求，将用户添加到新创建的受限项目。（API 参考）

文件夹和文件操作

列出文件夹次项

**GET 列出文件夹次项**请求调用 /v4/accounts/:account_id/folders/:folder_id/children 来列出给定文件夹中的次项。在此情况下，项目根文件夹设置为您的 FOLDER_ID 环境变量。

您可以使用以下可选查询参数来完善您的响应：

参数	类型	描述
`page_size`	整数	将返回文件夹数量限制为 1-100。默认为 50
`type`	字符串	按资源类型筛选文件夹次项：`file` 或 `folder`
`after`	字符串	不透明光标，用于返回分页结果的请求。这是自动生成的，并在前一个响应的 `links` 对象中返回。该内容不属于人类可读格式。
`include_total_count`	布尔值	返回所有实体的总计数默认为 False
`include`	枚举	为每个返回的对象附加额外数据，例如 `creator`、`project`、`media_links`。有关支持参数的完整列表，请参阅 API 参考

成功的请求将返回 200 OK 状态和类似于以下示例的响应体。 示例响应

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

测试 after 参数

如果您要测试分页结果，请在响应中找到 links 对象：

从 next 属性 URL 中，仅复制 after= 后面的字符串值

将此值设置为您下一个请求中 after 查询参数的值。

注意避免重复编码！ 如果 URL 包含编码字符（如 %3D%3D），请将其替换为原始版本 (==)。 Postman 会按字面意思解释您的输入，还可能会对其进行双重编码，从而产生 422 错误

创建文件 - 本地上传

**POST 创建文件 - 本地上传**请求调用 /v4/accounts/:account_id/folders/:folder_id/files/local_upload 在指定文件夹中上传本地文件。

本地上传需要两次或多次请求，具体取决于文件大小。首次测试时，请使用小文件（小于 10 MB），确保将过程限制为单个上传 URL。

创建占位符文件资源

在请求编辑器中，选择请求体选项卡以在 data 对象中设置名称和文件大小（以 bytes 为单位）。成功的请求将返回 201 Created 状态和类似于以下示例的响应体。 示例响应

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

此调用已在指定文件夹中创建了占位符文件资源。使用响应中 upload_urls 数组内的预签名上传 URL 在下一步中完成上传。

上传文件内容

单击响应中 upload_urls 数组内的 URL 在 Postman 中打开新的请求选项卡。将请求方法更改为 PUT。在请求编辑器中，选择标头选项卡，向您的请求添加以下标头：

x-amz-acl:private

Content-Type：此项必须与文件名中指定的扩展类型完全匹配（例如：名为 IMG.png 的文件必须使用 image/png）

alt image 在请求编辑器中选择请求体选项卡，然后点击二进制选项来选择您的文件。选择完后，点击发送完成您的请求。成功的请求将返回 200 OK 状态，确认您的文件已上传。

文件上传之后，Frame.io 媒体管道会自动处理转码和缩略图生成。对于较大的文件，可能需要几分钟时间让文件从 created 状态变为 ready 状态。

创建文件 - 远程上传

POST 创建文件 - 远程上传 请求调用 /v4/accounts/:account_id/folders/:folder_id/files/remote_upload 以使用提供的来源 URL 将外部文件提取到指定文件夹中。在请求编辑器中，选择请求体选项卡，在 data 对象中设置文件的名称和来源 URL。成功的请求将返回 202 Accepted 状态和类似于以下示例的响应体。 示例响应

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