higgsfield

Higgsfield MCP

One connector, 30+ models. Subscription-billed in credits — no per-provider API keys.

When to use this skill

Only use this skill if the user already pays for a Higgsfield subscription. The whole value is access to 30+ models behind one auth, billed against credits they're already paying for. Don't push a non-subscriber to subscribe for one project.

Three spokes

The skill does three things — keep it scoped to these:

1. Explore models — what's available, what role each model accepts
2. Generate image — single or batched
3. Generate video — including image→video chains

Install

Two ways to connect. Both end at the same place: an authenticated MCP your session can call.

Terminal (Claude Code):

claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp

Then run /mcp in your session and complete OAuth with the Higgsfield account that owns the subscription.

Claude Desktop app:

Settings → Connectors → Add custom connector → paste https://mcp.higgsfield.ai/mcp → sign in.

After auth — mandatory step:

select_workspace

Generation calls fail silently until a workspace is selected. Always run this once at the start of a session.

Heads-up: MCP tools may not appear in the running session after a fresh install — restart Claude Code / Desktop if /mcp shows higgsfield connected but no tools are visible.

No API keys to manage. No .env. The MCP handles auth.

ALWAYS quote credit cost before generating

Non-negotiable. Before any generate_image or generate_video call, quote:

• Model + settings
• Estimated credit cost (use the table below)
• Current balance
• Balance after the call

Wait for explicit "go" before firing. Credits ≠ free, and silent burn is the #1 way to ruin trust. Auto mode does not override this.

Cost table (measured, not from docs)

models_explore does NOT return credit costs — they're not in the API. Use this baked table:

Model	Settings	Credits
gpt_image_2	2K medium	~3
nano_banana_2	2K	~11
seedance_1_5	480p, 4s	~2.4
seedance_1_5	480p, 12s	~7.2
Video at higher tiers	—	TBD (measure first run)

Numbers will drift. Verify in the Higgsfield dashboard if a run feels off. Update this table when you measure new ones.

Plan-tier silently gates models

Higher-end models (e.g. seedance_2_0) are blocked on Starter and return a generic "Something went wrong" — no helpful error. If a model errors mysteriously, suspect plan gating before debugging the prompt. Suggest checking balance to infer the user's tier.

Workflow mechanics

Upload is 3 steps, not one. Wrap as a single helper if calling repeatedly:

1. media_upload → returns a presigned PUT URL + media_id
2. curl -X PUT the file bytes to that URL
3. media_confirm({ media_id }) → marks it ready

Generation is async:

1. Call generate_image or generate_video → returns job_id
2. Poll job_status({ job_id, sync: true }) — usually resolves in 1–2 polls (~10–20s for images, longer for video)

Result fields: always pull rawUrl (PNG / source). minUrl is just the webp preview.

One ref, many gens — an uploaded media_id survives the session. Reuse it across calls instead of re-uploading.

Parallel jobs work fine — fire multiple generate_image calls and poll independently.

Reference passing

Schema is medias: [{ value, role }] (not reference_images). value accepts three forms:

• media_id — from media_upload / media_confirm
• job_id — output of a prior generation, used as input to the next. Killer feature for image→video chains — generate a still, feed its job_id straight into generate_video without re-uploading.
• https:// URL — any public image URL

Role taxonomy varies per model

Always run models_explore action=get for a model before crafting the call. Roles are not consistent:

Model	Accepted roles
Seedance 1.5	start_image, end_image
Seedance 2.0	full set (image, start_image, end_image, video, audio)
Kling 3.0	start_image only
Nano Banana Pro / GPT Image 2	image

Pass the wrong role and the call rejects.

Seedance 1.5 duration trap

If you omit duration, Seedance 1.5 silently defaults to 12 seconds — 3× the cost of a 4s clip. Always pass duration explicitly.

Pricing footnotes

• Plus plan: $39/month, 1000 credits — sweet spot for ad workloads
• Top-up packs ($5 / 100 credits) expire in 90 days — don't stockpile
• Verify exact per-call credit cost in the Higgsfield dashboard before committing to a workflow swap

Failure rules

• Don't silently fall back from ref-to-video to text-to-video — losing the visual anchor defeats the workflow. Surface the failure.
• Don't retry the same input on the same model when a content-policy check trips — propose changing the input or model.
• If the MCP errors out, check /mcp to confirm the connection is still live. Subscription lapses break auth.

Models exposed

30+ behind one URL. Highlights:

Category	Models
Image	Nano Banana Pro, GPT Image 2, Flux, Seedream
Video	Seedance 2.0, Sora 2, Veo, Kling, Hailuo
Higgsfield exclusives	Soul (character consistency), Cinema Studio

Limits: images up to 4K, video up to 15 sec.