Higgsfield CLI Soul ID训练指南：3张照片打造高保真人脸角色，跨模型无限复用

Higgsfield CLI 是一款开源的终端 AI 工具，可以在命令行里调用 40+ 个顶级图像、视频与音频模型。它的 Soul ID 功能最实用：只需上传 3 张同一人的照片，就能训练出一个高保真的"人脸角色"，之后在任意兼容的图像模型中无限复用——生成的每张图片都会是"你"的脸。本指南带你用终端从零完成"3 张照片 → 训练 → 跨模型复用"的完整流程。

什么是 Soul ID？

简单说，Soul ID 就是终端里的数字形象资产：

• 📸 一次训练：上传 3 张清晰照片，训练出专属人脸参考（得到一个 soul_id）
• 🔁 无限复用：soul_id 是持久资产，训练一次后可在多个兼容模型中反复使用
• ⌨️ 脚本化：全流程命令化，可以写进脚本、批量生成

相关模型参数详情可查阅官方模型文档：MODELS.md。

60 秒安装 Higgsfield CLI

Higgsfield CLI 提供三种安装方式，任选其一即可（详见 install.sh 与 README.md）：

方式	适用系统	安装命令
npm（推荐新手）	跨平台，含 Windows	npm install -g @higgsfield/cli
Homebrew	macOS / Linux	brew install higgsfield-ai/tap/higgsfield
安装脚本	macOS / Linux	克隆仓库后执行仓库根目录的 install.sh

安装完成后，终端会获得 higgsfield（以及 higgs 快捷方式）命令。输入 higgsfield version 能输出版本信息，就说明装好了。

登录并启动 Soul ID 训练

第一步：登录账号

higgsfield auth login

第二步：用 3 张照片训练你的 Soul ID

准备 3 张同一人的照片（建议不同角度、光线清晰、面部无遮挡），然后在终端执行：

higgsfield soul-id create --name me --soul-2 \
  --image ./me1.jpg --image ./me2.jpg --image ./me3.jpg

higgsfield soul-id wait <soul_id>

命令说明：

• --name me：给这个角色起的名字，随便取
• --soul-2：指定使用 Soul 2 系列
• --image：可以重复传 3 次，对应 3 张训练照片
• soul-id wait <soul_id>：等待训练完成，训练成功后会返回结果

完整示例参考：README.md。

跨模型复用你的 Soul ID 角色

训练完成后，真正的价值才体现——把 soul_id 传给兼容的图像模型即可：

higgsfield generate create text2image_soul_v2 \
  --prompt "professional portrait, neutral background, soft daylight" \
  --soul-id <soul_id> \
  --wait

一条命令，就得到一张"你"的专业肖像照。把 --prompt 换成不同场景（商务、街拍、古装、电影感……），你的数字形象可以出现在任何画面里。

哪些模型支持 Soul ID？

目前文档中带有 --soul-id（或 --custom-reference-id）参数的模型包括：

模型	job_set_type	特点
Higgsfield Soul V2	text2image_soul_v2	通用文生图 + 人脸角色，支持 1.5k / 2k 质量档位
Soul Cinematic	soul_cinematic	电影感画面，支持多种宽高比

更多 Soul 系列模型（如 soul_location、soul_cast）可在 MODELS.md 中查看各自参数表。

常用命令与全局参数速查

核心子命令

命令	用途
higgsfield auth	登录 / 登出 / 查看令牌
higgsfield soul-id	训练和管理 Soul 人脸角色
higgsfield generate	创建 / 查询 / 等待生成任务
higgsfield model	查看模型列表与参数
higgsfield upload	上传图片 / 视频 / 音频
higgsfield account	查看积分余额与消费记录

全局参数

参数	作用
--wait	阻塞等待任务完成，直接打印结果 URL
--wait-timeout	最长等待时间（默认 10 分钟）
--wait-interval	轮询间隔（默认 3 秒）
--json	输出机器可读的 JSON，方便脚本处理

参数说明详见 README.md。

常见问题排查

提示 Session expired 或 Not authenticated 令牌有效期较短，重新执行一次即可：

higgsfield auth login

提示 Unknown model "<name>" 模型目录会持续更新，执行 higgsfield model list 查看当前可用模型名。

参考文件

• 项目主文档：README.md
• 模型参数总表：MODELS.md
• 一键安装脚本：install.sh
• 许可证：LICENSE

掌握 Soul ID 后，建议接着探索 Higgsfield CLI 的视频模型（如 Seedance 2.5、Kling v3.0）与工作流命令，把你训练好的数字形象延伸进视频创作里 🚀