---
title: "Éléments, versions et @handles"
description: "Personnages, décors, accessoires et styles sont des éléments avec des versions et des images de référence, appelés dans n'importe quel plan par leur @handle."
url: https://www.filmsquare.ai/docs/fr/concepts/elements/
lang: fr
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# Éléments, versions et @handles

Un élément est quelque chose qui doit avoir le même aspect dans chaque plan : un personnage, un décor, un accessoire ou
un style. Chaque élément a un `@handle`, des images de référence et des versions. Validez-le une fois, puis appelez-le
dans n'importe quel plan avec son handle.

![L'écran Elements avec personnages, décors et accessoires en cartes et un filtre par type](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## Types d'éléments

| Type | Dans l'app | Département |
| --- | --- | --- |
| Character | Cast member | [Casting](https://www.filmsquare.ai/docs/fr/departments/casting/), [Costumes](https://www.filmsquare.ai/docs/fr/departments/wardrobe/) |
| Location | Set | [Décors](https://www.filmsquare.ai/docs/fr/departments/sets/) |
| Prop | Prop | [Accessoires](https://www.filmsquare.ai/docs/fr/departments/props/) |
| Style | Style | Un look : caméra, optique, lumière, étalonnage, pellicule. Voir [Styles](https://www.filmsquare.ai/docs/fr/concepts/styles/) |

Un costume n'est pas un élément à part : c'est un [look](https://www.filmsquare.ai/docs/fr/departments/wardrobe/) sur un personnage, par séquence.

## @handles

Chaque élément a un handle, comme `@anna` ou `@backlot-street`. Tapez `@` dans un prompt, une description de plan ou le
composer pour faire entrer un élément. Filmsquare ajoute alors à la prise les images de référence de l'élément, choisies
selon la valeur de plan et l'axe de caméra.

Sur l'écran **Elements**, **Copy @handle** le copie. **Search elements or @handle** en trouve un.

## Où vivent les éléments

Un élément appartient à une production, ou à tout l'espace de travail (« Every production in this workspace »). Un
élément d'espace de travail peut servir dans toutes les productions ; l'élément propre à une production, seulement
dans celle-ci. Dans une production, vous les travaillez sous **Cast & sets → Cast**, **Locations** et **Props**, et les styles sous **Create → Mood**. Une
production a aussi sa propre page **Elements**, avec un bouton sur le **Home** d'une nouvelle production : elle montre les éléments de cette production et ceux de
l'espace de travail qu'elle utilise (marqués **Every production**), comme ceux que nomment ses prises importées. Ce que
vous y ajoutez reste dans cette production. Une modification d'un élément d'espace de travail vaut partout, et vous n'affectez une équipe qu'aux éléments propres à une production.

## Créer un élément

- **À partir d'un dépouillement :** le dépouillement d'un scénario fait entrer les personnages, décors et accessoires qu'il
  trouve.
- **Add elements :** sur la page Elements, déposez des photos n'importe où (ou choisissez-en plusieurs). Chacune
  devient une carte provisoire avec un type et un nom lus dans le nom du fichier (`chr_ines_v3.png` est le
  personnage Ines). Vérifiez les deux, puis ajoutez-les toutes d'un coup avec **Add**. Chaque photo devient la
  première référence de l'élément.
- **Describe one :** choisissez un **Kind** et un **Name** et écrivez une phrase. Filmsquare lance le rendu d'une fiche de référence et retient la première.
- **Save as element :** transformez une prise qui vous plaît en personnage, décor ou accessoire. La prise devient sa
  première référence.
- **À partir d'un tag :** **Create** à côté d'un tag sous **Script → Tagging** crée le personnage, le décor ou
  l'accessoire qu'il nomme.
- **New look :** sous **Create → Mood**, faites un style à partir d'images que vous sélectionnez. Voir  [Le canevas](https://www.filmsquare.ai/docs/fr/working-together/canvas/#looks).
- **New style :** sous **Create → Styles**, écrivez une charte de style et ajoutez des images de référence, ou prenez-en
  une dans la bibliothèque. Voir [Styles](https://www.filmsquare.ai/docs/fr/concepts/styles/).

## Versions

Chaque changement de l'aspect d'un élément est une nouvelle version. Les versions ne changent jamais une fois créées,
si bien que les plans qui en ont utilisé une restent reproductibles. La version la plus récente est **Current** ; les
plans utilisent la version actuelle, sauf si un plan est épinglé à une version plus ancienne.

Sur la page de l'élément, **New version** copie la version actuelle, avec chaque référence, comme version suivante.
Ajoutez ou modifiez ensuite des références dessus.

![La page d'un élément avec ses versions, ses images de référence et ses fiches](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> Une fois qu'une prise a été faite avec une version, les références de cette version sont figées. Pour ajouter une
> référence, créez une nouvelle version. L'API répond `409 element_version_frozen` avec la marche à suivre.

## Références et fiches

Une référence est une image de l'élément avec un rôle : face, trois quarts, profil, dos, plan en pied, turnaround,
expression, détail, plan large, et quelques autres. **Add reference** en téléverse une. La
croix à côté d'une image de la version actuelle la retire : Filmsquare fait une nouvelle version sans elle, et les
versions plus anciennes la gardent.

Une **fiche** (sheet) est une vue propre de l'élément, produite pour servir de référence. Lancez-en le rendu depuis la page de l'élément ; quand elle est juste, **Sign off as reference** (valider comme référence) : Filmsquare crée une nouvelle version avec cette image
ajoutée.

## Versions et validation

Une nouvelle version (v2 et plus) d'un élément est un changement sur du travail validé. Elle rend caduc son
département dans chaque épisode encore en cours qui utilise l'élément :

| Élément | Départements qui deviennent caducs |
| --- | --- |
| Personnage | Casting, Costumes, Voix |
| Décor | Décors |
| Accessoire | Accessoires |

Un nouvel élément (v1) ne le fait pas : le dépouillement qui l'a fait entrer était déjà validé. Voir
[Validation et feu vert](https://www.filmsquare.ai/docs/fr/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale).

## Archivage

**Archive…** retire un élément des listes. Les plans et les prises qui l'ont utilisé gardent leur historique. Rien
n'est supprimé.

## Avec votre propre Claude

`get_script` renvoie les handles qu'une production a déjà, de sorte qu'un dépouillement les réutilise. `view_media` montre
une image de référence à Claude ; `upload_file` ajoute une image comme ressource de la production pour une référence.
Les versions, références et fiches passent par `find_actions` et `run_action` (par exemple `forkElementVersion`,
`generateForElement`, `acceptElementTake`). `removeElementReferences` retire d'anciennes images d'un élément : une nouvelle version sans elles
devient la version actuelle, et les versions précédentes gardent les leurs. Voir [Ce que Claude peut faire](https://www.filmsquare.ai/docs/fr/claude/tools/).
