Reference Roles — Tell the Model What to Take from Each Reference

When you wire a reference into a Generate Image or Generate Video node — a plain image, or a Character / Location / Object / Animal asset via the Assets handle — you can tell the model which aspect of that reference to use: its identity, its outfit, its background, its style, and so on. That aspect is the reference’s role label.

A labeled reference resolves to one uniform phrase in the final prompt:

… the {label} from reference image A … (image — references are lettered A, B, C…)

… the {label} from @image_1 … (video — references are numbered @image_1, @image_2…)

The vocabulary is identical for image and video — only the binding (reference image A vs. @image_1) differs. The same mechanism powers plain image references and every asset type, so they share one numbering and never collide.

Type-aware defaults

A freshly-wired reference starts with the most useful label for its type, so it does the right thing with zero configuration:

Wired source	Default label
Character	`person`
Location	`background`
Object	`object`
Animal / Creature	`creature`
Face	`face`
Plain image / upload	`ref-only` (bare reference)
Video / audio	`ref-only` (bare reference)

Plain images, video, and audio default to ref-only — see Ref only below.

Preset roles

Click a reference pill to pick its role from a curated, type-aware menu (most-useful first; the default is bold). Custom… is always available for anything not listed.

Source	Preset roles
Character / Person	ref-only · person · face · clothes · hair · pose · expression · style
Location	ref-only · background · atmosphere · as-is · empty background · layout · lighting · style
Object	object · shape · material · color · texture · style
Animal / Creature	creature · anatomy · markings · pose · color · style
Plain image (wired / uploaded)	ref-only · object · person · face · clothes · background · style · pose · texture

A few roles read as a fuller phrase so the prompt stays natural:

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

Ref only

Ref only injects the bare reference — reference image A on image nodes, or @image_1 / @video_1 / @audio_1 on video nodes — with no the {label} from … phrase, so the model sees the reference without being told what to take from it. It’s the top entry of every reference pill’s menu and the default for plain image, video, and audio references.

For Character / Location / Object / Animal assets, ref-only is an explicit choice (their described defaults — person / background / object / creature — are unchanged). A Character or Location pill set to ref-only serializes as a plain role (@kira:1:ref-only) and shows a compact ref badge to set it apart from its described default.

Combining a variant with a role

A character or location mention can pick which image (the variant) and what to take from it (the role) independently: @abi:1:walking:clothes attaches Abi’s walking image and injects the clothes from reference image A. Any role works — curated, custom, or ref-only (@abi:1:walking:ref-only → bare reference image A with the walking image attached). Locations mirror it: @library:1:weather/rain:lighting.

In the editor the two axes map to the chip’s two controls: click the thumbnail to swap which image (canonical or a variant — swapping within the same character keeps your role), click the label to pick the role (picking a role keeps the variant; Default resets the role but keeps the image).

Custom labels

Pick Custom… and type anything (e.g. dragon, Danny, hoodie). Custom labels are sanitized (≤32 chars, spaces become dashes) and slot into the default phrase: the hoodie from reference image A. Proper nouns are used verbatim (Danny from reference image A).

Identity-lock (optional, off by default)

By default nothing identity-locking is auto-injected — references behave like images, and the role label alone drives the result. When you want to pin a subject’s exact identity, switch the identity-lock on for that reference and it prepends a short fidelity line:

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

… the person from reference image A …

The lock is opt-in and editable per reference: turn it on when you need it, and either keep the built-in wording (tuned per type — person / face / creature / location) or replace it with your own. Left off, your prompt stays terse and you remain in full control of any fidelity language.

In the editor you can also flip the lock per @-mention: open a character or location pill’s menu and toggle Identity lock. That mention then serializes a trailing ~lock (@kira:1:face~lock, @old-library:1:background~lock) and its reference gets the lock line — even when the source’s default lock is off. Locations use their own built-in wording:

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

The reverse is also available: a trailing ~nolock (@kira:1:face~nolock) forces the lock off for that one mention — even when the reference’s own default lock is on. So ~lock and ~nolock are a symmetric pair: force-on and force-off; a mention with neither simply inherits the reference’s default. ~nolock is typed directly into the prompt (the pill menu’s toggle only sets force-on or inherit).

The per-mention toggles apply to the default (hybrid) reference format only.

Combining references

Wire several references and label each one — the model composes them:

“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.”

References are numbered image-refs first, then assets, in the order they appear, and the same numbering drives both the prompt phrasing and the images sent to the model — so what you see in the final-prompt preview is exactly what runs.

API / SDK / MCP / CLI

The role label and identity-lock travel on the structured connectedReferences shape, so server-side callers control them too. See API Integration and the SDK Reference for the connected_references fields, and CLI for the passthrough flags.