higgsfield-generate

name	higgsfield-generate
version	0.3.0
description	Use when the user wants to generate an image or video via Higgsfield AI. Covers 30+ models: Soul V2, Seedance 2.0, Kling 3.0, Veo 3.1, GPT Image 2, Nano Banana 2. Also covers Marketing Studio — branded ad video/image with avatars and products. Use whenever: "generate an image", "make a video", "animate this photo", "image-to-video", "img2vid", "edit this image with AI", "produce a clip", "create an ad", "make a UGC video", "marketing video", "brand video", "TV spot", "import product from URL", "create avatar for ad", "Seedance", "Kling", "Veo", "Soul gen", "Nano Banana", "Marketing Studio". Chain with higgsfield-soul-id when user wants a reusable face identity. NOT for: training a Soul Character (use higgsfield-soul-id), product photoshoots with mode-specific enhancer (use higgsfield-product-photoshoot), text/TTS. Requires Higgsfield CLI installed and authed.
argument-hint	[prompt] [--model <name>] [--image <path-or-id>]
allowed-tools	["Bash","Read","Write","Edit","Skill"]
author	Higgsfield AI (ported by moiz)
license	MIT
user-invocable	true
metadata	{"openclaw":{"emoji":"🎬"}}

/higgsfield-generate — AI Image & Video Generation via Higgsfield

Submit jobs to any Higgsfield model. Wraps the higgsfield CLI. Covers generic image/video gen and Marketing Studio (branded ads, avatars, products).

When to use

• User wants an image or video generated by AI — any model, any style
• "animate this photo", "make a video from an image", "img2vid"
• "create a UGC ad", "Marketing Studio video", "brand video with avatar"
• "import this product URL and make an ad"
• "generate a cinematic still", "make a character illustration"
• Anything involving Seedance, Kling, Veo, Soul, Nano Banana, Flux, GPT Image

Route elsewhere if:

• User wants to train a reusable face identity → higgsfield-soul-id
• User wants a mode-enhanced product photoshoot → higgsfield-product-photoshoot
• User just needs a one-off image without Higgsfield → image-gen (Gemini, free tier)

On Activation

1. Read brand/voice-profile.md, brand/visual-style.md, and brand/creative-kit.md if present. Use brand context to inform model choice and prompt style where relevant. All files are optional — zero-context operation is fine.
2. Check CLI: higgsfield account status. If not on $PATH, surface install command (see Optional dependency section). If session expired, prompt auth.
3. Pick a model from the workflow below. Ask one question at a time if context is missing.

Optional dependency — Higgsfield account

This skill requires the @higgsfield/cli binary and a Higgsfield account.

Without the CLI installed, return a clear actionable error:

higgsfield CLI not found. Install with:
  curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
Then authenticate:
  higgsfield auth login

Without an authed Higgsfield account, the CLI itself surfaces the auth prompt — no special handling needed in the skill.

Fallback for image generation only: if the user just needs a one-off image and doesn't have a Higgsfield account, route them to image-gen (Gemini, model gemini-3.1-flash-image-preview, free tier). Video generation, Marketing Studio, Soul Characters, and product modes have no fallback — they require Higgsfield.

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.

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. Just submit unless the user asks.
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 higgsfield model get <jst> --json once and pass only what's needed. Use schema defaults otherwise. The server returns adjustments for non-fatal coercions and a structured error for invalid declared-param values.

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

5. 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. 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, add --json. With --wait --json you get the final job object array.

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: 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: auto/21:9/16:9/4:3/1:1/3:4/9:16. --generate-audio true is supported here. 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.

Anti-Patterns

Anti-pattern	Why it fails	Instead
Using higgsfield-generate for product photoshoots	Bypasses the mode-specific prompt enhancer — output is noticeably lower quality for product brand imagery.	Route to higgsfield-product-photoshoot any time a product + specific output format is involved.
Batching all context questions upfront	Users disengage when asked 5 things at once. Model choice and media inputs can often be inferred.	Ask at most one clarifying question before submitting. Pick a sensible default.
Using --generate-audio with seedance_2_0	The flag isn't accepted by Seedance — it silently breaks.	Use --audio <path> for Seedance lipsync/soundtrack; use --generate-audio true only for marketing_studio_video.
Printing raw job JSON to chat	Dumps internal IDs and noise. Users want a URL.	Always extract and present only the result URL plus a one-line summary.
Picking the wrong model then iterating blind	Costs money and time.	Read references/model-catalog.md first, pick the right model once.

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

Attribution

Ported from higgsfield-ai/skills — MIT License, Copyright (c) 2026 Higgsfield AI. Adapted for mktg's drop-in contract on 2026-05-05.

Upstream version: 0.3.0 Upstream commit: 1dcfe2687c3a9092232bac55c2b6b9ae3fc717d7

Drift detection: if the upstream skill changes, re-run mktg-steal https://github.com/higgsfield-ai/skills to evaluate the diff.