character-consistency git:20260805.9863cafC

Immutable. This exact content never changes and is served at /api/v1/blob/03952346fe3a8eb4.

# Character Consistency Skill

## Description
Maintain visual consistency for characters across all storyboard panels and video clips using a multi-layer approach covering prompt construction, reference generation, multi-edit refinement, and R2V video anchoring.

## Layer 1: Exhaustive Text Description
Every character in every shot prompt receives their complete locked description. No abbreviations, no "same as before." The model sees the full description each time.

### Description Format
```
CHARACTER_NAME: [age]-year-old [ethnicity/appearance], [hair description],
[facial features], [eye description], [build/height],
[distinguishing features], wearing [wardrobe]...
```

### Description Fields
- Age range (e.g., "mid-30s", "early 50s")
- Ethnicity/general appearance
- Hair: color, length, style, texture
- Eyes: color, shape, notable features
- Face: shape, notable features (cheekbones, jaw, etc.)
- Build: body type, approximate height
- Distinguishing marks: scars, tattoos, glasses, etc.
- Default wardrobe + scene-specific wardrobe changes

## Layer 2: Reference Image Generation & Seed Anchoring

### Prompt Structure for References (CRITICAL)
Style descriptions must be **front-loaded** in the prompt to prevent style drift between angles:

```
STYLE: [full aesthetic string]. [angle description]. [character description].
[base traits]. [no-layout instructions]. [wardrobe].
STYLE REMINDER: [style], [film stock].
```

**Anti-pattern:** Putting aesthetic at the END causes the model to commit to a rendering style before seeing style instructions, producing inconsistent angles (e.g., front is cartoon, profile is photorealistic).

### Generation Parameters
- **cfg_scale: 10** (not 7 — higher values enforce tighter prompt adherence and prevent style drift)
- **Negative prompt must include:** `photorealistic, photograph, photo` alongside standard negative terms — this prevents the model from drifting toward realism when the target aesthetic is stylized/illustration
- **Fixed seed** per character, recorded at lock time
- **Resolution:** 1K, aspect ratio 1:1 for references
- **Image model:** `nano-banana-2` (the global default in `src/characters/reference-manager.ts`). Seedance 2.0 used to accept face-bearing inputs only from `seedream-v5-lite`, but Venice removed that restriction (2026-07) — any image family works for character reference sheets now, regardless of whether the project targets Seedance, Kling, or Veo.

### Reference Angles
4 angles per character are generated and stored:
1. Front face (primary reference — used for `elements.frontal_image_url`)
2. Three-quarter view (used for `elements.reference_image_urls`)
3. Profile view (used for `elements.reference_image_urls`)
4. Full body (used for composition reference)

### Two-Pass Fallback for Persistent Style Drift
When base generation produces stylistically inconsistent angles despite front-loaded prompts and high cfg_scale:

1. **Keep the good reference** (usually front or three-quarter)
2. **Regenerate the drifting angle** as a base image
3. **Style-match via multi-edit** against the good reference:
   ```
   Prompt: "Match the exact art style, rendering technique, color treatment,
   and illustration style of the reference image (image 2). Keep the pose,
   angle, and composition of the base image (image 1)."
   Images: [base (drifting angle), reference (good angle)]
   Model: nano-banana-2-edit  (global default; the old Seedance seedream-only
          face rule was removed 2026-07 — any edit family works)
   ```
4. This forces the edit model to adopt the rendering style of the good reference while preserving the pose

## Layer 3: Multi-Edit Panel Refinement
When generated storyboard panels have good composition but character drift:

### Character Shots (has characters in shot)
- **Images sent:** Panel + 1-2 character front-facing references
- **Prompt:** Match face, body proportions, and wardrobe to references
- **Respects:** Per-episode wardrobe overrides, environment adaptation

### Non-Character Shots (establishing, insert, title)
- **Images sent:** Panel + style anchor (a refined character shot from same project)
- **Prompt:** Match rendering style, palette, line weight, lighting
- **Important:** Use a pre-refinement snapshot as style anchor — post-refinement panels can inherit layout artifacts from character reference sheets

### Post-Refinement
Multi-edit always returns 1024x1024 → crop center + scale to original aspect ratio (e.g., 768x1376 for 9:16)

## Layer 4: R2V Video Identity Anchoring

The most critical consistency layer for video generation. **R2V models are the only Venice video models that support character reference images.**

### How It Works
- Model: `kling-o3-standard-reference-to-video`
- **`elements` parameter:** Each character gets a structured element with:
  - `frontal_image_url`: front-facing character reference
  - `reference_image_urls`: three-quarter and profile angles (up to 3)
- **`reference_image_urls` parameter:** Flat array backup (up to 4 images)
- **Prompt integration:** Character names replaced with `@Element1`, `@Element2` tokens

### Critical Rules
1. **Only R2V models support elements/reference_image_urls.** Kling V3 Pro, Veo 3.1, `kling-o3-pro-image-to-video`, and all other non-R2V models have ZERO reference support.
2. **Never group shots with different characters into multi-shot units.** Multi-shot units render on Seedance R2V Enhanced by default (2026-08-05) with ONE slot plan per generation — disjoint characters can't all anchor correctly. (Legacy `videoDefaults.multiShotModel: kling-o3-pro-image-to-video` overrides have no references at all.)
3. **For talk shows, interviews, and panel formats:** Set `mustStaySingle: true` on all shots to force R2V singles.

### Format-Specific Guidance

| Format | Grouping Strategy | Reason |
|--------|------------------|--------|
| Talk show / interview | All singles with R2V | Frequent speaker cuts, identity > continuity |
| Continuous action scene | Multi-shot OK if same characters | Temporal continuity benefits outweigh |
| Drama with cuts | Singles for close-ups/reactions, multi-shot for continuous action | Balance both |

## Layer 5: Spatial Anchoring (placement, not just appearance)

Identity references lock what a character LOOKS like; they say nothing about
WHERE the character is. Placement is re-inferred on every generation unless
each prompt states the geometry the same way (rule 49):

- **`Location.spatialAnchors`** locks a place's geography: 3-5 named landmarks
  and their fixed relative positions. Injected as "Fixed layout (never
  rearrange): …" into every panel/plate/video prompt for shots in that
  location, and baked into the location's reference angles.
- **`ShotScript.blocking`** locks the shot's geometry: each character/object's
  position relative to the named anchors, frame side (screen left/center/
  right), depth, and facing/eyeline. Injected verbatim (with @ImageN name
  substitution) into panel, plate, and video prompts.
- **Storyboard blocking plates** encode the same geometry visually and carry a
  role clause restricting them to composition/blocking authority; the video
  prompt additionally forbids mirroring/swapping who stands where.
- **Continuity rules:** characters keep their screen sides and relative
  positions across a scene's shots unless a movement is scripted; eyelines
  and screen direction obey the 180-degree rule; close-ups still name what's
  behind/beside the subject.
- **QA:** `qa-storyboard` checks a SPATIAL CONTINUITY dimension against the
  stated blocking and the previous same-location panel; a side-swap or
  mirrored geography is FLAG-CRITICAL.

## Usage
```typescript
import { buildCharacterReferencePrompt } from './mini-drama/prompt-builder.js';
const prompt = buildCharacterReferencePrompt(character, aesthetic, 'front');
```