higgsfield-generate

version	0.3.0
name	higgsfield-generate
description	Generate images and videos via Higgsfield AI through 30+ models including Nano Banana 2, Soul V2, Veo 3.1, Kling 3.0, Seedance 2.0, Flux 2, GPT Image 2, plus Marketing Studio for branded ad video/image with curated avatars and imported products. Use when: "generate an image", "make a picture", "create artwork", "make a video", "animate this photo", "image-to-video", "img2vid", "edit this image with AI", "stylize a photo", "remix this image", "produce a clip", "render a scene", "create an ad", "make a UGC video", "generate marketing video", "make a product demo", "create unboxing", "TV spot", "virtual try-on", "product showcase", "brand video", "presenter video for product", "import product from URL", "create avatar for ad". Supports text-to-image, image-to-image, image-to-video, reference-based generation, and Marketing Studio (avatars + products + ad modes). Auto-detects whether passed IDs are uploads or previous jobs. Chain with higgsfield-soul-id when the user wants their face in the output. NOT for: training Soul Character (use higgsfield-soul-id), professional product photoshoots with mode-specific prompt enhancement (use higgsfield-product-photoshoot), text-only / chat / TTS tasks.
argument-hint	[prompt] [--model <name>] [--image <path-or-id>]
allowed-tools	Bash

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:

1. If higgsfield is not on $PATH, install it:

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

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

Credits & cost — read before any generation

Every MCP / CLI generation burns real credits, even on an "Unlimited" plan. Higgsfield's "Unlimited" / "365 Unlimited" entitlements (GPT Image 365, Seedance 1.5 Pro, Kling 2.6, Nano Banana, etc.) apply ONLY to manual generation in the web app (Image/Video/Cinema Studio). The API/MCP/CLI always draws down the credit balance at the nominal rate.

• Never tell the user a model is "free" just because it shows Unlimited on their plan — through this skill it costs credits.
• A cost preflight (get_cost: true) returns the nominal price (not zero) for unlimited models; it does not reflect the web-app entitlement.
• Watch the balance: higgsfield account status before and after a batch.
• Indicative MCP costs: Seedance 1.5 Pro ~2.4 (480p/4s), Kling 2.6 ~10 (5s), Veo 3.1 ~11 (4s), gpt_image_2 ~4 (1k/high) / ~7 (2k/high).
• For genuinely free generation on an unlimited model, the user must generate manually in the web UI — or use the web-API replay method below.

Free generation under an Unlimited plan (web-API replay)

Replay the web app's own API call from a logged-in browser page (gstack /connect-chrome → persistent profile) to get unlimited generation for free. The use_unlim:true flag is what makes it free.

• Endpoint: POST https://fnf.higgsfield.ai/jobs/v2/seedance1_5
• Auth: Bearer <token> from await window.Clerk.session.getToken() in the page context — refresh the token every clip (Clerk JWTs expire ~60s; reusing one across a loop → 401s).
• Do NOT send credentials:'include' (stricter CORS → "Failed to fetch").
• Body must include "use_unlim": true both top-level and inside params. Upload start-frames via MCP media_upload first (free, no DataDome), then inject the returned id as medias[].data.id.

Hard limits / gotchas:

• DataDome anti-bot: rapid direct fetches trip DataDome → 403 HTML page; does not cool down in minutes. Throttle hard or accept partial + resume later. The real UI "Generate" button keeps working.
• 16-concurrent-job cap (Team): the 17th in-flight job fails. Submit in waves of ≤14, let them drain (~3 min/render) before the next wave.
• Browser instability: headed Chromium drops the Clerk session / goes about:blank after ~150s of heavy use. Keep in-page loops < ~120s; reconnect (browse connect) on crash — the persistent-profile login is restored.
• Start-frame swap bug: re-uploading into an occupied <input type=file> silently fails (the slot only accepts an upload when empty) → every clip animates the same image. Fix: pass medias[].data.id directly in the body.
• MCP generate_video has NO audio for seedance_1_5 (clips are silent). For audio via MCP use Veo 3.1 / Kling / Seedance 2.0 (they cost credits). To force English native audio in the prompt: AUDIO IN ENGLISH ONLY: a warm female voice says: "<line>". English speech only, no Chinese.
• To stop the model spinning a flat ad graphic: the jars are completely static and locked in place: they do NOT spin, do NOT rotate. Only the camera moves slowly forward.

Reconcile after firing (don't trust the in-page log — the page may die): call MCP show_generations and match params.medias[0].data.id (filter params.prompt for your batch's unique phrase) against your target media-id list; resubmit only the missing ones. Download via results.rawUrl.

UX Rules

1. Be concise. No raw IDs, no JSON dumps in chat. Print result URL when ready.
2. No internal jargon. Don't narrate "calling higgsfield cost", "polling job".
3. Detect the user's language from the first message and reply in it. Technical args (--aspect_ratio 16:9) stay English.
4. Don't batch-ask. Pick a sane default model and ask one thing at a time only if genuinely missing.
5. Don't pre-estimate cost in chat. Just submit unless the user asks — but remember every MCP/CLI run burns real credits even on an "Unlimited" plan (see Credits & cost above).
6. 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

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

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

3. Validate quickly. If unsure of params, run once and pass only what's needed. Use schema defaults otherwise. The server returns for non-fatal coercions (e.g. → closest match) and a structured error for invalid declared-param values.

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.

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

1. 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.
2. 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>.
3. Pick mode. Default ugc. Other slugs (canonical from MCP): tutorial, ugc_unboxing, hyper_motion, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. See references/marketing-modes.md.
4. Generate (one-shot).

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