> 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
> - Версия 4 экспериментальная: 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 и поддерживают параллельный просмотр.





В настоящее время мы не поддерживаем прямое добавление в стек, поэтому последовательность API-интерфейса для управления базовым рабочим процессом стека версий будет следовать той же последовательности, что и в пользовательском интерфейсе Frame.io:




1. Добавление ресурса (по желанию: пометьте как частный).
2. Назначение ресурса в стек.





Существующие стеки версий можно переупорядочить, а отдельные версии можно исключить из стека. Наконец, стеки версий можно удалить, не удаляя ни один из составляющих их ресурсов.




<Info title="Все стеки версий имеют cover_asset">
  Стеки версий всегда имеют атрибут `cover_asset_id` на верхнем уровне. Это `ИД` ресурса, миниатюра которого отображается в веб-интерфейсе Frame.io и является версией с наибольшим номером в стеке.
</Info>


### Основные концепции

**Стеки версий**, как и **папки**, — это специальные `типы` ресурсов. Вы можете получить их с помощью тех же конечных точек, и на основе значения ключа `тип` в ответе API-интерфейса выполнять анализ и маршрутизацию соответствующим образом. Как правило, на практике это просто, но может представлять некоторые сложности при масштабном управлении стеками. Ключ к работе со стеками версий заключается в разделении **четырех наиболее распространенных сценариев**:
1. Ресурс можно добавить к ресурсу, что создаст стек с новым `ИД`.
2. Ресурс можно добавить к существующему стеку.
3. Стек можно переупорядочить.
4. Отдельные версии можно удалить.

**Первые два сценария** используют один и тот же [вызов конечной точки](ref:post_assets-assetid-version), поэтому единственный реальный нюанс заключается в том, чтобы знать, создаете ли вы новый стек (из двух ресурсов) или добавляете свой ресурс к существующему стеку. Кроме того, ограничения предсказуемы:
1. Стеки должны совпадать по `asset_type` (например, нельзя разместить *image* в стеке со *stream*).
2. Действующий пользователь должен иметь разрешения как для исходного ресурса, так и для целевого ресурса или стека.
3. Последовательное размещение ресурсов в стеке.
4. Нельзя наложить стек на стек.
5. Папки исключены.

**Последние два сценария** также довольно просты, но требуют более глубокого понимания самого стека. Например, чтобы изменить положение ресурса в стеке, вам нужно знать `ИД` ресурсов по обеим сторонам от места, куда вы хотите поместить целевой ресурс; это обычно означает, что вы уже получили весь стек.

### Необходимые области доступа




Перед началом работы с этим руководством убедитесь, что у вас есть токен, который включает следующие области доступа:




| Область доступа | Причина |
| ---------- | ---------- |
| **Ресурсы:** чтение, обновление | - Получение исходных и целевых ресурсов.<br />- Добавление ресурса в стек версий.<br />- Переупорядочение стека.<br />- Удаление ресурса из стека.<br />- Удаление стека. |




## Добавление ресурсов в стеки версий




### Шаг 1. Поиск места назначения




Для начала определите, в каком из двух ключевых сценариев вы находитесь: добавляете ресурс к другому ресурсу для создания стека или добавляете ресурс к стеку для его расширения.

Если вы знаете, что работаете с неверсированным ресурсом, или у вас уже есть `ИД` стека версий, можете переходить к шагу 2.

Если нет, далее представлен самый простой способ определить, является ли целевой ресурс уже частью стека:




1. Выполнить запрос `GET` к вашему целевому ресурсу по адресу `/v2/assets/:id​`
2. Проверьте возвращаемый `тип`.


  

* Если это *version_stack*, uuid, который вы только что проверили, — это ваш целевой uuid. Переходите к шагу 2.



3. Если `тип` — это *файл*, возьмите `parent_id`.
4. Выполните запрос GET к родительскому элементу через ту же конечную точку и проверьте его `тип`.

Если `тип` родительского элемента — *version_stack*, используйте его `ИД` как место назначения. Если `тип` — это что-то другое, это обычный ресурс и можно использовать исходный ИД как место назначения.

### Шаг 2. Подготовка полезной нагрузки




Теперь, когда у вас есть целевой uuid, вам нужно знать uuid ресурса, который вы добавляете в стек.




1. Если вы добавляете новый ресурс, просто используйте идентификатор, полученный в ответе о выполнении, когда вы [создаете ресурс](ref:post_assets-parentid-children).
2. Если вы добавляете существующий ресурс в стек, у вас должен быть `идентификатор`, полученный в результате процесса, описанного выше.

Единственный параметр тела, необходимый для добавления в стек версий, — это `next_asset_id`:

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




### Шаг 3. Добавление исходного ресурса к целевому

Теперь, когда у вас есть оба параметра `идентификатора` ресурса, вы готовы выполнить запрос `POST` по адресу `/assets/:id/version`, где :id — это ваш целевой ресурс или стек версий, а исходный (новый) ресурс находится в теле запроса.

## Переупорядочение стеками версий

Стеки версий основаны на простой порядковой концепции, где у каждого ресурса есть соседи `next_asset_id` и `prev_asset_id`, при этом порядок относится не к нумерации версий, а к атрибуту `index` каждого ресурса. `index` идет в противоположном направлении от номеров версий, соответственно:
* Первая (с наименьшим номером) версия в стеке имеет `предыдущий` ресурс, но не имеет `следующего` ресурса.
* Более новая (с наибольшим номером) версия в стеке имеет `следующий` ресурс, но не имеет `предыдущего` ресурса.
* Все «внутренние» версии имеют как `предыдущий`, так и `следующий` ресурс, которые являются ресурсами с более высокими и более низкими идентификаторами версий соответственно.




Это дает нам три различных сценария, все из которых используют один и тот же вызов конечной точки:

**Вызов:**

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

**Тело:**

```json
{
  "prev_asset_id": "&lt;asset_id&gt;",
  "next_asset_id": "&lt;asset_id&gt;"
}
```

Во всех случаях `ИД` в пути URL-адреса будет ресурсом, который вы перемещаете.
| Сценарий | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| Переместить в верхнюю часть стека | `null` | `ИД` предыдущего верхнего ресурса (наибольший номер версии). |
| Переместить в нижнюю часть стека | `ИД` предыдущего нижнего ресурса (v1). | `null` |
| Переместить версию внутри стека | `ИД` ресурса прямо *над* местом, куда вы хотите переместить ваш ресурс. | `ИД` ресурса прямо *под* местом, куда вы хотите переместить ваш новый ресурс. |




## Удаление ресурсов и удаление стеков версий




### Удаление ресурсов




Когда ресурс перемещается в стек версий, он становится дочерним элементом самого стека. Чтобы переместить ресурс из стека версий, нужно эффективно вернуть его обратно в папку, содержащую стек.




1. Выполните запрос `GET` к стеку версий с помощью вызова `/v2/assets/:id`
2. Возьмите `parent_id` стека (который станет вашим новым `ИД` целевой папки)
3. Переместите целевой ресурс в папку следующим образом:

**Вызов**:

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

**Тело**:

```json
{
    "id":"&lt;asset_id&gt;"
}
```





### Удаление стеков версий




Удаление стека версий выполняется очень просто:





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





Вот и все. При удалении стека все составляющие его ресурсы возвращаются в папку, где располагался стек.




<Info title="Стеки размером в 1 элемент следует удалять">
  Если вы удалите все элементы из стека версий, в итоге вы получите стек, состоящий из одного элемента. Это легко заметить — если вы выполните запрос `GET` к стеку версий по его `ИД`, вы увидите атрибут `&quot;version&quot;: 1`.
</Info>


Все это технически допустимо — одиночная версия будет загружаться и воспроизводиться, в нее можно будет добавлять новые версии, и все будет работать как обычно. Однако, чтобы не создавать путаницы для пользователей в веб-приложении Frame.io и других приложениях, мы рекомендуем удалять одиночные стеки.

Для получения дополнительной информации о конечной точке стекирования версий см. документацию по [ресурс ам](ref:assets).