dev-avatar-service

头像服务

一项服务端点，可为任何用户返回带品牌风格的头像：写实、插画或像素风格，并根据种子（用户 ID／邮箱哈希／姓名首字母）生成确定性结果。服务采用分级回退机制——真实照片 → 上传图片 → 根据姓名首字母生成 AI 头像 → 静态默认头像，并按种子缓存，让每位用户只需付费一次。

适用场景

• 新用户注册时，需要立即提供个人资料图片。
• 默认使用 Gravatar 的评论系统或论坛。
• 没有上传照片的团队页面、目录和排行榜。
• 用户选择头像前，在引导流程中显示占位头像。
• 作为 Gravatar／UI Avatars／DiceBear 的品牌化替代方案。
• 用于预发布／演示环境的模拟数据。

不适用于：仅凭一张照片深度伪造真实人物（工具不合适，伦理上也不妥），或为已经很好的上传照片添加风格效果——让用户保留自己的照片。

前置条件

开始构建前，先询问以下问题（一次发送，共 5 个问题）：

1. 种子来源：用户 ID、邮箱哈希、用户名还是姓名首字母？是否永久保持不变？
2. 风格：写实肖像、插画（类似 Pixar／Disney）、扁平矢量、像素艺术、黏土风格还是字母组合？
3. 品牌调色板：用于背景和字母组合回退方案的强调色。
4. 存储与缓存：S3／CDN + 数据库列、Picsart Drive URL 还是 KV 键？TTL 是多少？
5. 回退链：照片 → AI 头像 → 彩色背景上的姓名首字母 → 默认 SVG？顺序很重要。

如果用户提供了详细需求说明，则跳过。

运行方法

1. 先确定回退层级。 这是整个服务的核心：

   1. user.photo_url          → return as-is
   2. cache.get(seed)         → return stored AI avatar URL
   3. gen-ai generate         → store URL + return
   4. initials on brand color → SVG fallback (no credits)
   5. static /default.png     → last resort
   

2. 估算并验证模型。

   gen-ai models info recraftv4
   gen-ai pricing recraftv4
   gen-ai generate -m recraftv4 -p "illustrated avatar, seed abc123" \
     --aspect-ratio 1:1 --dry-run --debug
   

3. 确定性种子 → 提示词。 将种子哈希为稳定的属性选择。绝不注入 Math.random() 或时间戳。

   SEED="u_482c91"
   # Pick palette + mood from the seed, not from RNG
   HUE=$(printf "%s" "$SEED" | shasum | cut -c1-2)   # 0-255 from hash
   gen-ai generate -m recraftv4 \
     -p "illustrated profile avatar, round frame, abstract humanoid silhouette, HSL hue ${HUE}, friendly neutral expression, flat vector, centered composition, studio background" \
     --aspect-ratio 1:1 \
     --negative-prompt "text, watermark, letters, realistic face, specific person" \
     --save-to-drive --drive-folder avatars \
     --json --no-input | jq -r '.url'
   

4. 按种子缓存 URL（而非二进制文件）。可使用任何存储：Redis、KV、Postgres 列、S3 + 稳定文件名。

5. 姓名首字母回退方案（零费用）。 当生成式 AI 服务不可用、受到速率限制或超出预算时，返回一个 SVG，其中显示用户的姓名首字母，背景色由同一种子派生。用户永远不会看到损坏的图片。

   const initials = name.split(' ').map(p => p[0]).slice(0, 2).join('').toUpperCase();
   const hue = parseInt(sha1(seed).slice(0, 2), 16);
   const svg = `<svg viewBox="0 0 64 64"><rect width="64" height="64" fill="hsl(${hue} 70% 45%)"/><text x="32" y="40" text-anchor="middle" font-size="28" fill="#fff" font-family="system-ui">${initials}</text></svg>`;
   

6. 接入端点。 /avatar/:seed → 检查照片 → 检查缓存 → 生成式 AI → 姓名首字母。成功时重定向到 CDN URL；回退时内联返回 SVG。

7. 批量预热缓存，为现有用户提前生成头像，避免上线时实时请求生成式 AI 导致服务过载：

   gen-ai batch run avatars-backfill.json -c 4 -o ./avatars-out
   

快速参考

为现有的 500 位用户补充头像：

{
  "defaults": {
    "model": "recraftv4",
    "aspectRatio": "1:1",
    "negativePrompt": "text, watermark, letters, realistic face, specific person"
  },
  "jobs": [
    { "id": "u_482c91", "prompt": "illustrated profile avatar, round frame, flat vector, hue 42, friendly neutral, studio background" },
    { "id": "u_91ac3b", "prompt": "illustrated profile avatar, round frame, flat vector, hue 128, calm expression, studio background" },
    { "id": "u_7de119", "prompt": "illustrated profile avatar, round frame, flat vector, hue 201, warm smile, studio background" }
  ]
}

输出会保存到 ./avatars-out/<user-id>.webp——使用相同的键上传到你的 CDN。results.json 会成为种子 → URL 的查找表。

快速参考

子任务	模型	原因
插画／矢量／扁平风格头像	recraftv4	干净、一致、成本低——理想的默认选择
写实肖像（合成的通用人物）	flux-2-pro	面部效果最佳；仅使用通用描述词
像素风格头像	recraftv4 配合像素风格提示词	费用最低，风格可控
为上传的真实照片添加风格效果（需用户选择）	flux-kontext-pro + -i photo.jpg	编辑模型可保留身份特征
低成本草稿／风格探索	gemini-3.1-flash-image	单次调用成本最低
跨尺寸保持身份一致的变体	ideogram-character + -i master.png	多个头像保持相同面孔

使用 gen-ai models --mode image 验证当前可用的 ID。

流程

• 确定性 = 可缓存性。 从种子的哈希值派生每个可变属性（色调、姿势、表情）。相同种子 → 相同提示词 → 相同图像 → 永久只消耗一次额度。
• 为提示词模板添加版本号。 重新设计样式时，在缓存键中将 V=2 升级；旧头像会逐渐淘汰，新头像则按需重新生成。
• 回退方案不可或缺。 基于色调的首字母 SVG 必须始终可用。绝不能因为生成式 AI 返回 429，就让 UI 显示损坏的头像。
• 负面提示词很重要。 始终排除 text, watermark, letters, realistic face of specific person——头像不得与现实中的名人相似，也不得意外生成文字。
• 不要在每次页面加载时都生成。 每个种子只生成一次，并永久缓存（或直到模板版本升级）。病毒式增长的注册量不应引发生成式 AI 调用量激增。
• 使用 Drive 存储。 --save-to-drive --drive-folder avatars 可提供稳定的 CDN URL，无需额外基础设施。
• 上线前预热缓存。 为现有用户批量生成头像；不要让线上流量在冷缓存上运行。
• 尊重用户上传的图片。 如果用户上传了真实照片，就返回该照片——绝不要覆盖。AI 头像仅用于缺少照片的情况。
• 在边缘节点限流。 限制每个 IP 每小时的生成式 AI 调用次数。机器人探测 /avatar/:random，几分钟内就能耗尽额度预算。

常见问题

问题	修复方法
每次刷新后重新生成的头像看起来都不一样	提示词不具备确定性——对种子进行哈希运算，派生属性，不使用随机数生成器或时间戳
重新设计样式后缓存永远不会失效	为提示词模板添加版本号（在缓存键中使用 V=3）
AI 生成了看起来像真人、与名人相似的脸	添加 negativePrompt: "realistic face of specific person, celebrity, known individual"
头像中出现文字或水印	添加 negativePrompt: "text, watermark, letters, logos"
机器人流量耗尽额度预算	按 IP 限流；仅允许已认证用户调用生成器；匿名用户回退到首字母头像
生成式 AI 返回 429，导致头像 UI 损坏	链条的最后一步必须是 SVG 首字母回退方案
批量回填部分失败	gen-ai batch resume <out> 仅重试失败项
应用中头像样式不一致	提交提示词模板；绝不允许调用方传入原始提示词

验证

运行 gen-ai whoami 确认身份验证，然后使用 --debug 重新运行失败的命令。

成本与耗时

任务	额度	耗时
1 个头像（Recraft V4，插画风格）	1-2	~4-8s
1 个头像（Flux 2 Pro，照片级真实感）	3-5	~10-15s
1 个头像（Gemini 3.1 Flash，草稿）	1	~3-5s
首字母 SVG 回退方案	0	<1ms
缓存读取（KV/Redis 命中）	0	~2-5ms
并发数为 4 时批量处理 500 个	~750-1000	~15-20 min

稳定运行后，预计缓存命中率 >99%——持续成本接近于零。

另请参阅

• gen-ai-use.md — CLI 参考、身份验证，以及使用 --json --no-input / jq 编写脚本
• gen-ai-batch.md — 清单结构、批量续跑、限流策略、Cloudflare Worker 模式
• gen-ai-workflows.md — 工作流 6（头像照工作室），用于美化上传的照片
• dev-og-image-service — OG 卡片使用相同的缓存与确定性模式