---
title: "Elementos, versiones y @handles"
description: "Los personajes, las locaciones, los objetos de utilería y los estilos son elementos con versiones e imágenes de referencia, que se llaman en cualquier plano por su @handle."
url: https://www.filmsquare.ai/docs/es/concepts/elements/
lang: es
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# Elementos, versiones y @handles

Un elemento es algo que debe verse igual en todos los planos: un personaje, una locación, un objeto de utilería o un estilo.
Cada elemento tiene un `@handle`, imágenes de referencia y versiones. Dale el visto bueno una vez y llámalo en cualquier plano
con su handle.

![La pantalla Elements con elenco, locaciones y objetos de utilería como tarjetas y un filtro por tipo](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## Tipos de elemento

| Tipo | En la app | Departamento |
| --- | --- | --- |
| Character | Cast member | [Casting](https://www.filmsquare.ai/docs/es/departments/casting/), [Vestuario](https://www.filmsquare.ai/docs/es/departments/wardrobe/) |
| Location | Set | [Locaciones](https://www.filmsquare.ai/docs/es/departments/sets/) |
| Prop | Prop | [Utilería](https://www.filmsquare.ai/docs/es/departments/props/) |
| Style | Style | Un look: cámara, lente, luz, etalonaje, película. Consulta [Estilos](https://www.filmsquare.ai/docs/es/concepts/styles/) |

Un vestuario no es un elemento propio: es un [look](https://www.filmsquare.ai/docs/es/departments/wardrobe/) de un personaje, por escena.

## @handles

Cada elemento tiene un handle, como `@anna` o `@backlot-street`. Escribe `@` en un prompt, en la descripción de un
plano o en el compositor para traer un elemento. Filmsquare añade entonces a la toma las imágenes de referencia del
elemento, elegidas según el tamaño y el ángulo del plano.

En la pantalla **Elements**, **Copy @handle** lo copia. **Search elements or @handle** encuentra uno.

## Dónde viven los elementos

Un elemento pertenece a una producción, o a todo el espacio de trabajo ("Every production in this workspace"). Un elemento de
todo el espacio de trabajo se puede usar en cada producción; el elemento propio de una producción, solo en ella. En una producción los
trabajas en **Cast & sets → Cast**, **Locations** y **Props**, y los estilos en **Create → Mood**. Una
producción tiene también su propia página **Elements**, con un botón en el **Home** de una producción nueva: muestra los elementos de esa producción y los de todo el espacio de trabajo que
usa (marcados **Every production**), como los que nombran sus tomas importadas. Lo que añades ahí se queda en esa
producción. Un cambio en un elemento de todo el espacio de trabajo aplica en todas partes, y solo asignas equipo a los elementos
propios de una producción.

## Crear un elemento

- **Desde un desglose:** el desglose de un guion trae el elenco, las locaciones y los objetos de utilería que encuentra.
- **Add elements:** en la página Elements, suelta fotos en cualquier sitio (o elige varias). Cada una pasa a ser
  una tarjeta borrador con un tipo y un nombre leídos del nombre del archivo (`chr_ines_v3.png` es el personaje
  Ines). Revisa ambos y añádelas todas a la vez con **Add**. Cada foto pasa a ser la primera referencia del
  elemento.
- **Describe one:** elige un **Kind** y un **Name** y escribe una frase. Filmsquare renderiza una ficha de referencia
  y usa la primera.
- **Save as element:** convierte una toma que te gusta en un personaje, una locación o un objeto de utilería. La toma pasa a ser
  su primera referencia.
- **From a tag:** **Create**, junto a una etiqueta en **Script → Tagging**, crea el personaje, la locación o el objeto de utilería
  que nombra.
- **New look:** en **Create → Mood**, crea un estilo a partir de las imágenes que elijas. Consulta
  [El lienzo](https://www.filmsquare.ai/docs/es/working-together/canvas/#looks).
- **New style:** en **Create → Styles**, escribe una guía de estilo y agrega imágenes de referencia, o usa una de la biblioteca.
  Consulta [Estilos](https://www.filmsquare.ai/docs/es/concepts/styles/).

## Versiones

Cada cambio en el look de un elemento es una versión nueva. Las versiones no cambian una vez creadas, así que los
planos que usaron una se pueden reproducir. La versión más reciente es **Current**; los planos usan la versión
actual salvo que un plano esté fijado a una anterior.

En la página del elemento, **New version** copia la versión actual, con todas sus referencias, como la siguiente.
Después añade o cambia referencias en ella.

![La página de un elemento con sus versiones, imágenes de referencia y fichas](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> Cuando se ha hecho una toma con una versión, las referencias de esa versión quedan congeladas. Para añadir una
> referencia, crea una versión nueva. La API responde `409 element_version_frozen` con la salida.

## Referencias y fichas

Una referencia es una imagen del elemento con un rol: frontal, tres cuartos, perfil, espalda, cuerpo entero,
turnaround, expresión, detalle, general y algunos más. **Add reference** sube una. La
equis junto a una imagen de la versión actual la quita: Filmsquare crea una versión nueva sin ella, y las versiones anteriores la conservan.

Una **ficha** es una vista limpia del elemento, renderizada para usarla como referencia. Renderiza una desde la página
del elemento; cuando está bien, **Sign off as reference**: Filmsquare crea una versión nueva con esa imagen añadida.

## Versiones y visto bueno

Una versión nueva (v2 en adelante) de un elemento es un cambio sobre un trabajo que ya tenía visto bueno. Hace vencer su departamento en
cada episodio todavía en curso que usa el elemento:

| Elemento | Departamentos que vencen |
| --- | --- |
| Personaje | Casting, Vestuario, Voces |
| Locación | Locaciones |
| Objeto de utilería | Utilería |

Un elemento nuevo (v1) no lo hace: el desglose que lo trajo ya tenía el visto bueno. Consulta
[Visto bueno y luz verde](https://www.filmsquare.ai/docs/es/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale).

## Archivar

**Archive…** quita un elemento de las listas. Los planos y las tomas que lo usaron conservan su historial. No se
borra nada.

## Con tu propio Claude

`get_script` devuelve los handles que una producción ya tiene, para que un desglose los reutilice. `view_media`
muestra a Claude una imagen de referencia; `upload_file` añade una imagen como asset de producción para una
referencia. Las versiones, las referencias y las fichas pasan por `find_actions` y `run_action` (por ejemplo
`forkElementVersion`, `generateForElement`, `acceptElementTake`). `removeElementReferences` quita imágenes antiguas de un elemento: una versión
nueva sin ellas pasa a ser la actual, y las versiones anteriores conservan las suyas. Consulta [Qué puede hacer Claude](https://www.filmsquare.ai/docs/es/claude/tools/).
