> 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.

# 管理版本堆栈

## 概述




版本堆栈是 Frame.io 中的一种组织原则，它可以让资产垂直“堆叠”，而无需放进文件夹里。堆叠后的版本使得在 Frame.io UI 中更容易地在资产之间进行导航，并支持并排审阅。





我们目前不支持直接上传到堆栈中，因此管理基本版本堆栈工作流的 API 序列将与 Frame.io UI 的序列相同：




1. 上传资产（可选：标记为私有）。
2. 将资产分配到堆栈中。





现有版本堆栈可以重新排序，单个版本可以从堆栈中移除。最后，版本堆栈可以删除，而不会删除其任何组成资产。




<Info title="所有版本堆栈都有一个 cover_asset">
  版本堆栈在其顶层始终有一个名为 `cover_asset_id` 的属性。这是其缩略图显示在 Frame.io Web UI 中的那个资产的 `id`，并且该资产是堆栈中版本号最高的版本。
</Info>


### 核心概念

**版本堆栈**与**文件夹**一样，都是资产的特殊`类型`。您可以使用相同的端点来获取它们，并根据 API 响应中 `type` 键的值进行相应的解析和路由。这在实际操作中通常很简单，但在大规模管理堆栈时可能会遇到一些小问题。使用版本堆栈的关键在于区分以下**四种最常见的场景**：
1. 一个资产可以添加到另一个资产上，这将创建一个带有新 `id` 的堆栈。
2. 一个资产可以添加到现有堆栈中。
3. 可以重新排序堆栈。
4. 可以移除单个版本。

**前两种场景**使用相同的[端点调用](ref:post_assets-assetid-version)，因此唯一真正的细微差别在于要知道您是在用两个资产创建一个新的堆栈，还是将您的资产添加到现有堆栈中。除此之外，其限制条件是可预见的：
1. 堆栈中的 `asset_type` 必须匹配（例如，您不能将 *图像* 堆叠到 *视频流* 上）。
2. 操作用户必须对源资产和目标资产或堆栈都有权限。
3. 资产按顺序堆叠。
4. 您不能将一个堆栈堆叠在另一个堆栈上。
5. 文件夹则完全不行。

**后两种场景**也非常简单，但需要对堆栈本身有更多的了解。例如，要对堆栈中的资产进行重新排序，您需要知道目标资产将放置位置两侧的资产的 `id`；这通常意味着您已经获取了整个堆栈的信息。

### 必需的权限范围




在开始本指南之前，您需要确保拥有一个包含以下权限范围的令牌：




| 权限范围 | 原因 |
| ---------- | ---------- |
| **资产：**读取、更新 | - 获取源资产和目标资产。<br />- 将资产添加到版本堆栈中。<br />- 对堆栈重新排序。<br />- 从堆栈中移除资产。<br />- 删除堆栈。 |




## 将资产添加到版本堆栈




### 步骤 1：定位您的目标




第一步是要确定您正处于两种关键场景中的哪一种——是将一个资产添加到另一个资产以创建一个堆栈，还是将一个资产添加到一个堆栈中以扩展该堆栈。

如果您知道自己正在使用一个尚未版本化的资产，或者您已拥有一个版本堆栈 `id`，则可以进入步骤 2。

如果不是这样，判断目标资产是否已经属于某个堆栈的最简单方法是：




1. 通过调用 `/v2/assets/:id​` 来 `GET` 您的目标资产
2. 检查返回结果中的 `type` 值。


  

* 如果是 *version_stack*，那么您刚才检查的 uuid 就是您的目标 uuid。进入步骤 2。



3. 如果 `type` 值是 *file*，则获取 `parent_id`
4. 通过同一端点 GET 主项，并检查其 `type` 值。

如果主项的 `type` 是 *version_stack*，则使用其 `id` 作为您的目标。如果 `type` 是其他任何值，那么您正在处理的是一个普通资产，可以直接使用原始 id 作为目标。

### 步骤 2：准备您的负载




现在您已经有了目标 uuid，您需要知道要添加到堆栈中的资产的 uuid。




1. 如果您要上传新的资产，只需使用[创建资产](ref:post_assets-parentid-children)时成功响应中返回的 id 即可。
2. 如果您要堆叠现有资产，您应该已通过上述流程获得了它的 `id`。

添加版本堆栈时所需的唯一请求体参数是 `next_asset_id`：

```json
{
    "next_asset_id": "<source-asset-id>"
}
```




### 步骤 3：将源资产添加到目标位置

现在您已拥有两个资产 `id` 参数，可以发起 `POST` 请求 `/assets/:id/version`，其中 :id 是您的目标资产或版本堆栈，而您的源（新）资产则在请求体中。

## 重新排序版本堆栈

版本堆栈依赖于一个简单的顺序概念：每个资产都拥有 `next_asset_id` 和 `prev_asset_id` 相邻项，其中顺序不是指版本编号，而是指每个资产的 `index` 属性。`index` 与版本号的顺序相反，因此相应地：
* 堆栈中的第一个（版本号最低的）版本拥有 `prev` 资产，但没有 `next` 资产
* 堆栈中的最新（版本号最高的）版本拥有 `next` 资产，但没有 `prev` 资产
* 所有“中间”的版本同时拥有 `prev` 和 `next` 资产，分别是版本 ID 较高和较低的资产。




这为我们提供了三种不同的场景，它们都依赖于同一个端点调用：

**调用：**

```
PUT https://api.frame.io/v2/asset/:id/tween
```

**请求体：**

```json
{
  "prev_asset_id": "<asset_id>",
  "next_asset_id": "<asset_id>"
}
```

在所有情况下，URL 路径中的 `id` 都将是您要移动的资产。
| 场景 | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| 移动到堆栈顶部 | `null` | 之前顶部资产（版本号最高）的 `id`。 |
| 移动到堆栈底部 | 之前底部资产（版本 1）的 `id`。 | `null` |
| 在堆栈内移动版本 | 您希望将资产移动到的位置紧 *上方* 资产的 `id`。 | 您希望将新资产移动到的位置紧 *下方* 资产的 `id`。 |




## 移除资产与删除版本堆栈




### 移除资产




当一个资产移动到版本堆栈中时，它就成为该堆栈本身的次项。要将一个资产从版本堆栈中移出，您需要做的实际上就是将其重新设为堆栈所在文件夹的主项。




1. 通过调用 `/v2/assets/:id` 来 `GET` 版本堆栈本身
2. 获取堆栈本身的 `parent_id`（这将成为您的新目标文件夹 `id`）
3. 将您的目标资产按如下方式移动到该文件夹中：

**调用**：

```
POST https://api.frame.io/v2/assets/:parent_id/move
```

**请求体**：

```json
{
    "id":"<asset_id>"
}
```





### 删除版本堆栈




删除版本堆栈非常简单：





```
DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion
```





就是这样。删除堆栈会将其所有的组成资产返回到该堆栈所在的文件夹中。




<Info title="大小为 1 的堆栈应该被删除">
  如果您从一个版本堆栈中移除了所有元素，最终会得到一个只包含单个元素的版本堆栈。这很容易发现——如果您通过其 `id` 来 `GET` 版本堆栈，您会看到它有一个属性 `&quot;version&quot;: 1`。
</Info>


从技术上讲，这一切都没问题——这个单例版本可以加载和播放，可以添加新版本，一切都会正常进行；但是，为了避免在 Frame.io Web 版及其他应用程序中给用户造成困惑，我们建议删除单例堆栈。

有关版本堆栈端点的更多信息，请参阅[资产](ref:assets)文档。