# Reference roles

> Give each reference a role such as face, outfit, background or style, lock a subject's identity when you need it, and mention references by name in the prompt.

Source: https://nodaro.ai/docs/guides/reference-roles

A **reference role** tells the model what to take from one reference: its identity, its outfit, its background, its style, and more. A reference can be a plain image or a Character, Location, Object or Animal asset, connected to a [Generate Image](https://nodaro.ai/docs/nodes/image/generate-image) or [Generate Video](https://nodaro.ai/docs/nodes/video/generate-video) node. Nodaro writes each reference's role into the prompt as one plain phrase, so the model knows exactly which part of which picture to use.

## How a role reads in the prompt

A reference with a role becomes one phrase in the final prompt:

| Node | The phrase | How references are named |
| --- | --- | --- |
| Generate Image | `the {role} from reference image A` | By letter: A, B, C |
| Generate Video | `the {role} from @image_1` | By number: `@image_1`, `@image_2` |

The roles are the same on both nodes. Plain images and assets share one sequence, so two references never get the same name.

## Default roles

A new reference starts with the most useful role for its type, so it works with no setup:

| Connected source | Default role |
| --- | --- |
| [Character Asset](https://nodaro.ai/docs/nodes/assets/character) | person |
| [Location Asset](https://nodaro.ai/docs/nodes/assets/location) | location |
| [Object/Props Asset](https://nodaro.ai/docs/nodes/assets/object) | object |
| [Animal/Creature Asset](https://nodaro.ai/docs/nodes/assets/creature) | creature |
| [Create Face](https://nodaro.ai/docs/nodes/assets/create-face) | face |
| Plain image or upload | Ref only |
| Video or audio | Ref only |

## Choose a role

Click a reference's pill to open its role menu. The most useful roles for that type come first, and the default is in bold. **Custom…** is always at the end, for any role that is not listed.

| Source | Roles you can choose |
| --- | --- |
| **Character** | Ref only, **person**, face, clothes, hair, pose, expression, style |
| **Location** | Ref only, **location**, background, atmosphere, as-is, empty background, layout, lighting, style |
| **Object** | **object**, shape, material, color, texture, style |
| **Animal or creature** | **creature**, anatomy, markings, pose, color, style |
| **Plain image** | **Ref only**, object, person, face, clothes, background, style, pose, texture |

Two roles read as a fuller phrase, so the prompt stays natural:

| Role | Reads as |
| --- | --- |
| as-is | `reference image A, used as-is` |
| empty background | `the background from reference image A (without its foreground objects)` |

### Ref only

**Ref only** sends the reference without a phrase about what to take from it. On an image node the prompt says only `reference image A`, and on a video node only `@image_1`, `@video_1` or `@audio_1`. The model sees the reference but is not told how to use it. Ref only is the default for plain images, videos and audio. For a Character or Location asset, you can choose it on purpose; its pill then shows a small **ref** badge.

### Custom roles

Choose **Custom…** and type any word, such as `dragon`, `hoodie` or `Danny`. A custom role can be up to 32 characters, and spaces become dashes. It takes the place of the role in the phrase: `the hoodie from reference image A`. A proper name is used as written: `Danny from reference image A`.

## Combine several references

Connect several references, give each one a role, and describe how they fit together:

```
A portrait of the person from reference image A wearing the clothes from reference image B, standing in the background from reference image C, lit by the lighting from reference image D.
```

Workflow: A character gives the person, one photo gives the outfit and another gives the background.

- Upload Image → Generate Image (references)
- Upload Image → Generate Image (references)
- Character Asset → Generate Image (assets)

**The order of references.** References are numbered in one sequence. The images connected to **References** come first, then the assets connected to **Assets**, each in the order they appear. The same numbering drives the prompt and the pictures sent to the model, so the final-prompt preview shows exactly what runs.

## Mention a reference by name

You can place a reference exactly where it belongs in your sentence with an `@` mention.

### Characters and locations

Type `@` in the prompt and choose the character or location. A mention can also choose which picture to send, the **variant**, and what to take from it, the **role**:

| Mention | What it does |
| --- | --- |
| `@abi:1:walking:clothes` | Sends Abi's walking picture and adds `the clothes from reference image A` |
| `@abi:1:walking:ref-only` | Sends the walking picture as a bare `reference image A` |
| `@library:1:weather/rain:lighting` | Sends the rainy variant of the location and takes its lighting |

In the prompt, a mention is a chip with two controls. Click the **thumbnail** to change the picture: switching to another picture of the same character keeps your role. Click the **label** to change the role: that keeps the picture, and **Default** goes back to the default role.

### Plain images

Give the [Upload Image](https://nodaro.ai/docs/nodes/image/upload-image) node a **Label**. The label becomes the image's mention name, so a node labeled `Town` is `@town:1`.

| Mention | What it does |
| --- | --- |
| `@town:1` | Places `reference image A` exactly where you typed it |
| `@town:1:background` | Places `the background from reference image A` |
| `@town:1:signage` | Uses any single custom word as the role |
| `@town:1~lock` or `@town:1~nolock` | Turns the identity lock on or off for this mention |

Mentions are optional. An image without a label is still sent as before; it just has no name to mention. A label that starts with a digit, such as `3D Render`, cannot become a mention name, so rename it if you want to mention it.

### Creatures and objects

Animal/Creature and Object/Props assets use the same short form, with their own name and roles. A creature named Nessie is `@nessie:1`, and `@nessie:1:markings` takes its markings. The editor does not suggest these mentions, so type them by hand.

A mention matters most for creatures and objects. A connected creature or object that you do not mention still adds its phrase, at the end of the prompt. When you mention it, the phrase appears once, inside your sentence, and the model connects it to what you wrote:

```
A wide shot of @nessie:1 rising from the lake
```

This becomes "A wide shot of the creature from reference image A rising from the lake".

When two kinds share a name, the first kind in this order wins: character, location, image, creature, object.

## Lock a subject's identity

By default, Nodaro adds no identity instruction. References behave like pictures, and the role alone drives the result. When a subject must not change, turn on the **identity lock** for that reference. The lock adds one line before the rest of the prompt:

```
Lock the exact identity of the person in reference image A — face, bone structure, skin tone, all unique features.
```

- **Per reference.** The lock is off by default and you turn it on for each reference. The built-in wording is written for each type, person, face, creature and location, and you can replace it with your own.
- **Per mention.** In the menu of a character or location mention, turn on **Identity lock**. That mention then carries `~lock`, such as `@kira:1:face~lock`, even when the reference's own lock is off.
- **Off for one mention.** Type `~nolock` after a mention, such as `@kira:1:face~nolock`. The lock is then off for that mention, even when the reference's lock is on. A mention with neither follows the reference's setting.

For a location, the lock keeps the place instead of a face:

```
Lock the exact look of reference image A — match the location's architecture, layout, and lighting.
```

## From the API

Code and AI assistants can set the role and the identity lock of each reference too. They send them as structured references with image and video generation requests. See [Run a single node](https://nodaro.ai/docs/developers/api/nodes) and the [MCP tools](https://nodaro.ai/docs/mcp/tools).

## Tips

- **Mention creatures and objects.** A mention puts their phrase inside your sentence, where the model can connect it to the action you describe.
- **Lock only what must not change.** With the lock off, your prompt stays short and you keep full control of the wording. Turn it on for the subjects whose identity must hold.
- **Anchor recurring subjects.** For a character you use in many shots, make a [consistency grid](https://nodaro.ai/docs/guides/reference-boards) once and connect it as the reference.
- **Check the final prompt.** Open the final-prompt view of the prompt field to see every phrase your roles add.

## Frequently asked questions

### What is a reference role?

A role is a short label that tells the model which part of a reference to use, such as the face, the clothes, the background or the style. Nodaro writes it into the prompt as a phrase like "the clothes from reference image B".

### Why does my plain image reference have no role?

Plain images, videos and audio start as Ref only. The model receives the reference without being told what to take from it. Click the reference's pill to choose a role such as background or style.

### What does the identity lock do?

It adds one line to the prompt that tells the model to keep the exact identity of the subject in that reference, such as the face and bone structure of a person. It is off by default. Turn it on for each reference that must not change.

### How do I mention an uploaded image in the prompt?

Give the Upload Image node a label, such as Town. The image then has a mention name, @town:1, and @town:1:background tells the model to take the background from it.

### Do roles work on both image and video nodes?

Yes. The roles are the same on Generate Image and Generate Video. Only the way a reference is named in the prompt differs, a letter on image nodes and a number on video nodes.