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

# Gérer les piles de versions

## Vue d'ensemble




Les piles de versions constituent un principe organisationnel dans Frame.io qui permet aux fichiers d'être « empilés » verticalement sans être placés dans des dossiers. Les versions empilées facilitent la navigation de fichier à fichier dans l'interface utilisateur Frame.io et prennent en charge la révision côte à côte.





Nous ne prenons actuellement pas en charge le chargement direct dans une pile, donc la séquence API pour gérer le processus de pile de versions de base suivra la même séquence que l'interface utilisateur Frame.io :




1. Chargez le fichier (facultatif : marquez comme privé).
2. Attribuez le fichier à la pile.





Les piles de versions existantes peuvent être réorganisées et les versions individuelles peuvent être retirées d'une pile. Enfin, les piles de versions peuvent être supprimées sans supprimer leurs fichiers constituants.




<Info title="Toutes les piles de versions ont un cover_asset">
  Les piles de versions auront toujours un attribut appelé `cover_asset_id` à leur niveau supérieur. Il s'agit de l'`id` du fichier dont la vignette s'affiche dans l'interface utilisateur web Frame.io et qui correspond à la version la plus élevée de la pile.
</Info>


### Concepts fondamentaux

Les **piles de versions** -- comme les **dossiers** -- constituent des `types` spéciaux de fichiers. Vous pouvez les récupérer avec les mêmes points d'entrée et, selon la valeur de la clé `type` dans la réponse API, analyser et acheminer en conséquence. Cette approche est généralement simple en pratique, mais peut présenter quelques difficultés lors de la gestion de piles à grande échelle. La clé pour travailler avec les piles de versions consiste à séparer les **quatre scénarios les plus courants** :
1. Un fichier peut être ajouté à un fichier, ce qui créera une pile avec un nouvel `id`.
2. Un fichier peut être ajouté à une pile existante.
3. Une pile peut être réorganisée.
4. Les versions individuelles peuvent être supprimées.

**Les deux premiers scénarios** utilisent le même [appel de point d'entrée](ref:post_assets-assetid-version), donc la seule vraie nuance consiste à savoir si vous créez une nouvelle pile (à partir de deux fichiers) ou si vous ajoutez votre fichier à une pile existante. Outre cela, les contraintes sont prévisibles :
1. Les piles doivent correspondre sur `asset_type` (par exemple, vous ne pouvez pas empiler une *image* sur un *flux*).
2. L'utilisateur agissant doit avoir des autorisations pour l'asset source et l'asset ou la pile de destination.
3. Pile d'asset de manière séquentielle.
4. Vous ne pouvez pas empiler une pile sur une pile.
5. Les dossiers sont exclus.

**Ces deux derniers scénarios** sont également assez simples, mais nécessitent de connaître davantage la pile elle-même. Par exemple, pour réorganiser un asset dans une pile, vous devrez connaître les `identifiants` des assets de chaque côté de l'endroit où vous voulez que votre asset cible atterrisse ; et cela signifie généralement que vous avez déjà récupéré la pile entière.

### Portées requises




Avant de commencer ce Guide, vous devrez vous assurer que vous avez un jeton qui inclut les portées suivantes :




| Portée | Raison |
| ---------- | ---------- |
| **Assets :** Lecture, Mise à jour | - Récupérer les assets source et de destination.<br />- Ajouter un asset à une pile de versions.<br />- Réorganiser une pile.<br />- Supprimer un asset d'une pile.<br />- Supprimer une pile. |




## Ajout de ressources aux piles de version




### Étape 1 : localisez votre destination




La première étape consiste à identifier lequel des deux scénarios clés s'applique à votre cas : ajouter une ressource à une autre ressource pour créer une pile, ou ajouter une ressource à une pile pour étendre cette pile.

Si vous savez que vous travaillez avec une ressource non versionnée, ou si vous avez déjà un `id` de pile de version, vous pouvez passer à l'étape 2.

Dans le cas contraire, le moyen le plus simple de déterminer si une ressource de destination fait déjà partie d'une pile est de :




1. Effectuer un `GET` sur votre ressource cible via un appel à `/v2/assets/:id​`
2. Vérifier le `type` renvoyé.


  

* S'il s'agit de *version_stack*, l'uuid que vous venez de vérifier est votre uuid de destination. Passez à l'étape 2.



3. Si le `type` est *file*, récupérez le `parent_id`
4. Effectuez un GET sur le gabarit via le même point d'entrée, et vérifiez son `type`.

Si le `type` du gabarit est *version_stack*, utilisez son `id` comme destination. Si le `type` est autre chose, vous travaillez avec une ressource normale et pouvez utiliser l'identifiant original comme destination.

### Étape 2 : préparez votre charge utile




Maintenant que vous avez l'uuid de votre destination, vous devez connaître l'uuid de l'asset que vous ajoutez à la pile.




1. Si vous chargez un nouvel asset, utilisez simplement l'id renvoyé avec la réponse de succès lorsque vous [créez l'asset](ref:post_assets-parentid-children).
2. Si vous empilez un asset existant, vous devriez avoir l'`id` via le processus décrit ci-dessus.

Le seul paramètre de corps requis pour un ajout de pile de versions est `next_asset_id` :

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




### Étape 3 : ajoutez votre asset source à la destination

Maintenant que vous avez les deux paramètres `id` d'asset, vous êtes prêt à `POST` vers `/assets/:id/version`, où le :id est votre asset de destination ou pile de versions, et votre asset source (nouveau) est dans la charge utile du corps.

## Réorganisation des piles de versions

Les piles de versions reposent sur un concept ordinal simple où chaque asset a des voisins `next_asset_id` et `prev_asset_id`, où l'ordre ne fait pas référence à la numérotation des versions, mais à l'attribut `index` de chaque asset.L'`index` s'exécute à l'opposé des numéros de version, donc en conséquence :
* La première version (numérotée le plus bas) de la pile a un asset `prev`, mais pas d'asset `next`
* La version la plus récente (numérotée le plus haut) de la pile a un asset `next`, mais pas d'asset `prev`
* Toutes les versions « internes » ont à la fois un asset `prev` et `next`, qui sont les assets avec des ID de version supérieurs et inférieurs, respectivement.




Cela nous donne trois scénarios distincts, qui reposent tous sur le même appel de point d'entrée :

**Appel :**

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

**Corps :**

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

Dans tous les cas, l'`id` dans le chemin d'accès URL sera l'asset que vous déplacez.
| Scénario | `prev_asset_id` | `next_asset_id` |
| ---------- | ---------- | ---------- |
| Déplacer vers le haut de la pile | `null` | `id` de l'asset précédent du haut (numéro de version le plus élevé). |
| Déplacer vers le bas de la pile | `id` de l'asset précédent du bas (v1). | `null` |
| Déplacer la version dans une pile | `id` du fichier juste *au-dessus* de l'endroit où vous souhaitez déplacer votre fichier. | `id` du fichier juste *en dessous* de l'endroit où vous souhaitez déplacer votre nouveau fichier. |




## Suppression de fichiers et suppression de piles de versions




### Suppression de fichiers




Lorsqu'un fichier est déplacé dans une pile de versions, il devient un enfant de la pile elle-même.Pour déplacer un fichier hors d'une pile de versions, vous devez effectivement le reparenter dans le dossier contenant la pile.




1. `GET` la pile de versions elle-même via un appel à `/v2/assets/:id`
2. Récupérez le `parent_id` de la pile elle-même (qui devient votre nouveau dossier cible `id`)
3. Déplacez votre fichier cible dans le dossier comme suit :

**Appel** :

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

**Corps** :

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





### Suppression de piles de versions




La suppression d'une pile de versions est extrêmement simple :





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





C'est tout.La suppression d'une pile renverra tous ses fichiers constitutifs dans le dossier contenant la pile.




<Info title="Les piles de taille 1 doivent être supprimées">
  Si vous supprimez tous les éléments d'une pile de versions, vous vous retrouverez avec une pile de versions contenant un seul élément.C'est facile à repérer -- si vous `GET` la pile de versions par son `id`, vous verrez qu'elle a un attribut `&quot;version&quot;: 1`.
</Info>


Tout ceci est techniquement correct -- la version singleton se chargera et se lira, de nouvelles versions peuvent être ajoutées, et tout continuera normalement ; mais pour éviter de présenter un scénario déroutant pour les utilisateurs dans le Web Frame.io et d'autres applications, nous recommandons de supprimer les piles singleton.

Pour plus d'informations sur le point d'entrée d'empilement de versions, veuillez consulter la documentation [Fichiers](ref:assets).