Higgsfield Generate
Submit jobs to any Higgsfield model. Wraps the
higgsfield
CLI. Covers generic image/video gen and Marketing Studio (branded ads, avatars, products).
Prerequisites
higgsfield
CLI installed:
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
Authenticated:
higgsfield auth login
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
) → 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
--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
--wait (polls until import done) Local images → higgsfield upload create ... then higgsfield marketing-studio products create --title "..." --image ... 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 . 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). higgsfield generate create marketing_studio_video \ --prompt "..." \ --avatars '[{"id":" ","type":"preset"}]' \ --product_ids '[ ]' \ --mode ugc \ --duration 15 \ --resolution 720p \ --aspect_ratio 9 :16 \ --wait Resolution is 480p or 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:
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:
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