higgsfield

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: higgsfield
description: 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.
---

# 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