> 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 웹 UI에 썸네일이 표시되는 에셋의 `id`이자, 스택에서 가장 높은 번호가 매겨진 버전을 의미합니다.
</Info>


### 핵심 개념

**버전 스택**은 **폴더**와 마찬가지로 특별한 `유형`의 에셋입니다. 동일한 엔드포인트로 가져올 수 있으며, API 응답의 `type` 키 값에 따라 구문 분석하고 적절히 라우팅할 수 있습니다. 이는 실제로는 대체로 간단하지만, 대규모로 스택을 관리할 때는 몇 가지 까다로운 부분이 있을 수 있습니다. 버전 스택 작업의 핵심은 **가장 일반적인 4가지 시나리오**를 분리하는 것입니다.
1. 에셋을 다른 에셋에 추가하면 새 `id`를 가진 스택이 생성됩니다.
2. 기존 스택에 에셋을 추가할 수 있습니다.
3. 스택 순서를 바꿀 수 있습니다.
4. 개별 버전을 제거할 수 있습니다.

**처음 두 시나리오**는 동일한 [엔드포인트 호출](ref:post_assets-assetid-version)을 사용하므로, (두 개의 에셋에서) 새 스택을 생성하는 것인지 아니면 기존 스택에 에셋을 추가하는 것인지 파악하는 것이 유일한 차이점입니다. 그 외에 제약 조건은 예측 가능합니다.
1. 스택은 `asset_type`이 일치해야 합니다(예: *stream* 에셋 위에 *image* 에셋을 스택할 수 없음).
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`를 이미 확보한 상태여야 합니다.

버전 스택 추가에 필요한 유일한 body 매개변수는 `next_asset_id`입니다.

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




### 3단계: 대상에 소스 에셋 추가

이제 두 에셋 `id` 매개변수를 모두 얻었으므로 `/assets/:id/version`에 `POST` 요청을 보낼 준비가 되었습니다. 여기서 :id는 대상 에셋 또는 버전 스택이며, 소스(새) 에셋은 본문 페이로드에 포함됩니다.

## 버전 스택 순서 바꾸기

버전 스택은 각 에셋에 `next_asset_id`와 `prev_asset_id` 이웃이 있다는 단순한 서열 개념에 의존합니다. 여기서 순서는 버전 번호가 아니라 각 에셋의 `index` 속성을 나타냅니다. `index`는 버전 번호와 반대로 적용되므로 다음과 같습니다.
* 스택의 첫 번째(가장 낮은 번호의) 버전에는 `prev` 에셋이 있지만 `next` 에셋은 없습니다.
* 스택의 더 최근(가장 높은 번호의) 버전에는 `next` 에셋이 있지만 `prev` 에셋은 없습니다.
* 모든 &quot;내부&quot; 버전에는 `prev` 에셋과 `next` 에셋이 모두 있으며, 이는 각각 더 높고 더 낮은 버전 ID를 가진 에셋입니다.




이는 세 가지 고유한 시나리오를 제공하며, 모두 동일한 엔드포인트 호출에 의존합니다.

**호출:**

```
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 경로의 `id`는 이동하려는 에셋이 됩니다.
| 시나리오 | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| 스택의 맨 위로 이동 | `null` | 이전의 최상위 에셋(가장 높은 버전 번호)의 `id`입니다. |
| 스택의 맨 아래로 이동 | 이전의 최하위 에셋(v1)의 `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":"&lt;asset_id&gt;"
}
```





### 버전 스택 삭제




버전 스택을 삭제하는 것은 매우 간단합니다.





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





이것이 전부입니다. 스택을 삭제하면 이를 구성하는 모든 에셋이 스택이 포함된 폴더로 돌아갑니다.




<Info title="크기가 1인 스택은 삭제해야 합니다.">
  버전 스택에서 요소를 모두 제거하면 단일 요소가 포함된 버전 스택만 남게 됩니다. 이는 쉽게 알아볼 수 있습니다. `id`로 버전 스택을 `GET` 요청하면 `&quot;version&quot;: 1`이라는 속성을 가지고 있음을 확인할 수 있습니다.
</Info>


이 모든 상황은 기술적으로 문제없습니다. 싱글톤 버전도 로드 및 재생되고 새 버전을 추가할 수도 있으며 모든 것이 정상적으로 작동합니다. 하지만 Frame.io의 웹 및 기타 애플리케이션에서 사용자에게 혼란을 주는 상황을 피하려면 싱글톤 스택을 삭제하는 것을 권장합니다.

버전 스태킹 엔드포인트에 대한 자세한 내용은 [에셋](ref:assets) 설명서를 참조하세요.