---
title: "요소, 버전, @핸들"
description: "캐스트, 세트, 소품, 스타일은 버전과 레퍼런스 이미지를 가진 요소예요. 어느 컷에서나 @핸들로 불러 쓸 수 있어요."
url: https://www.filmsquare.ai/docs/ko/concepts/elements/
lang: ko
section: concepts
updated: 2026-11-15
mcp: [get_script, view_media, upload_file, find_actions, run_action]
---

# 요소, 버전, @핸들

요소는 모든 컷에서 똑같이 보여야 하는 것이에요. 배역, 세트, 소품, 스타일이요. 요소마다 `@handle`, 레퍼런스 이미지, 버전이 있어요. 한 번 컨펌하면 어느 컷에서나 핸들로 불러 쓸 수 있어요.

![캐스트, 세트, 소품이 카드로 나오고 종류별 필터가 있는 Elements 화면](https://www.filmsquare.ai/docs/shots/en/elements-desktop.webp)

## 요소의 종류

| 종류 | 앱에서 | 팀 |
| --- | --- | --- |
| Character | 배역 | [캐스팅](https://www.filmsquare.ai/docs/ko/departments/casting/), [의상](https://www.filmsquare.ai/docs/ko/departments/wardrobe/) |
| Location | 세트 | [세트](https://www.filmsquare.ai/docs/ko/departments/sets/) |
| Prop | 소품 | [소품](https://www.filmsquare.ai/docs/ko/departments/props/) |
| Style | 스타일 | 룩: 카메라, 렌즈, 조명, 컬러 그레이딩, 필름 스톡. [스타일](https://www.filmsquare.ai/docs/ko/concepts/styles/)을 보세요 |

의상은 별도의 요소가 아니에요. 배역에 씬별로 붙는 [룩](https://www.filmsquare.ai/docs/ko/departments/wardrobe/)이에요.

## @핸들

요소마다 `@anna`나 `@backlot-street` 같은 핸들이 있어요. 프롬프트, 컷 설명, 컴포저에 `@`를 입력하면 요소를 불러와요. 그러면 Filmsquare가 컷의 사이즈와 앵글에 맞춰 고른 요소의 레퍼런스 이미지를 테이크에 알아서 붙여 줘요.

**Elements** 화면에서 **Copy @handle**을 선택하면 복사돼요. **Search elements or @handle**로 찾을 수 있어요.

## 요소가 있는 곳

요소는 작품 하나에 속하거나 워크스페이스 전체에 속해요(“Every production in this workspace”). 워크스페이스 전체 요소는 모든 작품에서 쓸 수 있고, 작품 자체 요소는 그 작품에서만 써요. 작품 안에서는 **Cast & sets → Cast**, **Locations**, **Props**에서 요소를 다루고, 스타일은 **Create → Mood**에서 다뤄요. 작품에는 자체 **Elements** 페이지도 있고, 새 작품의 **Home**에 버튼이 있어요. 이 페이지는 그 작품의 요소와, 그 작품이 쓰는 워크스페이스 전체 요소(**Every production**으로 표시돼요. 예: 가져온 테이크가 이름을 부른 요소)를 보여 줘요. 여기서 추가한 것은 그 작품에 남아요. 워크스페이스 전체 요소를 바꾸면 모든 곳에 적용되고, 스태프 배정은 작품 자체 요소에만 해요.

## 요소 만들기

- **브레이크다운으로:** 시나리오 브레이크다운이 찾은 캐스트, 세트, 소품을 가져와요.
- **Add elements:** Elements 페이지 아무 곳에나 사진을 끌어다 놓아요(여러 장 선택도 돼요). 사진마다 파일 이름에서 읽은 종류와 이름이 붙은 초안 카드가 돼요(`chr_ines_v3.png`는 배역 Ines예요). 둘 다 확인하고 한꺼번에 **Add**해요. 각 사진이 요소의 첫 레퍼런스가 돼요.
- **설명으로 만들기:** **Kind**(종류)와 **Name**(이름)을 고르고 한 문장을 써요. Filmsquare가 레퍼런스 시트를 렌더하고 첫 번째 것을 써요.
- **Save as element:** 마음에 드는 테이크를 배역, 세트, 소품으로 만들어요. 그 테이크가 첫 레퍼런스가 돼요.
- **태그로:** **Script → Tagging**에서 태그 옆의 **Create**를 선택하면 태그가 가리키는 배역, 세트, 소품이 만들어져요.
- **New look:** **Create → Mood**에서 고른 이미지로 스타일을 만들어요. [캔버스](https://www.filmsquare.ai/docs/ko/working-together/canvas/#looks)를 보세요.
- **New style:** **Create → Styles**에서 스타일 가이드를 쓰고 레퍼런스 이미지를 붙이거나, 라이브러리에 있는 걸 써요. [스타일](https://www.filmsquare.ai/docs/ko/concepts/styles/)을 보세요.

## 버전

요소의 모습이 바뀔 때마다 새 버전이 돼요. 버전은 한번 만들어지면 바뀌지 않아서, 그 버전을 쓴 컷은 그대로 재현할 수 있어요. 가장 새 버전이 **Current**(현재)이고, 컷이 이전 버전에 고정되어 있지 않으면 현재 버전을 써요.

요소 페이지에서 **New version**(새 버전)은 현재 버전을 모든 레퍼런스와 함께 다음 버전으로 복사해요. 그런 다음 거기에 레퍼런스를 추가하거나 바꿔요.

![버전, 레퍼런스 이미지, 시트가 보이는 요소 페이지](https://www.filmsquare.ai/docs/shots/en/element-detail-desktop.webp)

> [!NOTE]
> 어떤 버전으로 테이크를 한번 만들면 그 버전의 레퍼런스는 고정돼요. 레퍼런스를 추가하려면 새 버전을 만드세요. API는 해결 방법과 함께 `409 element_version_frozen`으로 답해요.

## 레퍼런스와 시트

레퍼런스는 역할이 있는 요소의 이미지예요. 정면, 3/4, 측면, 후면, 전신, 턴어라운드, 표정, 디테일, 와이드 등이 있어요. **Add reference**로 하나를 올려요. 현재 버전의 이미지 옆 엑스 표시는 그 이미지를 빼요. Filmsquare가 그 이미지 없는 새 버전을 만들고, 이전 버전에는 그대로 남아요.

**시트**는 레퍼런스로 쓰려고 렌더한 요소의 깔끔한 컷이에요. 요소 페이지에서 렌더하고, 마음에 들면 **Sign off as reference**(레퍼런스로 컨펌)를 선택해요. Filmsquare가 그 이미지를 더한 새 버전을 만들어요.

## 버전과 컨펌

요소의 새 버전(v2 이상)은 컨펌 완료된 작업의 변경이에요. 그 요소를 쓰는, 아직 작업 중인 모든 에피소드에서 해당 팀을 컨펌 만료로 만들어요.

| 요소 | 컨펌이 만료되는 팀 |
| --- | --- |
| 배역 | 캐스팅, 의상, 보이스 |
| 세트 | 세트 |
| 소품 | 소품 |

새 요소(v1)는 그렇지 않아요. 그 요소를 가져온 브레이크다운은 이미 컨펌됐으니까요. [컨펌과 게이트](https://www.filmsquare.ai/docs/ko/concepts/sign-off-and-gates/#when-a-sign-off-goes-stale)를 보세요.

## 보관

**Archive…**를 선택하면 목록에서 요소가 빠져요. 그 요소를 쓴 컷과 테이크의 이력은 남아요. 삭제되는 건 없어요.

## 내 Claude와

`get_script`는 작품에 이미 있는 핸들을 돌려줘서 브레이크다운이 그 핸들을 다시 써요. `view_media`는 Claude에게 레퍼런스 이미지를 보여 줘요. `upload_file`은 레퍼런스용으로 이미지를 작품 에셋에 추가해요. 버전, 레퍼런스, 시트는 `find_actions`와 `run_action`으로 다뤄요(예: `forkElementVersion`, `generateForElement`, `acceptElementTake`). `removeElementReferences`는 요소에서 오래된 이미지를 빼요. 이미지 없는 새 버전이 현재 버전이 되고, 이전 버전에는 그대로 남아요. [Claude가 할 수 있는 일](https://www.filmsquare.ai/docs/ko/claude/tools/)을 보세요.
