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

# 关键概念

## API 结构




Frame.io API 支持一些常见概念，如速率限制、资源集合的分页、版本控制和错误处理。本节将介绍每种概念的具体细节。




### 组织与风格

API 围绕常见的 [REST](https://restfulapi.net/) 原则进行组织。所有请求都应通过 SSL 发起。所有请求和响应体（包括错误消息）均采用 JSON 格式编码。

除非另有说明，API 方法均遵循以下规范：

* 没有值的属性将使用 `null`，而不是保留为未定义状态 * 属性名称使用“蛇形命名法”（例如：`first_name`） * 时间戳以 ISO-8601 格式呈现（例如：`2016-02-03T16:38:46.985Z`）

### 路径约定




帐户 > 团队 > 项目 > 资产 > 评论





通常，Frame.io API 中的资源路径将遵循上述层级结构模型，深度不超过一个主层级。在直观的情况下，API 支持对逻辑上严格归属某个对象的资源使用独立路径。





例如，Frame.io API 同时支持以下两种路径：

* `GET /accounts/:id/teams` -- 返回帐户下的所有团队。* `GET /teams` -- 返回调用用户的所有团队。* `GET /teams/:id` -- 返回有关特定团队的详细信息。

再举一个例子：评论在其所属资产上下文之外意义不大，因此评论的收集和创建方法都位于资产范围内。但是，如果更新或删除一条评论，资产上下文就不再那么重要，因此会从资源路径中省略：

* `GET /assets/:id/comments` * `POST /assets/:id/comments` * `PUT /comments/:id` * `DELETE /comments/:id`

## 权限范围

无论是通过 OAuth2.0，还是直接通过[开发者门户](/)获取令牌，所有 API 令牌都必须关联一个明确的“权限范围”列表，这些权限范围是指资源（例如 `Asset`）和操作（例如 `create`）的组合，并使用点标记法来表示。例如，具有 `asset.create` 权限范围的令牌将能够创建新的资产。

如果您使用的是开发者令牌的实施方式，那么权限范围会被设置并分配给访问令牌本身。如果您使用的是 OAuth 应用程序，则会为该应用程序定义权限范围，当用户首次与应用程序交互时，他们会同意授权该应用程序使用所请求的权限范围进行操作。





开发者令牌和应用程序可用的权限范围包括以下内容（请注意，某些权限范围并非对所有人开放，出现问题时会特别说明）。




| 权限范围类别 | 描述 |
| ---------- | ---------- |
| 帐户、用户和团队 | 获取您有权访问的帐户和团队的信息。如果经过身份验证的用户是管理员等，他们可能有权访问自己帐户中其他用户和团队的相关信息。<br /><br />**注意**：要更新团队（例如管理 Webhook），您必须拥有团队经理或帐户管理员角色。 |
| 项目和资产 | 获取项目的基本信息，检查或更新用户的成员身份，创建或更新资产 |
| 评论 | 获取、创建或删除资产上的评论，或对特定评论发表回复。<br /><br />**注意：**更新或删除评论的请求必须由评论创建者执行。 |
| 审阅链接 | 创建审阅链接或管理其上的设置。<br /><br />**注意：**审阅链接是 Frame.io 的一项核心功能，用于收集资产，并通过单个 URL 发送给他人以获取反馈，无需明确的团队或项目访问权限。 |
| Webhook | Webhook 提供了一种方式，可以将 Frame.io 内部发生的事件转化为通知，这些通知可以发送到外部系统进行处理、作为 API 回调，并最终实现工作流自动化。 |
| 审核日志 | Frame.io 会显示其应用程序中绝大多数活动的日志。这包括对核心资源的基本增删改查 (CRUD) 操作，以及一些特殊的抽象处理（例如 `AssetVersioned`）。您必须是管理员才能访问日志。 |
| 演示文稿 |




## 分页




返回结果集合的 API 方法始终采用分页形式。所有预期返回分页结果的方法都会响应以下查询参数，并返回以下标头属性：




| 描述 | 查询参数 | 标头属性 |
| ---------- | ---------- | ---------- |
| 页面大小 | `page_size` | `per-page` |
| 页码 | `page` | `page-number` |
| 页数 | 不适用 | `total-pages` |
| 总数 | 不适用 | `total` |
此外，分页结果将包含一个 `Link` 响应标头（[请参阅 RFC-5988](https://tools.ietf.org/html/rfc5988)），其中包含以下信息：
* `next` -- 对应的 URL 是指向下一页的链接。
* `prev` -- 对应的 URL 是指向上一页的链接。
* `last` -- 对应的 URL 是指向最后一页的链接。

**注意：**当 `next` 和 `prev` 链接都不存在时，则表示返回的首页就是唯一的一页。