Higgsfield 灵魂角色 (Soul Character)

Higgsfield 灵魂角色 (Soul Character) 是做什么的？

训练一个忠实于面部的身份模型。可复用于所有由灵魂驱动的生成任务。

步骤 0 — 启动前准备

在执行任何其他命令之前：

1. 如果系统中没有安装 higgsfield，请安装：

   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   

2. 如果 higgsfield account status 返回 Session expired / Not authenticated，请让用户运行 higgsfield auth login（交互式）并等待确认。
3. 灵魂训练需要付费计划（Basic+）。如果 higgsfield account status 显示为免费计划，请在提交前告知用户。

用户体验规则

1. 简洁明了。不要在聊天中显示原始 ID，只需说“灵魂就绪”并带上名称引用即可。
2. 检测用户语言并以此回复。CLI 参数保持英文。
3. 只询问最少的输入信息：名称 + 照片。选择一个合理的模型变体。
4. 轮询是静默的——训练需要几分钟。不要重复更新状态。

工作流程

1. 获取名称。 一个单词，用于后续引用。如果缺少则询问。
2. 获取照片。 5–20 张面部照片，需要不同的角度和光照。本地路径或已上传的 ID 均可——--image 接受两者。
3. 选择变体。
   • --soul-2 — 用于图像生成（默认）
   • --soul-cinematic — 用于电影/视频作品 根据用户声明的下游用途选择。默认使用 --soul-2。
4. 提交。

   higgsfield soul-id create --name "<名称>" --soul-2 --image ./photo1.png --image ./photo2.png ...
   higgsfield soul-id create --name "<名称>" --soul-2 --image <上传ID> --image <上传ID> ...
   

   CLI 会自动上传路径。捕获返回的 reference id。
5. 等待。 higgsfield soul-id wait <id>。静默执行。超时默认 30 分钟。
6. 交付。 “灵魂 <名称> 就绪。在生成中使用 --soul-id <id> 参数。”

使用灵魂

训练完成后，传递给 higgsfield-generate：

higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <ref_id> --quality 2k --wait
higgsfield generate create soul_cinematic --prompt "..." --soul-id <ref_id> --quality 2k --wait

列出已有的灵魂

higgsfield soul-id list                   # 所有引用
higgsfield soul-id get <id>               # 按 ID 查询单个

错误处理

• Minimum Basic plan required — 用户是免费计划；告知他们。
• Training failed — 检查照片质量（5+ 张不同的面部，光照充足）。
• Session expired → higgsfield auth login。

参考文档

• references/photo-guide.md — 什么照片效果最好
• references/troubleshooting.md — 常见的训练失败原因