---
title: "Elementi, versioni e @handle"
description: "Personaggi, set, oggetti di scena e stili sono elementi con versioni e immagini di riferimento, richiamati in ogni inquadratura con il loro @handle."
url: https://www.filmsquare.ai/docs/it/concepts/elements/
lang: it
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# Elementi, versioni e @handle

Un elemento è qualcosa che deve avere lo stesso aspetto in ogni inquadratura: un personaggio, un set, un oggetto di
scena o uno stile. Ogni elemento ha un `@handle`, immagini di riferimento e versioni. Lo approvi una volta, poi lo
richiami in qualsiasi inquadratura con il suo handle.

![La schermata Elements con cast, set e oggetti di scena come schede e un filtro per tipo](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## Tipi di elemento

| Tipo | Nell'app | Reparto |
| --- | --- | --- |
| Character | Personaggio | [Casting](https://www.filmsquare.ai/docs/it/departments/casting/), [Costumi](https://www.filmsquare.ai/docs/it/departments/wardrobe/) |
| Location | Set | [Scenografia](https://www.filmsquare.ai/docs/it/departments/sets/) |
| Prop | Oggetto di scena | [Attrezzeria](https://www.filmsquare.ai/docs/it/departments/props/) |
| Style | Stile | Un look: macchina, ottica, luce, color, pellicola. Vedi [Stili](https://www.filmsquare.ai/docs/it/concepts/styles/) |

Un costume non è un elemento a sé: è un [look](https://www.filmsquare.ai/docs/it/departments/wardrobe/) di un personaggio, per scena.

## @handle

Ogni elemento ha un handle, come `@anna` o `@backlot-street`. Scrivi `@` in un prompt, nella descrizione di
un'inquadratura o nel compositore per portare dentro un elemento. Filmsquare aggiunge poi per te le immagini di
riferimento dell'elemento al ciak, scelte per il taglio e l'angolazione dell'inquadratura.

Nella schermata **Elements**, **Copy @handle** lo copia. **Search elements or @handle** ne trova uno.

## Dove vivono gli elementi

Un elemento appartiene a una produzione, oppure a tutto lo spazio di lavoro («Every production in this workspace»).
Un elemento di tutto lo spazio di lavoro si può usare in ogni produzione; l'elemento proprio di una produzione solo
lì. In una produzione ci lavori sotto **Cast & sets → Cast**, **Locations** e **Props**, e sugli stili sotto
**Create → Mood**. Una produzione ha anche una sua pagina **Elements**, con un pulsante sulla **Home** di una nuova
produzione: mostra gli elementi di quella produzione e quelli di tutto lo spazio di lavoro che usa (segnati **Every
production**), come quelli nominati dai suoi ciak importati. Ciò che aggiungi lì resta in quella produzione. Una
modifica a un elemento di tutto lo spazio di lavoro vale ovunque, e la troupe si assegna solo agli elementi propri
di una produzione.

## Creare un elemento

- **Da uno spoglio:** lo spoglio di una sceneggiatura porta dentro il cast, i set e gli oggetti di scena che trova.
- **Add elements:** nella pagina Elements, lascia cadere foto ovunque (o sceglierne più d'una). Ognuna diventa una
  scheda bozza con un tipo e un nome letto dal nome del file (`chr_ines_v3.png` è il personaggio Ines).
  Controlla entrambi, poi **Add** li aggiunge tutti insieme. Ogni foto diventa il primo riferimento dell'elemento.
- **Descrivine uno:** scegli un **Kind** (tipo) e un **Name** (nome) e scrivi una frase. Filmsquare renderizza una
  scheda di riferimento e usa la prima.
- **Save as element:** trasforma un ciak che ti piace in un personaggio, un set o un oggetto di scena. Il ciak
  diventa il suo primo riferimento.
- **Da un tag:** **Create** accanto a un tag sotto **Script → Tagging** crea il personaggio, il set o l'oggetto di
  scena che nomina.
- **New look:** sotto **Create → Mood**, crea uno stile da immagini che selezioni. Vedi
  [Il canvas](https://www.filmsquare.ai/docs/it/working-together/canvas/#looks).
- **New style:** sotto **Create → Styles**, scrivi una guida di stile e aggiungi immagini di riferimento, oppure usane
  una della libreria. Vedi [Stili](https://www.filmsquare.ai/docs/it/concepts/styles/).

## Versioni

Ogni cambiamento di aspetto di un elemento è una nuova versione. Le versioni non cambiano mai una volta create,
quindi le inquadrature che ne hanno usata una restano riproducibili. La versione più recente è **Current**; le
inquadrature usano la versione attuale a meno che un'inquadratura non sia fissata a una più vecchia.

Nella pagina dell'elemento, **New version** copia la versione attuale, con ogni riferimento, come la successiva.
Poi aggiungi o cambia i suoi riferimenti.

![La pagina di un elemento con le sue versioni, le immagini di riferimento e le schede](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> Una volta fatto un ciak con una versione, i riferimenti di quella versione sono congelati. Per aggiungere un
> riferimento, fai una nuova versione. L'API risponde `409 element_version_frozen` con la via d'uscita.

## Riferimenti e schede

Un riferimento è un'immagine dell'elemento con un ruolo: frontale, tre quarti, profilo, retro, figura intera,
turnaround, espressione, dettaglio, campo largo e qualche altro. **Add reference** ne carica uno. La croce accanto a
un'immagine della versione attuale la toglie: Filmsquare crea una nuova versione senza di essa, e le versioni più
vecchie la conservano.

Una **scheda** è una vista pulita dell'elemento, renderizzata per essere usata come riferimento. Ne renderizzi una
dalla pagina dell'elemento; quando è giusta, **Sign off as reference** (approva come riferimento): Filmsquare crea
una nuova versione con quell'immagine aggiunta.

## Versioni e approvazione

Una nuova versione (v2 in su) di un elemento è un cambiamento di lavoro già approvato. Fa scadere il suo reparto in
ogni episodio ancora in lavorazione che usa l'elemento:

| Elemento | Reparti che scadono |
| --- | --- |
| Personaggio | Casting, Costumi, Voci |
| Set | Scenografia |
| Oggetto di scena | Attrezzeria |

Un nuovo elemento (v1) no: lo spoglio che l'ha portato dentro era già approvato. Vedi
[Approvazione e via libera](https://www.filmsquare.ai/docs/it/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale).

## Archiviare

**Archive…** toglie un elemento dagli elenchi. Le inquadrature e i ciak che lo hanno usato conservano la loro
cronologia. Non viene cancellato nulla.

## Con il tuo Claude

`get_script` restituisce gli handle che una produzione ha già, così uno spoglio li riusa. `view_media` mostra a
Claude un'immagine di riferimento; `upload_file` aggiunge un'immagine come asset di produzione per un riferimento.
Versioni, riferimenti e schede passano per `find_actions` e `run_action` (per esempio `forkElementVersion`,
`generateForElement`, `acceptElementTake`). `removeElementReferences` toglie vecchie immagini da un elemento: una nuova
versione senza di esse diventa quella attuale, e le versioni precedenti conservano le loro. Vedi
[Cosa può fare Claude](https://www.filmsquare.ai/docs/it/claude/tools/).
