higgsfield-recipes

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