# Higgsfield

> One MCP, 30+ image and video models. Use this skill when the user wants to generate images or videos via Higgsfield (Seedance 2.0, Sora 2, Veo, Kling, Nano Banana Pro, GPT Image 2, Flux, Hailuo, Soul, Cinema Studio, etc.) without juggling per-provider API keys. Triggers on "higgsfield", "higgsfield mcp", "use higgsfield", or any image/video generation request when the user already has a Higgsfield subscription.

- Skill: `robonuggets/higgsfield` (Agent Skill)
- Install (CLI): `npx skillmds@latest add robonuggets/higgsfield`
- Raw SKILL.md: https://api.skillmd.com/api/skills/robonuggets/higgsfield/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: robonuggets (https://skillmd.com/u/robonuggets)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/robonuggets/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.