> This page is for Plataforma, version Herdado.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - Herdado: 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.

# Gerenciar pilha de versões

## Visão geral




As pilhas de versões são um princípio organizacional no Frame.io que permite que os ativos sejam "empilhados" verticalmente sem serem colocados em pastas.As versões empilhadas facilitam a navegação de ativo para ativo na IU do Frame.io e oferecem suporte à revisão lado a lado.





No momento, não oferecemos suporte ao upload direto em uma pilha, portanto, a sequência da API para gerenciar o fluxo de trabalho básico da pilhas de versões seguirá a mesma sequência da IU do Frame.io:




1. Faça upload do ativo (opcional: marque como privado).
2. Atribua o ativo à pilha.





As pilhas de versões existentes podem ser reordenadas e versões individuais podem ser removidas de uma pilha.Por fim, as pilhas de versões podem ser excluídas sem excluir nenhum de seus ativos constituintes.




<Info title="Todas as pilhas de versões têm um cover_asset">
  As pilhas de versões sempre terão um atributo chamado `cover_asset_id` no nível superior.Este é o `id` do ativo cuja miniatura é exibida na interface web do Frame.io e é a versão com número mais alto na pilha.
</Info>


### Conceitos principais

**Pilhas de versões**, assim como **pastas**, são `tipos` especiais de ativos.Você pode buscá-las com os mesmos pontos de acesso e, com base no valor da chave `type` na resposta da API, analisar e rotear adequadamente.Isso geralmente é simples na prática, mas pode apresentar algumas complicações ao gerenciar pilhas em grande escala.A chave para trabalhar com pilhas de versões é separar os **quatro cenários mais comuns**:
1. Um ativo pode ser adicionado a um ativo, o que criará uma pilha com um novo `id`.
2. Um ativo pode ser adicionado a uma pilha existente.
3. Uma pilha pode ser reordenada.
4. Versões individuais podem ser removidas.

**Os dois primeiros cenários** usam a mesma [chamada de ponto de acesso](ref:post_assets-assetid-version), portanto, a única nuance real é saber se você está criando uma nova pilha (de dois ativos) ou adicionando seu ativo a uma pilha existente.Além disso, as restrições são previsíveis:
1. As pilhas devem corresponder ao `asset_type` (por exemplo, você não pode empilhar uma *imagem* em um *fluxo*).
2. O usuário ativo deve ter permissões para o ativo de origem e o ativo ou pilha de destino.
3. Empilhe ativos sequencialmente.
4. Não é possível empilhar uma pilha em uma pilha.
5. Pastas estão totalmente fora de questão.

**Os dois últimos cenários** também são bem simples, mas exigem saber um pouco mais sobre a pilha em si.Por exemplo, para reordenar um ativo em uma pilha, você precisará saber os `id`s dos ativos em ambos os lados de onde deseja que seu ativo de destino seja posicionado, e isso geralmente significa que você já buscou a pilha inteira.

### Escopos obrigatórios




Antes de começar este guia, você precisará se certificar de que possui um token que inclua os seguintes escopos:




| Escopo | Motivo |
| ---------- | ---------- |
| **Ativos:** Leitura, atualização | - Buscar ativos de origem e destino.<br />- Adicionar um ativo a uma pilhas de versões.<br />- Reordenar uma pilha.<br />- Remover um ativo de uma pilha.<br />- Excluir uma pilha. |




## Adicionar ativos às pilhas de versões




### Etapa 1: localizar seu destino




A primeira etapa é identificar em qual dos dois cenários principais você se encontra: adicionar um ativo a outro ativo para criar uma pilha ou adicionar um ativo a uma pilha para ampliá-la.

Se você sabe que está trabalhando com um ativo sem versão, ou já tem um `id` da pilhas de versões, pode prosseguir para a Etapa 2.

Caso contrário, a maneira mais fácil de determinar se um ativo de destino já faz parte de uma pilha é:




1. Faça o `GET` do seu ativo de destino através de chamada para `/v2/assets/:id​`
2. Verifique o `type` que retorna.


  

* Se for *version_stack*, o uuid que você acabou de verificar é seu uuid de destino.Prossiga para a Etapa 2.



3. Se o `type` for *file*, pegue o `parent_id`
4. Faça o GET do principal por meio do mesmo ponto de acesso e verifique seu `type`.

Se o `type` do principal for *version_stack*, use o `id` como seu destino.Se o `type` for qualquer outra coisa, você está lidando com um ativo comum e pode usar o id original como seu destino.

### Etapa 2: preparar seu conteúdo




Agora que você tem seu uuid de destino, precisa saber o uuid do ativo que está adicionando à pilha.




1. Se você estiver fazendo upload de um novo ativo, simplesmente use o id retornado com a resposta de sucesso quando você [criar o ativo](ref:post_assets-parentid-children).
2. Se você estiver empilhando um ativo existente, você deve ter o `id` através do processo descrito acima.

O único parâmetro de corpo necessário para uma adição de pilha de versões é `next_asset_id`:

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




### Etapa 3: adicionar seu ativo de origem ao destino

Agora que você tem ambos os parâmetros `id` do ativo, você está pronto para fazer `POST` para `/assets/:id/version`, onde o :id é seu ativo de destino ou pilhas de versões, e seu ativo de origem (novo) está no conteúdo do corpo.

## Reordenar as pilhas de versões

As pilhas de versões dependem de um conceito ordinal simples de cada ativo ter vizinhos `next_asset_id` e `prev_asset_id`, onde a ordem se refere não à numeração da versão, mas ao atributo `index` de cada ativo.O `index` funciona oposto aos números de versão, então consequentemente:
* A primeira versão (numerada mais baixa) na pilha tem um ativo `prev`, mas nenhum ativo `next`
* A versão mais recente (numerada mais alta) na pilha tem um ativo `next`, mas nenhum ativo `prev`
* Todas as versões &quot;internas&quot; têm um ativo `prev` e `next`, que são os ativos com IDs de versão mais altos e mais baixos, respectivamente.




Isso nos dá três cenários distintos, todos dependem da mesma chamada de ponto de acesso:

**Chamada:**

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

**Corpo:**

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

Em todos os casos, o `id` no caminho do URL será o ativo que você está movendo.
| Cenário | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| Mover para o topo da pilha | `null` | `id` do ativo do topo anterior (número de versão mais alto). |
| Mover para o final da pilha | `id` do ativo final anterior (v1). | `null` |
| Mover versão dentro de uma pilha | `id` do ativo logo *acima* de onde você gostaria de mover seu ativo. | `id` do ativo logo *abaixo* de onde você gostaria de mover seu novo ativo. |




## Remover ativos e excluir pilhas de versões




### Remover ativos




Quando um ativo é movido para uma pilhas de versões, ele se torna um filho da própria pilha.Para remover um ativo de uma pilha de versões, o que você precisa fazer é, na prática, reatribuir sua hierarquia de principal à pasta que contém a pilha.




1. `GET` a própria pilha de versões por meio de uma chamada para `/v2/assets/:id`
2. Obtenha o `parent_id` da própria pilha (que se tornará o `id` da sua nova pasta de destino)
3. Mova o ativo de destino para a pasta da seguinte forma:

**Chamada**:

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

**Corpo**:

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





### Excluir pilhas de versões




Excluir uma pilhas de versões é extremamente simples:





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





Pronto.Excluir uma pilha retornará todos os ativos constituintes para a pasta que contém a pilha.




<Info title="Pilhas de tamanho 1 devem ser excluídas">
  Se você remover todos os elementos de uma pilha de versões, você ficará com uma pilha de versões com um único elemento nela.Isso é fácil de identificar: se você `GET` a pilha de versões pelo `id`, verá que ela tem um atributo de `&quot;version&quot;: 1`.
</Info>


Tecnicamente, tudo isso está correto. A versão singleton será carregada e reproduzida, novas versões podem ser adicionadas e tudo continuará normalmente. No entanto, para evitar causar confusão aos usuários no site do Frame.io e em outros aplicativos, recomendamos excluir as pilhas singleton.

Para mais informações sobre o ponto de acesso da pilha de versões, consulte a documentação [Ativos](ref:assets).