name: higgsfield-mcp description: Use this skill whenever the user wants to generate video, animation, or motion-design output with Higgsfield through its CLI or MCP server. Triggers include any mention of "Higgsfield", "DoP", "make a Higgsfield video", "Higgsfield motion preset", or asking an agent to render shots/B-roll. Note that it now supports Text-to-Image generation (e.g., via flux-pro/text-to-image) as well.

Run Higgsfield MCP better

Higgsfield ships an MCP server, a CLI, official SDKs, and a REST API. Both work, but agents get the most out of Higgsfield when they understand three things up front: motion presets are the product, prompt structure is opinionated, and renders take longer than image generators. This skill teaches your agent those rules so it stops treating Higgsfield like a generic text-to-video API.

When to use Higgsfield

Use Higgsfield when the user wants:

• A specific camera move (push-in, orbit, parallax, dolly-zoom, whip-pan)
• Cinematic shots from a still image (image-to-video with motion)
• Short B-roll or ad cuts where the shot matters more than the subject
• Stylized motion design rather than photoreal video
• High-quality image generation via Text-to-Image (e.g., flux-pro/text-to-image)

Do not reach for Higgsfield when:

• 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

Install

You can use the CLI, official SDKs, or the direct REST API.

CLI:

npm install -g @higgsfield/cli
higgsfield auth login

Official SDKs:

• Python: pip install higgsfield-client
• Node.js: npm install @higgsfield/client

REST API: You can also use the direct REST API at https://cloud.higgsfield.ai/api/v1 with async polling.

For agent-driven usage, add the Higgsfield MCP server to your agent's MCP config:

{
  "mcpServers": {
    "higgsfield": {
      "command": "npx",
      "args": ["-y", "@higgsfield/mcp"]
    }
  }
}

The MCP server exposes generate_video, list_presets, get_render_status, and download_render. It also provides the higgsfield://characters MCP resource for consistency when managing character references.

How to write prompts Higgsfield actually understands

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

1. Subject — what's in frame. Keep it concrete.
2. Motion preset — pick from the presets, don't invent one.
3. Style modifier — e.g. "shot on 35mm", "neon-lit", "moody cinematic".

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? Don't burn a render trying to guess.

Motion preset reference

Always call list_presets first if you're unsure. Common ones:

• push-in / pull-out — distance change, no rotation
• orbit — rotates around the subject
• parallax — sideways camera move with depth separation
• dolly-zoom — vertigo effect (zoom in, dolly out)
• whip-pan — fast horizontal sweep, usually for transitions
• static — no camera motion, use when motion comes from the subject

The preset is the most important parameter. The same prompt with orbit vs push-in looks like two completely different videos.

Render times and polling

Higgsfield renders take 30–120 seconds typically. The MCP generate_video call returns a renderId. Poll get_render_status every 10 seconds — don't poll faster, you'll get rate-limited. Show the user progress, then call download_render once status is complete. (This same async polling pattern applies if you are using the REST API at https://cloud.higgsfield.ai/api/v1).

// Typical agent flow
const { renderId } = await mcp.call("higgsfield", "generate_video", {
  prompt: "...",
  preset: "push-in",
  duration: 5,
});

let status = "queued";
while (status !== "complete" && status !== "failed") {
  await sleep(10000);
  status = (await mcp.call("higgsfield", "get_render_status", { renderId })).status;
}

if (status === "complete") {
  const { url } = await mcp.call("higgsfield", "download_render", { renderId });
  // Pass `url` to the user.
}

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

• Default duration is 5 seconds — change it explicitly only when needed
• Higher resolution costs more credits per second; check Scopeful's Higgsfield page for the current credit math
• Failed renders still consume credits in some plans — verify the prompt + preset before kicking off batches
• The CLI's --retry flag does NOT refund the first render — it's a new render

When the user asks "how much will this cost?" point them at scopeful.org/tools/higgsfield for the live USD-per-second math.

What to do when a render fails

1. Read the failure reason from get_render_status — Higgsfield returns specific codes (NSFW filter, invalid preset, source image too small, etc.)
2. If it's a content filter, ask the user to rephrase rather than retrying the same prompt
3. If it's a source-image issue, upscale or re-crop before retrying
4. Don't auto-retry more than once — failed renders cost the user, even when they fail

Useful follow-ups after a successful render

• Offer to chain a second Higgsfield clip with a different preset for a multi-shot sequence
• Suggest pairing with ElevenLabs for VO or Suno for music if the user is building an ad
• Save the final URL — Higgsfield render URLs expire after 7 days, so download or rehost