> This page is for 平台, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - 旧版: 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. # Postman 集合 本指南介绍了官方 Frame.io Developer API Postman 集合的基础知识，这是一组预构建的请求，您可以将其用于 Frame.io V4 API 使用入门。 该集合涵盖了 V4 API 端点的完整范围，分为稳定和实验性两个类别。 稳定端点可随时投产，实验性端点是功能完整的新增部分，但可能会根据反馈进行更改，然后才会升级为稳定版本。 ## Postman 使用入门 > **Tip** > > 本指南假设您已为该 API 生成了凭据。 如果尚未生成，请先从[此处](/platform/docs/quick-start)开始 #### 创建 Postman 帐户 + 选择您的设置 在 [postman.com](http://auth.postman.com/__redirect/login) 创建您的 Postman 帐户，然后选择您的设置。 您可以在[此处](https://www.postman.com/downloads/)下载 Postman 应用程序或使用 web 上的 Postman。 #### 导入 Frame.io Developer API Postman 集合 #### [Frame.io Developer API 集合](https://www.postman.com/adobe/workspace/frame-io-v4-public-api/collection/33150877-924315f2-cc62-45f5-8153-77ff2aaa9067?action=share\&creator=33150877\&active-environment=33150877-cffd66a8-23bd-4c50-8891-29157ead1185) 在此处 Fork 或下载 ### 设置您的环境 Frame.io Developer API 集合有一个默认 环境 ，其中定义了多个环境变量。`BASE_URL` 和 `IMS_BASE_URL` 值是静态的。您可以根据帐户信息配置其他环境变量。 ![alt image](/_fern-img/0780e30f05ff2cee570d698b9adc209f24326281b60e23968e5d78e66c5c9b43.webp) ![alt image](/_fern-img/663c863cbbec947567616faf433d79e3900e70ace3d8d9d26299ee20e204c064.webp) 下表是集合的默认环境和暂存环境中每个变量的说明： | 变量 | 描述 | 如何检索 | 环境 | | ------------------- | ---------------------- | ------------------------------------------------------------------------------------ | ----- | | `BASE_URL` | 所有 V4 API 请求的基础 URL | 预配置，请勿编辑 | 默认 | | `IMS_BASE_URL` | Adobe IMS 身份验证基础 URL | 预配置，请勿编辑 | 默认，暂存 | | `IMS_CLIENT_ID` | 您的 Frame.io 应用程序客户端 ID | **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** 中的凭据页面 | 暂存 | | `IMS_CLIENT_SECRET` | 您的 Frame.io 应用程序客户端密钥 | **[Adobe Developer Console](https://developer.adobe.com/developer-console/)** 中的凭据页面 | 暂存 | | `FOLDER_ID` | 目标文件夹的唯一 ID | 在文件夹响应对象中返回 | 默认 | | `WEBHOOK_ID` | 已配置 Webhook 的唯一 ID | 在 Webhook 响应对象中返回 | 默认 | | `ASSET_ID` | 文件或文件夹资产的唯一 ID | 在文件或文件夹响应对象中返回 | 默认 | | `SHARE_ID` | 共享链接的唯一 ID | 在共享响应对象中返回 | 默认 | --- ### 设置授权 > **Tip** > > [ 本指南使用 OAuth 2.0 通过 Frame.io V4 API 进行身份验证。有关其他身份验证方法（例如服务器到服务器 (S2S)）的信息，请参阅](\ **Tip** > > 如果您有多个 Frame.io 帐户，每个帐户都会在响应中显示为单独的对象 获得帐户 ID 后，从响应中复制 `id` 值并将其保存为环境变量。将其作为 `account_id` 路径参数 ，在未来的请求中使用 `{{ACCOUNT_ID}}`。 --- ## 工作区和项目操作 您的 Frame.io 文件存储在文件夹中，按工作区内的项目进行组织。 有关 V4 资源层级的完整概述，请参阅\**]\(\ **Tip** > > 您可以使用位于**项目权限**文件夹中的后续 **`PATCH 更新项目中的用户角色`**请求，将用户添加到新创建的受限项目。 （**[API 参考](/platform/docs/guides/postman-collection)**） --- ## 文件夹和文件操作 ### 列出文件夹次项 \*\*`GET 列出文件夹次项`\*\*请求调用 **[`/v4/accounts/:account_id/folders/:folder_id/children`](/platform/api-reference/folders/index)** 来列出给定文件夹中的次项。 在此情况下，项目根文件夹设置为您的 **`FOLDER_ID`** 环境变量。 您可以使用以下可选查询参数来完善您的响应： | 参数 | 类型 | 描述 | | ------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **`page_size`** | 整数 | 将返回文件夹数量限制为 **1-100。 默认为 50** | | **`type`** | 字符串 | 按资源类型筛选文件夹次项：**`file`** 或 **`folder`** | | **`after`** | 字符串 | 不透明光标，用于返回分页结果的请求。 **这是自动生成的，并在前一个响应的 `links` 对象中返回。** 该内容不属于人类可读格式。 | | **`include_total_count`** | 布尔值 | 返回所有实体的总计数 **默认为 False** | | **`include`** | 枚举 | 为每个返回的对象附加额外数据，例如 `creator`、`project`、`media_links`。 有关支持参数的完整列表，请参阅 **[API 参考](/platform/api-reference/folders/index#request.query.include)** | 成功的请求将返回 **`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`](/platform/v4/api-reference/files/create-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](/_fern-img/86ddb4aebecaffdee01cf07be3c2e7af0b616285721ec8ef412575114a916b21.webp) 在请求编辑器中选择**请求体**选项卡，然后点击**二进制**选项来选择您的文件。 选择完后，点击**发送**完成您的请求。 成功的请求将返回 **`200 OK`** 状态，确认您的文件已上传。 文件上传之后，Frame.io 媒体管道会自动处理转码和缩略图生成。 对于较大的文件，可能需要几分钟时间让文件从 **`created`** 状态变为 **`ready`** 状态。 --- ### 创建文件 - 远程上传 **`POST 创建文件 - 远程上传`** 请求调用 **[`/v4/accounts/:account_id/folders/:folder_id/files/remote_upload`](/platform/v4/api-reference/files/create-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" } } ```