Visual Identity

Visual Identity

Build a persistent visual identity that stays consistent across sessions. Supports OpenAI (gpt-image-1) and Flux Kontext Pro.

Two workflows:

1. Visual identity (primary): Establish a reference appearance, then generate new scenes that preserve the same face and features. Identity persists in the agent's memory across sessions.
2. Text-to-image (secondary): One-off image generation from a text prompt, no identity persistence.

When to use

• The user asks "show me what you look like" or wants agent selfies
• The user wants an avatar, profile picture, or character art
• The user wants to create a visual identity (a consistent character across scenes)
• The user provides a reference photo and wants variations or new scenes
• The user asks you to generate or create any image

Environment

The script auto-detects which provider to use based on environment variables:

You can override with --provider openai or --provider flux.

If neither key is set, guide the user:

• OpenAI (recommended): They likely already have an OPENAI_API_KEY set. If not, https://platform.openai.com/api-keys
• Flux: https://api.bfl.ai to create an account, keys at https://api.bfl.ai/auth/login, credits at https://api.bfl.ai/credits

Never ask the user to paste the full key in chat.

Dependencies

Install if missing (prefer uv):

uv pip install requests Pillow

If uv is unavailable:

pip3 install requests Pillow

Workflow 1: Visual Identity (Character Consistency)

This is the primary workflow. The goal is to establish a reference appearance and then generate new scenes that preserve the same face, bone structure, and features.

Step 1: Establish the reference

Either the user provides a photo, or you generate a base character:

Option A -- User provides a reference photo: The user pastes or specifies an image file. Save it to the persistent identity directory (see "Persisting Visual Identity" below).

Option B -- Generate a base character from text: Use text-to-image to create the initial character. Be very specific about physical features. Example prompt:

A portrait of a young woman with shoulder-length auburn hair, green eyes, light freckles, wearing a black leather jacket. Clean background, studio lighting, 3:4 portrait.

Save the result as the reference image.

Step 2: Generate scenes with the reference

Pass the reference image as base64-encoded input_image:

python3 <path-to-skill>/scripts/generate_image.py edit \
  --reference /path/to/canonical.jpg \
  --prompt "The same person is sitting at a desk coding late at night, lit by monitor glow" \
  --out /tmp/identity_coding.jpg

Step 3: Anchor the prompt

Always include an identity-anchoring phrase in every prompt that uses a reference. This tells the model to preserve facial features:

Keep his/her exact face, bone structure, eye color, and hair.

Or more naturally woven into the prompt:

The same man is relaxing on a tropical beach at sunset, wearing a linen shirt. Golden hour lighting. Keep his exact face, bone structure, eye color, and hair.

Step 4: Iterate with the user

• Show each result and ask for feedback
• Adjust scene, clothing, lighting, or setting based on feedback
• Always reuse the same reference image for consistency
• If the user wants to change the base appearance, go back to Step 1

Example session flow

1. User: "Create a visual identity for me -- here's my photo"
2. Agent: Saves reference, generates 2-3 scenes (beach, office, hiking)
3. User: "I like the beach one but make me wearing a hat"
4. Agent: Regenerates beach scene with hat, same reference
5. User: "Now make one of me cooking"
6. Agent: New scene with same reference

Persisting Visual Identity

Two things persist across sessions: the reference image (binary) and the identity metadata (markdown). They live in different places.

Reference image: agent data directory

Save the canonical reference image to ~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg. This is outside memfs because binary images would bloat the git-backed memory repo. The reference/ directory persists across sessions.

mkdir -p ~/.letta/agents/$AGENT_ID/reference/visual-identity
cp /tmp/generated_portrait.jpg ~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg

Identity metadata: memfs

After establishing a visual identity, create a memory file at reference/visual-identity.md in the agent's memory filesystem. This syncs via git like all other memory files.

Use the Memory tool to create it:

memory(command="create", reason="Store visual identity metadata",
  file_path="reference/visual-identity.md",
  description="Agent's persistent visual identity -- reference image path and appearance description.",
  file_text="## Reference Image\n~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg\n\n## Appearance\n- Hair: shoulder-length auburn, slight wave\n- Eyes: green\n- Skin: light with freckles\n- Build: athletic\n- Distinguishing: small scar above left eyebrow\n\n## Anchoring Phrase\nKeep the exact same face, bone structure, eye color, and hair from the reference image.\n\n## History\n- Established: 2026-04-15\n- User feedback: \"make the hair a bit darker\" -> regenerated, approved")