> This page is for 平台, version V4 实验版.
> 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.

# 入门指南

## Adobe Developer Console

使用 Adobe API 的第一步是在 Adobe Developer Console 中创建**项目**。 Developer Console 中的项目对应于您正在构建的用于调用 Frame.io 开发者 API 的应用程序。 这与 Frame.io 中的项目不同。

#### 资源层级

**帐户 → 工作区 → 项目 → 文件夹 → 文件夹/版本堆栈/文件**

#### [项目指南](https://developer.adobe.com/developer-console/docs/guides/projects/)

在 Developer Console 中创建项目后，将 Frame.io API 添加到其中。

## Frame.io V4 开发者 API 有哪些新增功能？

正如 Frame.io 应用程序已为版本 4 进行了彻底改造一样，V4 API 也从头开始进行了重新设计。 尽管一些关键概念与旧版本保持相似，但许多概念已被替换或重新设计，用来支持更强大的协作工作流和集成。 全新 API 的引入也为我们提供了大幅简化操作并优先考虑重要客户工作流的机会。

> **Info**
>
> Frame.io V4 与旧版的比较请参见[此处](https://help.frame.io/zh-CN/articles/9084073-frame-io-v4-legacy-feature-comparison)。

在 V4 API 中，一些资源已进行了重命名（如工作区，在 Frame.io 旧版中称为团队）来匹配 Frame.io 版本 4，而其他资源也已重命名（如旧版中的资产）为指代特定的存储实体（文件、文件夹和版本堆栈），从而减少开发人员的困惑。 还有一些（例如自定义字段和共享项）是全新资源。 除了其他重大变更外，我们还大幅减少了默认情况下为资源请求返回的数据量，重命名了几个响应中的属性名称，使其在整个 API 界面上更加准确和一致，还切换到新的基于光标的分页机制。 因此，需要注意的是，除了 Camera to Cloud (C2C) API 之外，与旧版 API 集成的客户端与 V4 API 不兼容。

此外，有些功能仍在开发中，预计会根据真实客户用例和反馈快速跟进与演进。 示例包括创建自定义操作和版本堆栈的功能。 如果之前在我们旧版 API 中提供的功能现在似乎缺失了，很可能是已经有了替代方案，或者很快就会推出，但我们想听听您的意见。

在深入了解 V4 API 之前，首先理解 Frame.io 版本 4 应用程序中表达的核心概念会很有帮助。 一个很好的起点就是 [Frame.io V4 知识库](https://help.frame.io/zh-CN/)。 帐户、用户、工作区、项目、收藏集、共享项和自定义字段（元数据）等概念在 V4 API 中已建模为不同的资源，了解它们在应用程序中的关系和功能将有助于理解它们在 V4 API 中的工作原理。

## API 概述

Frame.io V4 API 的设计遵循 RESTful 架构原则，并使用标准的 HTTP 方法和响应代码，以及特定于资源的唯一 URL。 Frame.io 发布了我们 V4 API 的 [OpenAPI 3.0 规范](https://api.frame.io/v4/openapi.json)，其中提供了有关其端点、请求参数和响应的详细信息。 OpenAPI 规范可供各种第三方代码生成工具使用，促进客户端应用程序的快速开发。

### URL 和路径约定

OpenAPI 规范中发布的 URL 路径通常反映资源所有权和包含关系。 因此，一些请求参数（例如帐户 ID、文件夹 ID 等） 嵌入在资源路径中。 虽然这些路径旨在具有可预测性且易于理解，但 API 请求返回的某些 URL 结构（例如预签名上传 URL 或显示链接）可能会发生变化，绝不应由客户端应用程序直接组成。

### 请求查询参数

控制分页行为以及在响应对象中可选地包含相关资源的请求参数被定义为一组标准查询参数：`include`、`page_size`、`include_total_count`。 有些请求可能支持特定于该资源或操作的其他查询参数。

```html
GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true
```

### 请求和响应负载

请求和响应负载均由 JSON 对象组成，因此，HTTP POST、PUT 或 PATCH 请求的 content-type 标头必须指定 `application/json` 媒体类型。 在创建或更新资源时，请求的 `data` 属性必须包含资源对象。 正在创建或更新的资源的属性包含在此对象中。 同样，包含资源的成功响应也将在响应的 `data` 属性内提供这些资源。

### 分页

可能返回大量资源对象的响应（例如文件夹或评论列表）会进行分页处理，从而减少结果集增大时的请求延迟。这意味着对请求的响应可能只包含一个“页面”的结果。 如上所述，客户端可以在发出请求时通过 `page_size` 查询参数选择特定的页面大小，最多可以选择 100 个元素。 如果未指定，页面大小将默认为 50 个元素。 V4 API 使用一种称为 *基于光标的分页* 形式，且在响应对象的 `links` 属性中包含一个相对链接（请参见下面的示例），该链接在 `after` 查询参数中包含一个不透明的光标字符串（客户端不应尝试自行构造此字符串），这允许客户端通过发出后续请求来检索下一页结果（请参见下面的示例响应）。 目前，V4 API 仅支持单向分页。

```json
{
    "data": [
        {
            "created_at": "2024-10-02T00:22:44.887775Z",
            "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
            "file_size": 102432,
            "id": "df171f3e-c95f-4454-9071-825cd924b572",
            "media_type": "application/pdf",
            "name": "sample.pdf",
            "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
            "project": {
                "created_at": "2024-08-21T17:45:41.881596Z",
                "description": "For demonstration purposes",
                "id": "976dd413-a92b-4af6-b465-98aded0174a8",
                "name": "Demo Project",
                "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
                "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
                "storage": 20881946,
                "updated_at": "2024-10-02T00:22:47.168489Z",
                "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
            },
            "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
            "status": "created",
            "type": "file",
            "updated_at": "2024-10-02T00:22:44.927993Z"
        }
    ],
    "links": {
        "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
    },
    "total_count": 21
}
```

### 错误

如果发生错误，响应对象中的 `errors` 属性将包含一个或多个错误对象的数组，它们会提供有关发生的错误的详细信息。 目前，V4 API 不支持批处理操作，因此没有客户端必须处理部分成功和错误的情况。

```json
{
    "errors": [
        {
            "detail": "Unexpected field: foo",
            "source": {
                "pointer": "/data/foo"
            },
            "title": "Invalid value"
        }
    ]
}
```

下表列出了 V4 API 使用的常见状态代码。

| 状态代码 | **状态** | 描述                                                                          |
| ---- | ------ | --------------------------------------------------------------------------- |
| 200  | 确定     | 请求成功。                                                                       |
| 201  | 已创建    | 资源已创建。                                                                      |
| 204  | 无内容    | 资源已删除。 无响应负载。                                                               |
| 400  | 无效请求   | 请求无效，通常是由于参数或负载格式不正确或缺失。                                                    |
| 401  | 未授权    | 授权令牌缺失或无效。                                                                  |
| 403  | 已禁止    | 授权令牌对此请求没有足够的权限。                                                            |
| 404  | 未找到    | 请求的资源不存在。                                                                   |
| 422  | 实体无法处理 | 请求负载和/或参数格式正确，但在其他方面无效，因此无法执行请求（与 400 Bad Request 基本一样）。                    |
| 429  | 请求过多   | 请求已超出此帐户的 API 速率限制。 请参阅《快速入门指南》中的“速率限制”部分了解详细信息。                            |
| 5xx  | 服务器错误  | 我们的服务器报告了一个意外错误。 客户端应至少等待 30 秒后再重试该事件，任何自动重试都应受到限制并包含随机间隔，此外还应在连续请求中采用指数退避。 |

### 身份验证和授权

V4 API 依赖于 OAuth 2.0 和 [Adobe Identity Management Server (IMS)](https://experienceleague.adobe.com/en/docs/commerce-admin/start/admin/ims/adobe-ims-integration-overview) 来验证用户身份 (AuthN) 并代表该用户生成访问令牌。 每个 API 请求都必须通过 HTTP Authorization 标头提供访问令牌（即持有者令牌身份验证）。

> **Note**
>
> 由 IMS 生成的[令牌范围](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/ims#scopes)是静态的，该授权 (AuthZ) 确定用户可以执行哪些操作（以及 API 可代表该用户执行哪些操作），这由 Frame.io 中授予用户的角色和权限决定。 有关生成和请求访问令牌的更多详细信息，请参阅“Developer Console 快速入门”和“身份验证设置”（在“使用 Postman 开始开发”下）部分。

### 版本和向后兼容性

Frame.io V4 API 与早期版本的 Frame.io API *不*向后兼容，通常无法用于访问或更新旧版帐户中包含的资源，因为 V4 概念和数据模型发生了重大变化。 因此，与 V4 API 相关的 URI 均包含 `/v4` 路径前缀。 但是，V4 API 仍在快速演进，新功能可能偶尔会产生重大更改。 更常见的情况是，Frame.io 将发布 API 的全新*增补*，我们认为这些增补在一段时间内属于实验性质，这样我们就可以接收和回复客户反馈和用法指标。 考虑到向后兼容性对于管理生产-质量集成且有高正常运行时间要求的客户来说是一个主要问题，我们正在设计 V4 API，以通过自定义 HTTP 标头支持额外的版本控制级别，以便允许客户端选择使用实验性端点，避免破坏性更改，并在 V4 命名空间内提供向后兼容性保证。 更多详细信息即将发布，但目前可以肯定的是，V4 API 的初始版本比较稳定，一段时间之后我们才会考虑引入重大变更。

### 速率限制

所有 V4 API 调用都受到速率限制，每个 API 资源和操作均配置有自己的限制。限制范围从低至每分钟 10 次请求到高达每秒 100 次请求不等。 目前，每项限制都由*用户*强制执行，但策略和限制本身可能会发生变化。

V4 API 使用“[漏桶](https://wikipedia.org/wiki/Leaky_bucket)”渐进式速率限制算法，其中限制会在其分配的时间窗口内逐渐刷新。 换句话说，不存在某种硬性截止时间点，到达后某个特定资源的限制就会刷新（即“固定窗口”和“滑动窗口”强制策略）。 相反，剩余限制会以与资源限制和时间窗口相对应的速率持续刷新。 超过特定端点速率限制的请求将失败，并出现 429 HTTP 错误。

我们针对响应 429 错误的推荐策略通常称为“指数退避”。

简而言之：

* 在收到 `429` 时，先暂停一段时间（至少一秒），然后重试请求
* 如果又收到一个 `429`，则以指数方式增加等待时间，或至少将前一次的时间加倍，直到恢复正常功能

为了确定适用于特定请求的速率限制，客户端可以检查响应中返回的以下 HTTP 标头：

| 标头                      | 值描述                        |
| ----------------------- | -------------------------- |
| `x-ratelimit-limit`     | 此资源路径的速率限制，以请求次数为单位。       |
| `x-ratelimit-remaining` | 当前时间窗口内剩余的请求次数。            |
| `x-ratelimit-window`    | 此资源路径限制的时间窗口，以毫秒 (ms) 为单位。 |

## API 详细信息

V4 API 的权威文档是我们的[API 参考指南](/platform/api-reference/)，但在发出第一个请求之前，了解 V4 API 建模的资源层级会很有帮助。

### 资源层级

[帐户](https://help.frame.io/zh-CN/collections/8779087-account-settings)通常与组织相关联，代表决定订阅计划、内容所有权、用户角色/权限和工作区组织的基本资源。 因此，几乎 V4 API 中所有端点的 URL 路径都包含一个前缀，用于标识资源所在的帐户。 工作区（以前在 Frame.io 的旧版本中称为团队）和[项目](https://help.frame.io/zh-CN/articles/9101006-project-settings)用于组织内容和用户，其中包括谁有权访问哪些内容。

Frame.io 中内容资源的基本层级如下：

#### 资源层级

**帐户 → 工作区 → 项目 → 文件夹 → 文件夹/版本堆栈/文件**

上传到 Frame.io 的每个资产最终都表示为[文件](https://help.frame.io/zh-CN/articles/9436564-supported-file-types-on-frame-io)，而[文件夹](https://help.frame.io/zh-CN/articles/9101044-creating-folders)和[版本堆栈](https://help.frame.io/zh-CN/articles/9101068-version-stacking)是充当容器的存储资源，为支持版本化资产的分级存储模型提供基础。 大多数用户已经熟悉 Frame.io 中文件夹的基本概念：它只是作为其他存储资源（建模为其`次项`）的无序容器，且代表文件夹树中的一个节点。 每个项目都有一个唯一的根文件夹（通过 `root_folder_id` 键进行标识），充当项目所有资产所处文件夹树的根目录。

版本堆栈是文件的有序容器。 其排序严格线性，并为每个次项确定版本号，但客户端可以根据需要对版本堆栈中的文件重新排序。 在任何给定时间，文件始终是恰好一个文件夹*或*版本堆栈的次项（包含在其中）。 同样地，文件夹或版本堆栈始终恰好是一个文件夹的次项（不包括项目的根文件夹）。

有关对存储在 Frame.io 内的文件和文件夹执行基本 CRUD 操作的更多详细信息，请参阅 [API 参考指南](../api/current/)。 目前，V4 API 仅在列出文件夹内容时支持版本堆栈，但用于创建和更新版本堆栈的端点即将推出。

## SDK

SDK 适用于 TypeScript 和 Python。 您可以使用以下命令安装它们。 文档的 SDK 参考部分包含 [Python](/platform/docs/sdk-reference/python-sdk-reference) 和 [TypeScript](/platform/docs/sdk-reference/typescript-sdk-reference) SDK 的完整参考。

### TypeScript

```bash
npm i -s frameio
```

在 [npm](https://www.npmjs.com/package/frameio) 上查看

### Python

```bash
pip install frameio
```

在 [PyPi](https://pypi.org/project/frameio/) 上查看