> ## Documentation Index
> Fetch the complete documentation index at: https://fal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Characters and smart entities

> Define reusable characters, props, environments, styles, and scenes with reference images and an @handle.

A smart entity is a named visual reference you can reuse in generations. Give it reference images and an `@handle`, then select it in a supported prompt instead of attaching and describing the same references each time.

## Choose a type

| Type        | Use it for                                       | Example                                        |
| :---------- | :----------------------------------------------- | :--------------------------------------------- |
| Character   | A person or creature's visual identity.          | `@mara`, a recurring protagonist.              |
| Prop        | A recurring object or product.                   | `@green-bottle`, a campaign product.           |
| Environment | A place, landscape, or setting.                  | `@workshop`, a recurring interior.             |
| Style       | A visual treatment, palette, medium, or texture. | `@watercolor`, a shared illustration look.     |
| Scene       | Staging, composition, and subject arrangement.   | `@breakfast`, a recurring kitchen-table setup. |

All five types use **1–20 image references**. Choose images that make the intended reference clear. Use several angles for a prop, recognizable views of an environment, or examples of the same visual style.

A style entity uses reference images too. It is not a model fine-tune or a text-only preset. A scene is a visual reference for staging. Creating one does not assemble a 3D scene or a video timeline.

## What an entity contains

* **References:** the images that define it, plus a selected cover.
* **Name and handle:** how you find it in the library and mention it in prompts.
* **Description:** text that explains its visual characteristics. Characters require one. The other types allow it to be omitted.
* **Associated media:** generations that used the entity and assets linked to it by hand.

The defining reference images are displayed separately from the associated-media gallery. Adding a media item to that gallery does not automatically make it a reference for future generations.

## Reuse

Entity references help guide a model toward a consistent subject or look. The result depends on the model and its supported inputs. Using an entity is not a guarantee of an identical appearance in every output.

<CardGroup cols={2}>
  <Card title="Creating and managing entities" href="/docs/documentation/assets/entities/managing">
    Add references, choose handles, and maintain associated media
  </Card>

  <Card title="Using entities in generations" href="/docs/documentation/assets/entities/using">
    Mention references in Agent and supported model prompts
  </Card>
</CardGroup>