higgsfield-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Higgsfield Generate

Higgsfield 生成工具

Submit jobs to any Higgsfield model. Wraps the

higgsfield

CLI. Covers generic image/video gen and Marketing Studio (branded ads, avatars, products).

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

higgsfield

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

Step 0 — Bootstrap

步骤0 — 初始化

Before any other command, make sure the CLI is installed and authenticated:

higgsfield

is not on

$PATH

, install it:

bash

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

If
```
higgsfield account status
```
fails with
```
Session expired
```
/
```
Not authenticated
```
, ask the user to run
```
higgsfield auth login
```
(interactive, opens a browser) and wait for them to confirm before continuing.

Skip both checks if

higgsfield account status

already prints account info.

在执行任何其他命令之前，请确保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

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

UX Rules

用户体验规则

Be concise. No raw IDs, no JSON dumps in chat. Print result URL when ready.
No internal jargon. Don't narrate "calling higgsfield cost", "polling job".
Detect the user's language from the first message and reply in it. Technical args (
```
--aspect_ratio 16:9
```
) stay English.
Don't batch-ask. Pick a sane default model and ask one thing at a time only if genuinely missing.
Don't pre-estimate cost. Just submit unless the user asks.
Pass
```
--wait
```
to
```
generate create
```
so the command blocks until done and prints the result URL itself. Avoid the two-step
```
create
```
→
```
wait
```
pattern.

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

Workflow — generic generation

工作流程 — 通用生成

Pick a model. Practical defaults from production use:

Image:
- Brand product visual (Pinterest pin, lifestyle, hero banner, ad pack, virtual try-on) → use
```
higgsfield-product-photoshoot
```
  instead. NOT this skill.
- Branded ad image with avatar + product (Marketing Studio shape) → Marketing Studio Image (see Marketing Studio below)
- Aesthetic UGC / fashion editorial / lifestyle character → Soul 2.0
- Cinematic still frame → Soul Cinema
- Highly characterful creative persona (text-only, distinctive) → Soul Cast
- Locations / environments / no-people scenes → Soul Location (best in class)
- Vector illustrations OR face edit + complex scene swap → Seedream 4.5
- Soul Character (reference id from
```
higgsfield-soul-id
```
  ) → Soul 2.0 for stills, Soul Cinema for cinematic
- Fast and cheap iteration → Z Image
- Character or cartoon-style work → Nano Banana 2; step up to Nano Banana Pro on hard cases
- Default for everything else → GPT Image 2. Graphic design, UI, banners, typography, and high-fidelity general generation.
Video:
- All advertising / commercial / branded ad video → Marketing Studio (see Marketing Studio below)
- Default all-purpose serious video (multi-shot, consistent identity, motion-heavy) → Seedance 2.0. SOTA.
- Single-plane scene without strong dynamics, cheaper than Seedance 2.0 → Kling 3.0
- Cheap clean shot without cuts → Seedance 1.5 Pro
- Cinema-grade highest fidelity → Cinema Studio Video 3.0
- Cheap with strong physics, no audio needed → Minimax Hailuo
- Fast batch / volume → Veo 3.1 Lite
For the actual
```
--model
```
ID to pass to
```
higgsfield generate create
```
, run
```
higgsfield model list --json | jq
```
to map display names to IDs. See
```
references/model-catalog.md
```
for the full table.
Pass media inputs straight to flags. Media flags accept a local file path or a UUID. CLI auto-uploads paths and auto-detects job vs upload for UUIDs. No need to pre-upload. Each model declares accepted roles (
```
image
```
,
```
start_image
```
,
```
end_image
```
,
```
video
```
,
```
audio
```
) — see
```
references/media-inputs.md
```
.
Validate quickly. If unsure of params, run
```
higgsfield model get <jst> --json
```
once and pass only what's needed. Use schema defaults otherwise. The server returns
```
adjustments
```
for non-fatal coercions (e.g.
```
aspect_ratio=99:99
```
→ closest match) and a structured error for invalid declared-param values.
Submit and wait in one shot.
```
higgsfield generate create <jst> --prompt "..." [media flags] [param flags] --wait
```
. Blocks until terminal status and prints the result URL on stdout. Tunables:
```
--wait-timeout 20m
```
(default 10m),
```
--wait-interval 5s
```
(default 3s).
Deliver. Send the URL plus a one-line summary (model, duration if video).

To inspect or rerun later,

higgsfield generate list --json

and

higgsfield generate get <id> --json

work for retrospection.

higgsfield generate wait <id>

is still available if you ever need to rejoin a job started without

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

重新等待任务完成。

Media flags

媒体参数

Flag	Use for	Models that accept it
`--image <path-or-id>`	reference image	most image models, `seedance_2_0` , `veo3` , `marketing_studio_video`
`--start-image <path-or-id>`	first frame for image-to-video transitions	`kling3_0` , `kling2_6` , `veo3_1` , `seedance_2_0` , `marketing_studio_video`
`--end-image <path-or-id>`	last frame for transitions	`kling3_0` , `seedance_2_0` , `marketing_studio_video`
`--video <path-or-id>`	reference video	`seedance_2_0`
`--audio <path-or-id>`	reference audio (lipsync, soundtrack match)	`seedance_2_0` (use this, NOT `--generate-audio` )

Each flag accepts either a local file path (auto-uploaded) or a UUID (upload id from

higgsfield upload create

, or a previous job id). Each model declares its own role set via

MEDIA_ROLES

. See

references/media-inputs.md

for the full table.

参数	用途	支持的模型
`--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

。

Common params

常用参数

Flags pass through to model schema. Use

higgsfield model get <jst>

to discover.

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

For machine-readable output (chained pipelines, agent context), add

--json

. With

--wait --json

you get the final job object array. Without

--wait

, you get the job IDs.

Stdin prompt:

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

参数会直接传递给模型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

Branded image/video gen: avatars + products + ad-style modes. Use models

marketing_studio_video

and

marketing_studio_image

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

marketing_studio_video

和

marketing_studio_image

模型。

Concepts

核心概念

Avatar — presenter face. Curated

preset

(browse

higgsfield marketing-studio avatars list

) or

custom

(uploaded photos via

higgsfield marketing-studio avatars create

Product — brand item with title + reference images. Imported from URL (
```
higgsfield marketing-studio products fetch --url ...
```
) or created from uploaded images (
```
higgsfield marketing-studio products create
```
).
Webproduct — App Store / web page version. Auto-routes when fetching App Store URLs.

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时会自动路由。

UX rules (additional)

额外用户体验规则

One question per phase. Don't ask product+avatar+mode upfront.

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

Workflow — quick ad video

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

Get product.

URL →

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

(polls until import done)

Local images →

higgsfield upload create <photo>...

then

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

Capture product id.

Pick avatar.

Default:
```
higgsfield marketing-studio avatars list
```
and pick a preset matching the brand voice.

Custom:

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

Pick mode. Default

ugc

. Other slugs (canonical from MCP):

ugc_how_to

ugc_unboxing

product_showcase

product_review

tv_spot

wild_card

ugc_virtual_try_on

virtual_try_on

. See

references/marketing-modes.md

Generate (one-shot).

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

Resolution is

480p

720p

. Aspect ratio is one of

auto

21:9

16:9

4:3

1:1

3:4

9:16

--generate-audio true

is supported here (unlike

seedance_2_0

--wait

blocks until done; bump

--wait-timeout 30m

for longer ad runs.

Deliver. URL + one-line summary (mode, duration).

获取产品。

通过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加上一行摘要（包含模式、时长）。

Click-to-Ad shortcut (URL-driven)

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

When the user gives a product URL and wants a marketing video in one go:

bash

undefined

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

bash

undefined

1. Trigger fetch (returns the product id and starts background scrape)

1. 触发获取（返回产品ID并启动后台抓取）

higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

2. Generate the marketing video against the same URL — backend reuses the entity

2. 基于同一URL生成营销视频 — 后端会复用已有的实体

higgsfield generate create marketing_studio_video
--url https://shop.example.com/sneakers
--mode ugc
--duration 15
--aspect_ratio 9:16
--wait


Backend dedupes by URL, so repeated runs reuse the existing entity instead of re-fetching.

higgsfield generate create marketing_studio_video
--url https://shop.example.com/sneakers
--mode ugc
--duration 15
--aspect_ratio 9:16
--wait


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

Workflow — marketing image

工作流程 — 营销图片生成

Same as above but use

marketing_studio_image

model:

bash

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

与上述流程相同，但使用

marketing_studio_image

模型：

bash

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

Errors

错误处理

```
Missing required params: prompt
```
→ user gave no prompt; ask for it.

Invalid values: aspect_ratio=99:99 (allowed: ...)

→ bad enum; pick from allowed.

Unknown params: foo

→ schema doesn't accept that flag; check

higgsfield model get <jst>

```
Session expired
```
→
```
higgsfield auth login
```
.

See

references/troubleshooting.md

for more.

```
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

。

Reference docs

参考文档

Load on demand:

```
references/model-catalog.md
```
— picking the right model for the task
```
references/prompt-engineering.md
```
— writing prompts that work
```
references/media-inputs.md
```
— image/video reference flows
```
references/troubleshooting.md
```
— common errors and fixes
```
references/marketing-avatars.md
```
— preset vs custom avatars
```
references/marketing-products.md
```
— URL fetch vs manual product create
```
references/marketing-modes.md
```
— every Marketing Studio mode

按需加载：

```
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所有模式