Higgsfield 生成工具

向任意Higgsfield模型提交任务。封装了

higgsfield

CLI，涵盖通用图片/视频生成以及Marketing Studio（品牌广告、虚拟形象、产品）功能。

步骤0 — 初始化

在执行任何其他命令之前，请确保CLI已安装并完成身份验证：

如果

higgsfield

不在

$PATH

中，请安装它：

bash

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

如果
```
higgsfield account status
```
返回
```
Session expired
```
/
```
Not authenticated
```
错误，请让用户运行
```
higgsfield auth login
```
（交互式操作，会打开浏览器），并等待用户确认完成后再继续。

如果

higgsfield account status

已能显示账户信息，则可跳过上述两项检查。

用户体验规则

保持简洁。聊天中不显示原始ID或JSON输出。任务完成后输出结果URL即可。
避免内部行话。不要提及“调用higgsfield成本”、“轮询任务”等内容。
根据用户的第一条消息检测其语言，并使用该语言回复。技术参数（如
```
--aspect_ratio 16:9
```
）保留英文。
不要批量提问。选择合理的默认模型，仅当确实缺少必要信息时才逐个提问。
不要预先估算成本。除非用户询问，否则直接提交任务。
向
```
generate create
```
命令添加
```
--wait
```
参数，让命令阻塞直到任务完成并自行打印结果URL。避免使用先
```
create
```
再
```
wait
```
的两步模式。

工作流程 — 通用生成

选择模型。根据生产使用经验推荐以下实用默认模型：

图片生成：
- 品牌产品视觉内容（Pinterest图、生活场景图、主横幅、广告包、虚拟试穿）→ 请使用
```
higgsfield-product-photoshoot
```
  ，而非本工具。
- 带有虚拟形象+产品的品牌广告图片（Marketing Studio类型）→ Marketing Studio 图片生成（详见下方Marketing Studio章节）
- 具有美感的UGC/时尚编辑/生活场景人物 → Soul 2.0
- 电影静帧 → Soul Cinema
- 极具特色的创意角色（纯文本描述、辨识度高）→ Soul Cast
- 地点/环境/无人场景 → Soul Location（同类最佳）
- 矢量插画或面部编辑+复杂场景替换 → Seedream 4.5
- Soul Character（来自
```
higgsfield-soul-id
```
  的参考ID）→ 静态图使用Soul 2.0，电影级内容使用Soul Cinema
- 快速低成本迭代 → Z Image
- 角色或卡通风格作品 → Nano Banana 2；复杂场景可升级至Nano Banana Pro
- 其他所有场景默认选择 → GPT Image 2。适用于平面设计、UI、横幅、排版以及高保真通用生成。
视频生成：
- 所有广告/商业/品牌广告视频 → Marketing Studio（详见下方Marketing Studio章节）
- 通用严肃视频默认选择（多镜头、一致身份、动态丰富）→ Seedance 2.0。当前最优模型（SOTA）。
- 无强动态的单平面场景，比Seedance 2.0成本更低 → Kling 3.0
- 无镜头切换的低成本清晰镜头 → Seedance 1.5 Pro
- 电影级最高保真度 → Cinema Studio Video 3.0
- 低成本且物理效果逼真，无需音频 → Minimax Hailuo
- 快速批量生成 → Veo 3.1 Lite
要获取传递给
```
higgsfield generate create
```
的实际
```
--model
```
ID，请运行
```
higgsfield model list --json | jq
```
来映射显示名称与ID。完整对照表请查看
```
references/model-catalog.md
```
。
直接将媒体输入传递给参数。媒体参数接受本地文件路径或UUID。CLI会自动上传文件路径对应的内容，并自动检测UUID对应的是任务ID还是上传ID。无需预先上传。每个模型都会声明支持的角色（
```
image
```
、
```
start_image
```
、
```
end_image
```
、
```
video
```
、
```
audio
```
）→ 详见
```
references/media-inputs.md
```
。
快速验证。若不确定参数，可运行一次
```
higgsfield model get <jst> --json
```
，仅传递必要参数。否则使用 schema 默认值。服务器会针对非致命强制转换返回
```
adjustments
```
（例如
```
aspect_ratio=99:99
```
会转为最接近的有效值），针对无效的声明参数值返回结构化错误。
一次性提交并等待。执行
```
higgsfield generate create <jst> --prompt "..." [媒体参数] [其他参数] --wait
```
。命令会阻塞直到任务进入终端状态，并在标准输出打印结果URL。可调参数：
```
--wait-timeout 20m
```
（默认10分钟）、
```
--wait-interval 5s
```
（默认3秒）。
交付结果。发送结果URL加上一行摘要（包含模型名称，视频需包含时长）。

如需查看或重新运行过往任务，可使用

higgsfield generate list --json

和

higgsfield generate get <id> --json

进行追溯。如果之前启动任务时未添加

--wait

，仍可使用

higgsfield generate wait <id>

重新等待任务完成。

媒体参数

参数	用途	支持的模型
`--image <path-or-id>`	参考图片	大多数图片模型、 `seedance_2_0` 、 `veo3` 、 `marketing_studio_video`
`--start-image <path-or-id>`	image-to-video转场的第一帧	`kling3_0` 、 `kling2_6` 、 `veo3_1` 、 `seedance_2_0` 、 `marketing_studio_video`
`--end-image <path-or-id>`	转场的最后一帧	`kling3_0` 、 `seedance_2_0` 、 `marketing_studio_video`
`--video <path-or-id>`	参考视频	`seedance_2_0`
`--audio <path-or-id>`	参考音频（唇形同步、配乐匹配）	`seedance_2_0` （请使用此参数，而非 `--generate-audio` ）

每个参数接受本地文件路径（会自动上传）或UUID（来自

higgsfield upload create

的上传ID，或过往任务ID）。每个模型通过

MEDIA_ROLES

声明其支持的角色集合。完整列表请查看

references/media-inputs.md

。

常用参数

参数会直接传递给模型schema。可使用

higgsfield model get <jst>

查看详细信息。

bash

higgsfield generate create gpt_image_2 --prompt "neon city at dusk" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "anime character concept, expressive pose" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "camera dollies in" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --wait

如需机器可读输出（用于链式流水线、Agent上下文），请添加

--json

参数。使用

--wait --json

会返回最终任务对象数组；不使用

--wait

则返回任务ID。

通过标准输入传递提示词：

echo "..." | higgsfield generate create z_image --wait

。

Marketing Studio

品牌图片/视频生成：虚拟形象+产品+广告风格模式。使用

marketing_studio_video

和

marketing_studio_image

模型。

核心概念

Avatar（虚拟形象） — 演示者面部。可选择预设形象（运行
```
higgsfield marketing-studio avatars list
```
浏览）或自定义形象（通过
```
higgsfield marketing-studio avatars create
```
上传照片创建）。
Product（产品） — 带有标题和参考图片的品牌商品。可从URL导入（
```
higgsfield marketing-studio products fetch --url ...
```
）或通过上传图片创建（
```
higgsfield marketing-studio products create
```
）。
Webproduct（网页产品） — App Store/网页版本。获取App Store URL时会自动路由。

额外用户体验规则

每个阶段只提一个问题。不要一次性询问产品、虚拟形象和模式。

工作流程 — 快速制作广告视频

获取产品。

通过URL →

higgsfield marketing-studio products fetch --url <url> --wait

（轮询直到导入完成）

通过本地图片 →

higgsfield upload create <photo>...

然后执行

higgsfield marketing-studio products create --title "..." --image <id>...

记录产品ID。

选择虚拟形象。

默认：运行
```
higgsfield marketing-studio avatars list
```
并选择符合品牌调性的预设形象。

自定义：

higgsfield marketing-studio avatars create --name "..." --image <upload_id>

。

选择模式。默认模式为

ugc

。其他模式标识（来自MCP的标准标识）：

ugc_how_to

、

ugc_unboxing

、

product_showcase

、

product_review

、

tv_spot

、

wild_card

、

ugc_virtual_try_on

、

virtual_try_on

。详见

references/marketing-modes.md

。

一次性生成。

bash

higgsfield generate create marketing_studio_video \
  --prompt "..." \
  --avatars '[{"id":"<avatar_id>","type":"preset"}]' \
  --product_ids '[<product_id>]' \
  --mode ugc \
  --duration 15 \
  --resolution 720p \
  --aspect_ratio 9:16 \
  --wait

分辨率支持

480p

或

720p

。宽高比支持

auto

21:9

16:9

4:3

1:1

3:4

9:16

。此处支持

--generate-audio true

（与

seedance_2_0

不同）。

--wait

会阻塞直到任务完成；对于较长的广告制作，可将

--wait-timeout

调整为

30m

。

交付结果。发送结果URL加上一行摘要（包含模式、时长）。

一键生成广告快捷方式（基于URL）

当用户提供产品URL并希望一次性生成营销视频时：

bash

# 1. 触发获取（返回产品ID并启动后台抓取）
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. 基于同一URL生成营销视频 — 后端会复用已有的实体
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

后端会根据URL去重，因此重复运行会复用现有实体，无需重新抓取。

工作流程 — 营销图片生成

与上述流程相同，但使用

marketing_studio_image

模型：

bash

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

错误处理

```
Missing required params: prompt
```
→ 用户未提供提示词；请询问用户。
```
Invalid values: aspect_ratio=99:99 (allowed: ...)
```
→ 参数值无效；从允许的选项中选择。

Unknown params: foo

→ schema不接受该参数；请查看

higgsfield model get <jst>

。

```
Session expired
```
→ 请运行
```
higgsfield auth login
```
重新登录。

更多错误处理请查看

references/troubleshooting.md

。

参考文档

按需加载：

```
references/model-catalog.md
```
— 为任务选择合适的模型
```
references/prompt-engineering.md
```
— 编写有效的提示词
```
references/media-inputs.md
```
— 图片/视频参考流程
```
references/troubleshooting.md
```
— 常见错误及修复方案
```
references/marketing-avatars.md
```
— 预设与自定义虚拟形象
```
references/marketing-products.md
```
— URL抓取与手动创建产品对比
```
references/marketing-modes.md
```
— Marketing Studio所有模式

higgsfield-generate

NPX安装

标签

SKILL.md 内容（中文）

Higgsfield 生成工具

步骤0 — 初始化

用户体验规则

工作流程 — 通用生成

媒体参数

常用参数

Marketing Studio

核心概念

额外用户体验规则

工作流程 — 快速制作广告视频

一键生成广告快捷方式（基于URL）

工作流程 — 营销图片生成

错误处理

参考文档