higgsfield-recipes

name	higgsfield-recipes
description	Shared library of Higgsfield MCP prompt patterns used by `saas-visual-generator` and `saas-landing-builder`. Auto-activate when another skill is about to call `mcp__higgsfield__generate_image`, `mcp__higgsfield__generate_video`, or `mcp__higgsfield__media_upload`. Centralizes the model picks, aspect ratios, durations, negative prompts, and output paths used across the flow.

Higgsfield Recipes

The single source of truth for "how we talk to Higgsfield". Other skills read this; you should too before any Higgsfield call.

Available MCP tools

• mcp__higgsfield__generate_image — primary for logos + moodboard + static graphics
• mcp__higgsfield__generate_video — primary for hero loop + animated logo reveal + feature micro-loops
• mcp__higgsfield__media_upload + mcp__higgsfield__media_confirm — when feeding a local image (e.g. the approved logo) into a video generation
• mcp__higgsfield__job_status + mcp__higgsfield__job_display — poll long-running jobs
• mcp__higgsfield__balance + mcp__higgsfield__transactions — check credits BEFORE long batches
• mcp__higgsfield__models_explore — discover available models / params at runtime
• mcp__higgsfield__list_workspaces + mcp__higgsfield__select_workspace — workspace selection if user has multiple

Pre-flight (run once per session)

1. Call mcp__higgsfield__balance. If insufficient credits for the batch you're about to run, surface to the user before starting.
2. If multiple workspaces, confirm the active one with mcp__higgsfield__list_workspaces. Use the one tied to this project if obvious; otherwise ask once.
3. Call mcp__higgsfield__models_explore if you need to pick a specific image or video model — the available list can change.

Default parameters

Images (logo + brand identity board + hero poster)

Locked model: gpt_image_2 for every mcp__higgsfield__generate_image call in this plugin. It's required on every call.

Why: best text rendering on the platform (hex labels, type specimens, logo wordmarks, button copy). The brand identity board leans heavily on legible in-image text.

Default params per asset type are listed in prompts.md under "Model selection (LOCKED)". Always include the universal negative-prompt fragment.

Videos (hero / logo reveal / feature loops)

• Hero loop: aspect 16:9, duration 6–10s, prompt for loopable motion.
• Animated logo reveal: aspect 1:1 or 16:9, duration 2–3s.
• Feature micro-loops: aspect 1:1, duration 3–5s.
• Output: MP4 (h.264). If the MCP returns WebM, transcode in a follow-up step or accept it (Next.js handles both).

Saving outputs

Higgsfield returns a URL or job. The skill that called it is responsible for:

1. Polling job_status until done.
2. Fetching the asset URL.
3. curl-ing / saving the binary to the right path:
   • Brand assets → brands/<slug>/assets/...
   • Site motion → sites/<slug>/public/motion/...

Never leave assets only as URLs — the landing page needs them locally for offline-deterministic builds.

Cost discipline

• Check mcp__higgsfield__balance before any batch that needs > 4 images or > 1 video.
• If running low, ask the user before kicking off — don't surprise them.

Failure modes

Symptom	What to do
mcp__higgsfield__balance fails or returns 401	MCP not authenticated. Tell user to /mcp → authenticate higgsfield.
Single image gen returns blank/garbage	Refine prompt with the brief, retry once, then ask user.
Video job stuck > 10 min	Show user the job_display link and ask whether to wait or move on.
Asset URL 404 when fetching	Re-run job_status to get fresh URL, then retry.

Related

• prompts.md — concrete prompt patterns
• ../saas-visual-generator/logo-prompts.md — logo-specific
• ../saas-visual-generator/moodboard-prompts.md — moodboard-specific
• ../saas-landing-builder/animation-rules.md — motion-asset constraints