Run Higgsfield better

Run Higgsfield better is a free agent skill maintained by Scopeful. It teaches an AI coding agent such as Claude Code, Cursor, Windsurf or Codex how to drive this tool correctly, so you do not have to re-explain it every session. Every published Scopeful skill is free and the install command is public, with no sign-in required. Install it with npx skills add higgsfield-ai/skills. Scopeful also tracks hand-verified USD pricing for 39 AI creative tools at https://www.scopeful.org/tools.

Routing playbook for every Higgsfield surface: 30+ models, Marketing Studio modes, Virality Predictor scoring, 4 workflows, prompt structure, polling and failure playbook. Points at the dedicated CLI and MCP install skills.

Tags: video, image, mcp, cli, higgsfield, marketing-studio, virality-predictor, workflows

Install

npx skills add higgsfield-ai/skills

Reference

name: higgsfield-better description: Use this skill whenever the user wants to generate image, video, 3D, or audio output with Higgsfield — through the CLI, the MCP, the higgsfield-ai/skills plugin pack, or the @higgsfield/client SDK. Triggers include any mention of "Higgsfield", "DoP", "make a Higgsfield video", "Higgsfield motion preset", "Marketing Studio", "Virality Predictor", "Soul character", "draw-to-video", "reframe", "voice-change", "dubbing", or asking an agent to render a shot, B-roll, ad, product photo, or music. Teaches model selection, prompt structure, the polling / cost / failure playbook, and points at the right install path for the chosen surface. For the CLI install itself see higgsfield-cli. For the MCP install itself see higgsfield-mcp.

Run Higgsfield better

Higgsfield ships four surfaces, all backed by the same platform.higgsfield.ai API: a CLI (@higgsfield/cli), a remote HTTP MCP at mcp.higgsfield.ai, a 4-skill plugin pack (higgsfield-ai/skills), and a TS/Node SDK (@higgsfield/client). Pick the surface that matches how the user is running the agent, then use this skill for the model-selection and prompt-craft rules that apply to all of them. The mistakes agents make on Higgsfield are not surface-specific — they are the same three across all four:

1. Picking the wrong model for the task. Higgsfield exposes 30+ models and the defaults are good but not universal. "A cinematic push-in from a still" wants Seedance 2.0, not Soul V2. "A brand UGC ad with a presenter" wants Marketing Studio, not Veo 3.1. This skill is the routing table.
2. Burning credits on guesswork. Failed renders cost the user. NSFW, invalid preset, missing prompt, aspect ratio outside the enum — every one of these can be caught before submit. This skill is the preflight checklist.
3. Polling the wrong way. Renders take 30 to 120s for image-to-video, 2 to 15 minutes for Marketing Studio ad runs. Polling too fast hits rate limits, polling too slow wastes user time. This skill is the rhythm.

Surface selection (pick one, then load its install skill)

The four surfaces are not mutually exclusive. A common setup: install the CLI for terminal use and the MCP for in-editor use, both backed by the same higgsfield auth login account.

Install the higgsfield-ai plugin pack

The higgsfield-ai/skills repo (494 stars, MIT, version 0.3.0, 2026-06-22) ships four cross-agent skills. They are the deepest prompt-engineering reference for Higgsfield — this Scopeful master skill summarizes the routing; the plugin pack teaches the prompt craft.

Prerequisite

# install the CLI first (any of the 3 paths in the higgsfield-cli skill)
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
higgsfield auth login

Option 1 — npx skills (recommended, cross-agent)

npx skills add higgsfield-ai/skills

Works with Claude Code, Cursor, Codex, and any agent that picks up ~/.<agent>/skills/<name>/SKILL.md. Installs all four skills.

Option 2 — gh skill install

gh skill install higgsfield-ai/skills

Same coverage as Option 1. Requires GitHub CLI v2.90+.

Option 3 — Claude Code marketplace

Inside Claude Code:

/plugin marketplace add higgsfield-ai/skills
/plugin install higgsfield@higgsfield

Registers /higgsfield:generate, /higgsfield:soul-id, /higgsfield:product-photoshoot, /higgsfield:marketplace-cards.

Option 4 — setup script (universal fallback)

git clone --depth 1 https://github.com/higgsfield-ai/skills.git
cd skills
./setup

Auto-detects Claude Code / Cursor / Codex, installs the CLI if missing, checks auth, symlinks each skill into the agent's expected directory. Idempotent.

The 4 skills (one-liner per skill)

Chain: train Soul → use the reference_id in generate (Soul V2 models + identity-aware Marketing Studio). product-photoshoot and marketplace-cards are self-contained.

Model selection (the routing table)

30+ models, ~9 of which are the ones an agent will ever pick. The defaults below come from the upstream higgsfield-generate SKILL.md (verified 2026-06-30). Run higgsfield model list for the live catalog before assuming a slug exists.

Image — pick by brief

Video — pick by brief

3D, audio, voice

• 3D mesh/GLB from 1 to 4 reference images: multi_image_to_3d (add --should_texture true when the asset needs texture).
• Sound effects / ambience / foley / impacts: mirelo_text_to_audio. Requires --prompt + --duration. No media input.
• Music / backing tracks / jingles / instrumental beds: sonilo_music. Requires --prompt + --duration. No media input.
• Text to speech: text2speech_v2. Pick engine with --model (elevenlabs, minimax, seed_speech, vibe_voice, cozy_voice) and voice with --voice_type (preset or element) + --voice_id. Discover voices with higgsfield voices list.

Marketing Studio (branded ads, the underused surface)

Marketing Studio is the surface for "I have a product and I want an ad video." It chains: a product entity (imported from URL or built from uploaded images) + an optional avatar (presenter face, preset or custom) + an optional hook (reusable opening angle) + an optional setting (reusable environment) + a mode (UGC, how-to, unboxing, product showcase, review, TV spot, virtual try-on, wild card).

Modes (9)

ugc (default), ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on.

One-liner: Click-to-Ad (URL-driven)

# 1. Trigger fetch (returns the product id, import runs in the background)
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

Two ad approaches are mutually exclusive

Either the user gives an ad reference video (reference-driven) or picks hook/setting blocks (composed-from-blocks) — never both. If hook/setting are picked, do not offer to attach an ad reference. If a reference is attached, do not offer hook/setting.

Hook/setting are valid only for ugc, ugc_how_to, ugc_unboxing, product_review, ugc_virtual_try_on — not for product_showcase, tv_spot, wild_card, or virtual_try_on.

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 on marketing_studio_video (unlike seedance_2_0). Bump --wait-timeout 30m for long ad runs.

Virality Predictor (the underrated tool)

brain_activity analyzes a finished video for hook strength, attention, retention, distraction risk. It returns text, not media. Customer-facing name: Virality Predictor. Technical job_set_type: brain_activity. Route "analyze this video", "score this ad", "evaluate the hook" to it even though it shows up under text/analysis models — classify by intent, not by output category.

higgsfield generate create brain_activity --video ./ad.mp4 --wait

Report shape (one-liner, no internals):

Overall score: 44/100
Peak hook: 49% at 1s
Sustain: 89%
Strongest region: Visual Cortex
Risk: Default Mode is high — possible mind-wandering.

Open report: <report_url>

Higher Visual / Auditory / Language / Attention scores = stronger stimulus and focus. Lower Default Mode = less mind-wandering. The CLI prints an Open report URL; send that for the visual report. Do not surface brain_example_url, vertexMapBinaryUrl, vertexMapUrl in normal chat — they are implementation details.

Workflows (the 4 that combine existing assets)

higgsfield workflow list is the live catalog. Current shape (2026-06-30):

• draw_to_video — edit a source clip with a sketch frame at a specific timestamp. --video, --sketch, --timestamp, --prompt. Use for "change the jacket to red at 3 seconds."
• reframe — re-aspect a source video. --video, --aspect-ratio, --resolution. Use for "turn this 16:9 into a 9:16 for Reels."
• voice-change — replace the voice on a source video. --video, --voice_type (preset or element), --voice_id. Run higgsfield voices list for IDs.
• dubbing — dub a source video into another language. --video, --target_language (ISO-639-3: eng, spa, fra, deu, jpn, …).

Create through higgsfield generate workflow <name> ... --wait. Cost via higgsfield generate cost workflow <name> ... (not supported for voice-change or dubbing).

Prompt structure that Higgsfield rewards

Higgsfield prompts are not freeform. They have three slots, and skipping any of them produces mediocre output:

1. Subject. What is in frame. Keep it concrete. red 1970 muscle car parked on wet asphalt, not a cool car.
2. Camera or motion direction. For image: lens, lighting, framing. For video: motion preset (push-in, orbit, parallax, dolly-zoom, whip-pan, static) — pick from the preset list, do not invent one.
3. Style modifier. e.g. shot on 35mm, neon-lit, moody cinematic, golden hour.

Bad: cool video of a car driving fast Good: red 1970 muscle car parked on wet asphalt, motion: slow push-in, style: rain-soaked neon noir, 35mm anamorphic

When the user gives vague input, ask one clarifying question before generating: which preset, which style, which mode. Do not burn a render trying to guess.

Live feedback (the polling rhythm)

For the CLI: pass --wait. It blocks until the job reaches a terminal state and prints the result URL on stdout. Default 10 minutes, default 3s poll interval.

For the MCP: synchronous job-id returns, then poll a status tool every 10 seconds. Faster polling hits rate limits; the upstream API enforces a minimum interval.

For the plugin pack (higgsfield-generate): follow its higgsfield generate create <jst> ... --wait rule. Avoid create then wait as two steps.

For the TS SDK: subscribe(endpoint, { withPolling: true }). The SDK polls /requests/{request_id}/status automatically. Status values are queued / in_progress / nsfw / failed / completed. The SDK maps API responses to JobSet with isCompleted, isQueued, isInProgress, isFailed, isNsfw helpers.

For Marketing Studio ad runs: bump --wait-timeout 30m (default is 10m, ad renders regularly exceed it).

What to do when a render fails

Read the failure code from the response. Map it:

• Missing required params: prompt — user gave no prompt; ask for it.
• Missing required params: medias on brain_activity — pass exactly one video via --video <path-or-id>.
• Invalid values: aspect_ratio=99:99 (allowed: ...) — bad enum; pick from the allowed list.
• Unknown params: foo — schema does not accept that flag; run higgsfield model get <jst> to see what it does accept. If this fires for hook_id or setting_id, the selected model does not support Marketing Studio setup items.
• Session expired / Not authenticated — higgsfield auth login (CLI) or browser re-auth (MCP).
• NSFW content filter — ask the user to rephrase rather than retrying the same prompt.
• Source image too small — upscale or re-crop before retrying.

Do not auto-retry more than once. Failed renders cost the user, even when they fail.

Pricing gotchas (so you don't burn the user's credits)

• Default duration is 5 seconds; pass it explicitly only when the brief needs more.
• Higher resolution costs more credits per second. Check Scopeful's /tools/higgsfield for the current credit math — pricing is verified monthly and the seed is updated when Higgsfield changes its plans.
• Marketing Studio ad runs cost more than raw model runs because of the avatar / product / brand-kit setup. Estimate before kicking off a batch.
• Failed renders still consume credits on some plans. Verify the prompt + preset before kicking off batches.
• The CLI's --retry flag does not refund the first render — it is a new render.
• Render URLs expire (the CLI documentation says 7 days for some result types). Download or rehost immediately.

Useful follow-ups after a successful render

• Chain a second clip with a different preset for a multi-shot sequence.
• For ads: hand the result to Virality Predictor to score the hook before iterating further.
• For product shots: hand the result to higgsfield-product-photoshoot to expand the variant set (different modes, different angles).
• Suggest pairing with ElevenLabs for VO or Sonilo Music for the soundtrack if the user is building an ad.

When NOT to reach for Higgsfield

• The user wants a long-form (>10s) sequence. Chain Veo or Sora instead.
• The user wants pure text-to-video without thinking about camera language — the prompt will be under-specified and the result mediocre. Reframe first, then generate.
• The user is iterating on the subject, not the shot. Use an image model first (GPT Image 2, Soul V2, Nano Banana Pro), then bring the still into Higgsfield for the motion pass.
• The user wants photoreal raw video. Reach for Veo 3.1 or Kling 3.0 first; Higgsfield's strength is stylized / cinematic / motion-design shots, not photoreal.