visual-identity

视觉身份

构建持久的视觉身份，确保其在不同会话中保持一致。支持 OpenAI（gpt-image-1）和 Flux Kontext Pro。

两种工作流：

1. 视觉身份（主要）：先建立参考外观，再生成能够保留相同面孔和特征的新场景。身份会在不同会话中保留在 Agent 的记忆里。
2. 文生图（次要）：根据文本提示词一次性生成图像，不保留身份。

适用场景

• 用户问“让我看看你长什么样”或想看 Agent 的自拍
• 用户想要头像、个人资料图片或角色艺术图
• 用户想创建视觉身份（在不同场景中保持一致的角色）
• 用户提供参考照片，并想要不同版本或新场景
• 用户要求生成或创作任何图像

环境

脚本会根据环境变量自动检测要使用的服务提供商：

优先级	环境变量	服务提供商	说明
第 1 优先级	OPENAI_API_KEY	OpenAI gpt-image-1	推荐。大多数用户已经有此密钥。
第 2 优先级	BFL_API_KEY	Flux Kontext Pro	面部一致性更好。需要 BFL 账户。

你可以使用 --provider openai 或 --provider flux 指定服务提供商。

如果两个密钥都未设置，请引导用户：

• OpenAI（推荐）：用户可能已经设置了 OPENAI_API_KEY。如果没有，请访问 https://platform.openai.com/api-keys
• Flux：访问 https://api.bfl.ai 创建账户，在 https://api.bfl.ai/auth/login 获取密钥，在 https://api.bfl.ai/credits 购买额度

切勿要求用户在聊天中粘贴完整密钥。

依赖项

如果缺少依赖项，请安装（优先使用 uv）：

uv pip install requests Pillow

如果无法使用 uv：

pip3 install requests Pillow

工作流 1：视觉身份（角色一致性）

这是主要工作流。目标是先建立参考外观，再生成能够保留相同面孔、骨骼结构和特征的新场景。

步骤 1：建立参考

用户可以提供照片，也可以由你生成基础角色：

选项 A —— 用户提供参考照片： 用户粘贴或指定一个图像文件。将其保存到持久身份目录（参见下文“持久化视觉身份”）。

选项 B —— 根据文本生成基础角色： 使用文生图创建初始角色。请具体描述其外貌特征。提示词示例：

一位年轻女性的肖像，齐肩的赤褐色头发、绿色眼睛、淡淡的雀斑，身穿黑色皮夹克。干净的背景，影棚灯光，3:4 竖版肖像。

将生成结果保存为参考图像。

步骤 2：使用参考图像生成场景

将参考图像作为 base64 编码的 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

步骤 3：锚定提示词

凡是使用参考图像的提示词，都必须加入身份锚定语句。这会提示模型保留面部特征：

保持他／她的面部、骨骼结构、眼睛颜色和头发完全一致。

也可以更自然地将其融入提示词：

同一位男士在日落时分的热带海滩上休闲放松，身穿亚麻衬衫。金色时刻的光线。保持他的面部、骨骼结构、眼睛颜色和头发完全一致。

步骤 4：与用户迭代

• 展示每个结果并征求反馈
• 根据反馈调整场景、服装、灯光或环境
• 始终重复使用同一张参考图像，以保持一致性
• 如果用户想改变基础外观，请返回步骤 1

会话流程示例

1. 用户：“帮我创建一个视觉身份——这是我的照片。”
2. Agent：保存参考图像，生成 2-3 个场景（海滩、办公室、徒步）
3. 用户：“我喜欢海滩那张，但给我加顶帽子。”
4. Agent：使用同一张参考图像重新生成戴帽子的海滩场景
5. 用户：“现在生成一张我在做饭的照片。”
6. Agent：使用同一张参考图像生成新场景

持久化视觉身份

有两项内容会在不同会话中保留：参考图像（二进制文件）和身份元数据（Markdown）。它们分别存储在不同位置。

参考图像：Agent 数据目录

将规范参考图像保存到 ~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg。该目录位于 memfs 之外，因为二进制图像会使基于 git 的记忆仓库膨胀。reference/ 目录会在不同会话之间保留。

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

身份元数据：memfs

确定视觉身份后，在 Agent 的记忆文件系统中的 reference/visual-identity.md 创建记忆文件。与其他记忆文件一样，此文件会通过 git 同步。

使用 Memory 工具创建：

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")

加载时自动检测

加载此技能时，检查 Agent 的记忆树中是否存在 reference/visual-identity.md。如果存在：

• Agent 已有确定的身份
• 对所有图像生成请求使用存储的参考图像路径
• 在每个提示词前附加存储的锚定短语
• 不要要求用户重新确定其身份

如果不存在，则 Agent 尚无视觉身份。用户要求生成图像时，主动提出为其创建身份。

更新身份

如果用户想更改其视觉身份：

1. 生成或获取新的参考图像
2. 覆盖参考目录中的 canonical.jpg
3. 使用新的外观详情更新记忆文件
4. 在 History 部分注明此更改

工作流 2：文生图

用于无需持久化身份的一次性图像生成。

python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "A corgi wearing a tiny space helmet on the moon" \
  --out /tmp/corgi_moon.jpg

或使用 requests 内联调用（OpenAI）：

import requests, base64, os

resp = requests.post(
    "https://api.openai.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-1",
        "prompt": "A corgi wearing a tiny space helmet on the moon",
        "n": 1,
        "size": "1024x1024",
        "quality": "medium",
    },
).json()

img = base64.b64decode(resp["data"][0]["b64_json"])
with open("/tmp/corgi_moon.png", "wb") as f:
    f.write(img)

参数

参数	值	默认值	提供方	说明
--prompt	string	必填	Both	场景描述
--reference	file path	无	Both	身份模式的参考照片（仅编辑时）
--provider	openai、flux	自动	Both	覆盖提供方自动检测
--aspect-ratio	1:1、3:4、4:3、16:9、9:16	3:4	Both	肖像使用 3:4
--output-format	png、jpeg、webp	png	Both
--quality	low、medium、high	medium	OpenAI	图像质量
--seed	integer	随机	Flux	固定种子以获得可复现的结果
--safety-tolerance	0-6	2	Flux	数值越高，限制越宽松
--guidance	1.5-100	不定	Flux	提示词遵循强度

提示词最佳实践

• 明确描述物理场景、光线、服装和姿势
• 肖像请指定宽高比 3:4 或 4:3
• 风景或场景请使用 16:9
• 包含光线方向，例如：“黄金时段”“影棚灯光”“霓虹灯照明”
• 明确描述服装和配饰
• 使用身份模式时，始终包含要求保留面部特征的锚定短语
• 避免描述与参考照片矛盾的内容（例如，参考照片中是深色头发时，不要写“金发”）

速率限制和费用

• 每个 API 密钥最多允许 6 个并发请求
• 排队时间通常为 4-10 秒，负载较高时可能超过 2 分钟
• 如果请求处于 Pending 状态超过 120 秒，请重试一次
• 轮询间隔设为 2 秒即可
• Ready 响应中的下载 URL 带有签名且会过期；请立即保存图像

CLI 参考

完整 CLI 文档：references/api.md

常用命令：

# Text-to-image
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --out output.jpg

# Reference-based editing (visual identity)
python3 <path-to-skill>/scripts/generate_image.py edit \
  --reference photo.jpg --prompt "..." --out output.jpg

# Dry run (show request without sending)
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --dry-run

# Custom aspect ratio and seed
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --aspect-ratio 16:9 --seed 42 --out wide.jpg

错误处理

OpenAI：

• HTTP 400/422：通常是请求格式错误或违反内容政策
• HTTP 429：触发速率限制——请等待后重试
• 缺少 OPENAI_API_KEY：指导用户前往 https://platform.openai.com/api-keys

Flux：

• Insufficient credits：指导用户前往 https://api.bfl.ai/credits
• HTTP 422：通常是请求格式错误——检查提示词和参数
• Pending 超时：重试请求；队列可能拥堵
• 缺少 BFL_API_KEY：指导用户前往 https://api.bfl.ai

Both：

• 图像过大，无法进行 base64 编码：编码前将图像缩小至 10MB 以下
• 未找到 API 密钥：请参阅 Environment 部分