> This page is for Plataforma, version Heredado.
> 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
> - Heredado: 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.

# Administrar pilas de versiones

## Información general




Las pilas de versiones son un principio organizativo en Frame.io que permite que los activos se "apilen" verticalmente sin colocarlos en carpetas. Las versiones apiladas facilitan la navegación entre activos dentro de la IU de Frame.io y admiten la revisión en paralelo.





Actualmente, no admitimos la carga directa en una pila, por lo que la secuencia de API para administrar el flujo de trabajo básico de pila de versiones seguirá la misma secuencia que la IU de Frame.io:




1. Cargue el activo (opcional: márquelo como privado).
2. Asigne el activo a la pila.





Las pilas de versiones existentes se pueden reordenar y las versiones individuales se pueden sacar de una pila. Finalmente, las pilas de versiones se pueden eliminar sin quitar ninguno de sus activos constituyentes.




<Info title="Todas las pilas de versiones tienen un atributo cover_asset">
  Las pilas de versiones siempre tendrán un atributo llamado `cover_asset_id` en su nivel superior. Este es el `id` del activo cuya miniatura se muestra en la IU web de Frame.io, y es la versión con el número más alto en la pila.
</Info>


### Conceptos fundamentales

Las **pilas de versiones**, al igual que las **carpetas**, son `tipos` especiales de activos. Puede recuperarlos con los mismos puntos finales y, según el valor de la clave `type` en la respuesta de la API, se pueden analizar y enrutar según corresponda. Por lo general, esto es sencillo en la práctica, pero puede presentar algunas complicaciones cuando se administran pilas a escala. La clave para trabajar con pilas de versiones es separar los **cuatro escenarios más comunes**:
1. Se puede añadir un activo a un activo, lo que creará una pila con un `id` nuevo.
2. Se puede añadir un activo a una pila existente.
3. Se puede reordenar una pila.
4. Se pueden quitar versiones individuales.

**Los primeros dos escenarios** utilizan la misma [llamada de punto final](ref:post_assets-assetid-version), por lo que el único matiz real es saber si está creando una pila nueva (a partir de dos activos) o añadiendo su activo a una pila existente. Aparte de eso, las restricciones son predecibles:
1. Las pilas deben coincidir en `asset_type` (por ejemplo, no puede apilar una *imagen* en un *flujo*).
2. El usuario que realiza la acción debe tener permisos tanto para el activo de origen como para el activo o la pila de destino.
3. Los activos se apilan secuencialmente.
4. No se puede apilar una pila en una pila.
5. Las carpetas están totalmente descartadas.

**Los dos últimos escenarios** también son bastante simples, pero requieren un poco más de conocimiento sobre la pila en sí. Por ejemplo, para reordenar un activo en una pila, necesitará saber cuáles son los `id` de los activos que hay en cada lado de donde quiere colocar su activo de destino, y eso, por lo general, significará que ya ha recuperado toda la pila.

### Ámbitos necesarios




Antes de comenzar a leer esta guía, asegúrese de tener un token que incluya los siguientes ámbitos:




| Ámbito | Motivo |
| ---------- | ---------- |
| **Activos:** Lectura, Actualización | - Recuperar activos de origen y de destino.<br>- Añadir un activo a una pila de versiones.<br>- Reordenar una pila.<br>- Quitar un activo de una pila.<br>- Eliminar una pila. |




## Añadir activos a pilas de versiones




### Paso 1: Localizar su destino




El primer paso consiste en identificar en cuál de los dos escenarios clave se encuentra: añadir un activo a otro para crear una pila, o añadir un activo a una pila para ampliar esa pila.

Si sabe que está trabajando con un activo sin versiones o ya tiene un `id` de pila de versiones, puede continuar con el paso 2.

Si no, la forma más fácil de determinar si un activo de destino ya forma parte de una pila es la siguiente:




1. Realice una solicitud `GET` a su activo de destino mediante una llamada a `/v2/assets/:id`.
2. Compruebe el `type` que se devuelve.


  

* Si es *version_stack*, el uuid que acaba de comprobar es su uuid de destino. Vaya al paso 2.



3. Si el `type` es *file*, anote el `parent_id`.
4. Realice una solicitud GET al elemento principal mediante el mismo punto final y compruebe su `type`.

Si el `type` del elemento principal es *version_stack*, use su `id` como su destino. Si el `type` es cualquier otra cosa, está trabajando con un activo normal y puede usar el identificador original como su destino.

### Paso 2: Preparar su carga útil




Ahora que tiene su uuid de destino, necesita saber cuál es el uuid del activo que va a añadir a la pila.




1. Si está cargando un activo nuevo, simplemente use el id que se devuelve con la respuesta correcta cuando [cree el activo](ref:post_assets-parentid-children).
2. Si está apilando un activo existente, debería tener el `id` a través del proceso descrito anteriormente.

El único parámetro de cuerpo necesario para una adición de pila de versiones es `next_asset_id`:

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




### Paso 3: Añadir su activo de origen al destino

Ahora que tiene ambos parámetros de `id` de activo, ya tiene todo lo que necesita para realizar una solicitud `POST` a `/assets/:id/version`, donde :id es su activo de destino o pila de versiones, y su activo de origen (nuevo) está en la carga útil del cuerpo.

## Reordenar pilas de versiones

Las pilas de versiones se basan en un concepto ordinal simple de que cada activo tiene elementos circundantes `next_asset_id` y `prev_asset_id`, donde el orden no se refiere a la numeración de versiones, sino al atributo `index` de cada activo. El `index` funciona de forma contraria a los números de versión, por lo tanto:
* La primera versión (con el número más bajo) en la pila tiene un activo `prev`, pero no tiene activo `next`.
* La versión más reciente (con el número más alto) en la pila tiene un activo `next`, pero no tiene activo `prev`.
* Todas las versiones &quot;internas&quot; tienen tanto un activo `prev` como un activo `next`, que son los activos con ID de versión más altos y más bajos, respectivamente.




Esto nos da tres escenarios distintos, todos los cuales dependen de la misma llamada de punto final:

**Llamada:**

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

**Cuerpo:**

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

En todos los casos, el `id` en la ruta de la URL será el activo que esté moviendo.
| Escenario | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| Mover al principio de la pila | `null` | `id` del activo superior anterior (número de versión más alto). |
| Mover al final de la pila | `id` del activo inferior anterior (v1). | `null` |
| Mover una versión dentro de una pila | `id` del activo justo *encima* de donde le gustaría mover su activo. | `id` del activo justo *debajo* de donde le gustaría mover su activo nuevo. |




## Quitar activos y eliminar pilas de versiones




### Quitar activos




Cuando un activo se mueve a una pila de versiones, se convierte en elemento secundario de la propia pila. Para mover un activo fuera de una pila de versiones, lo que necesitará hacer es efectivamente volver a asignarlo como elemento principal en la carpeta que contiene la pila.




1. Realice una solicitud `GET` a la pila de versiones en sí mediante una llamada a `/v2/assets/:id`
2. Obtenga el `parent_id` de la pila en sí (que se convierte en su nuevo `id` de carpeta de destino)
3. Mueva su activo de destino a la carpeta de la siguiente manera:

**Llamada**:

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

**Cuerpo**:

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





### Eliminar pilas de versiones




Eliminar una pila de versiones es extremadamente sencillo:





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





Eso es todo. Eliminar una pila devolverá todos sus activos constituyentes a la carpeta que contiene la pila.




<Info title="Las pilas de tamaño 1 deben eliminarse">
  Si quita todos los elementos de una pila de versiones, acabará con una pila de versiones con un solo elemento. Esto es fácil de detectar: si realiza una solicitud `GET` a la pila de versiones por su `id`, verá que tiene un atributo de `&quot;version&quot;: 1`.
</Info>


Todo esto es técnicamente correcto: la versión singleton se cargará y reproducirá, se pueden añadir versiones nuevas y todo continuará con normalidad; pero para evitar presentar un escenario confuso para los usuarios en las aplicaciones web y otras aplicaciones de Frame.io, recomendamos eliminar las pilas singleton.

Para obtener más información sobre el punto final de la pila de versiones, consulte la documentación [Activos](ref:assets).