Higgsfield Generate

Submit jobs to any Higgsfield model. Wraps the

higgsfield

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

Step 0 — Bootstrap

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.

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.

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

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.

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

Marketing Studio

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

marketing_studio_video

and

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.

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

Click-to-Ad shortcut (URL-driven)

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

bash

# 1. Trigger fetch (returns the product id and starts background scrape)
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
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.

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

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.

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

higgsfield-generate

NPX Install

Tags

SKILL.md Content

Higgsfield Generate

Step 0 — Bootstrap

UX Rules

Workflow — generic generation

Media flags

Common params

Marketing Studio

Concepts

UX rules (additional)

Workflow — quick ad video

Click-to-Ad shortcut (URL-driven)

Workflow — marketing image

Errors

Reference docs