---
name: higgsfield-mcp
description: >-
  Creates and retrieves AI video and image assets via the Higgsfield MCP server (Seedance 2.0, Veo 3.1 / Veo 3.1 Lite, Kling 3.0, Kling 2.6, Grok Imagine, Minimax Hailuo, Wan 2.6 / 2.7, Cinema Studio Video, Marketing Studio, Nano Banana 2 / Pro, GPT Image 2, Seedream 4.5 / 5 lite, Higgsfield Soul 2 / Soul Cinema, Flux 2.0, b-roll, scene, character / Soul / reference-element flows). Loads prompts from the bundled prompting guide and model library, talks to Higgsfield via the connected MCP tools (no API keys in .env), preflights credit cost via get_cost before generating, and uses media_upload / media_confirm for reference inputs. Use when the user mentions Higgsfield, higgsfield.ai, Seedance, Veo, Kling, Grok Video, Nano Banana, Soul characters, reference elements, Marketing Studio, b-roll, UGC scripts, or generating marketing creative through Higgsfield.
---

# Higgsfield MCP

## Configuration

- **Transport:** Higgsfield is reached through its connected **MCP server**. There is no `.env` API key; auth is configured at the MCP-client level (Claude Code or Cursor MCP settings).
- **Health check:** `balance` returns current credits and plan. This is the canonical "is the connection working" probe. Run `./scripts/check-higgsfield-mcp.sh` if you want a CLI version that opens an MCP-enabled session and prints the result.
- **Workspace:** If the user belongs to multiple workspaces (private + team), call `list_workspaces` first and `select_workspace` to lock the right one. The selection persists across sessions.
- **Never** paste an MCP API key (if Higgsfield ever issues one) into chat, commit `.env`, or write keys into `MASTER_CONTEXT.md`.

### If the MCP server is not reachable

1. Verify the Higgsfield MCP is connected at the **client** level (Claude Code: `claude mcp list`; Cursor: MCP settings panel).
2. If it is not listed, ask the user to install / reconnect the Higgsfield MCP. Do not ask them to paste credentials in chat.
3. Once connected, re-run `balance` to confirm.

## Read order

1. Repo root **`MASTER_CONTEXT.md`** when present (brand voice, decisions, quirks).
2. This skill's **[reference.md](reference.md)** for MCP tools, parameters, media-upload flow, model catalog.
3. **[prompting/guide.md](prompting/guide.md)** then the right **`prompting/prompt-library/`** file for the model (see table below).

## Decision tree: which flow?

Every video generation goes through one MCP tool: **`generate_video`**, with the right `model` value and the right `medias` roles. Image generation goes through **`generate_image`**. See [reference.md](reference.md) for the full parameter list per model (durations, aspect ratios, allowed roles).

| User goal | MCP tool | `model` | Prompt library |
|-----------|----------|---------|----------------|
| **Seedance 2.0 UGC video** (selfie-style product review / testimonial) | `generate_video` | `seedance_2_0` | [seedance-2.md](prompting/prompt-library/seedance-2.md) (platform guide) + [seedance-2-ugc.md](prompting/prompt-library/seedance-2-ugc.md) (9-layer UGC formula) |
| **Seedance 2.0 premium product reveal** (dark void, no person, text narrative) | `generate_video` | `seedance_2_0` | [seedance-2.md](prompting/prompt-library/seedance-2.md) + [seedance-2-premium-reveal.md](prompting/prompt-library/seedance-2-premium-reveal.md) |
| **Seedance 2.0 product hero** (elemental effects, splash/mist, no person) | `generate_video` | `seedance_2_0` | [seedance-2.md](prompting/prompt-library/seedance-2.md) + [seedance-2-product-hero.md](prompting/prompt-library/seedance-2-product-hero.md) |
| **Seedance 2.0 studio lookbook** (polished, voiceover, multi-look) | `generate_video` | `seedance_2_0` | [seedance-2.md](prompting/prompt-library/seedance-2.md) + [seedance-2-studio-lookbook.md](prompting/prompt-library/seedance-2-studio-lookbook.md) |
| **Seedance 2.0 feature walkthrough** (fast-paced feature demo) | `generate_video` | `seedance_2_0` | [seedance-2.md](prompting/prompt-library/seedance-2.md) + [seedance-2-feature-walkthrough.md](prompting/prompt-library/seedance-2-feature-walkthrough.md) |
| **Reverse-engineer a video style** into a reusable Seedance 2.0 template | Follow the analyze-video skill | | [prompting/analyze-video/SKILL.md](prompting/analyze-video/SKILL.md) |
| **Clone/replicate an existing video ad** for a different product | Follow the clone-ad skill | | [prompting/clone-ad/SKILL.md](prompting/clone-ad/SKILL.md) |
| **Veo 3.1** ultra-realistic video (start-frame supported) | `generate_video` | `veo3_1` | [prompt-library/veo-3-1.md](prompting/prompt-library/veo-3-1.md) |
| **Veo 3.1 Lite** (fast / budget batch video) | `generate_video` | `veo3_1_lite` | [prompt-library/veo-3-1.md](prompting/prompt-library/veo-3-1.md) |
| **Kling 3.0** video (multi-shot, motion transfer, audio sync) | `generate_video` | `kling3_0` | [kling-3.md](prompting/prompt-library/kling-3.md) |
| **Kling 2.6** (cinematic physics-aware video) | `generate_video` | `kling2_6` | [kling-3.md](prompting/prompt-library/kling-3.md) |
| **Grok Imagine** video (text or image to video, supports audio) | `generate_video` | `grok_video` | See [reference.md](reference.md) for fields |
| **Minimax Hailuo** (natural physics, facial emotion) | `generate_video` | `minimax_hailuo` | See [reference.md](reference.md) |
| **Wan 2.7** (synchronized audio, character consistency) | `generate_video` | `wan2_7` | See [reference.md](reference.md) |
| **Cinema Studio Video** (Higgsfield cinematic) | `generate_video` | `cinematic_studio_video_v2` or `cinematic_studio_3_0` | See [reference.md](reference.md) |
| **Marketing Studio video** (one-click product ads, TikTok/Reels-ready, brand-kit aware) | `generate_video` | `marketing_studio_video` | See [reference.md](reference.md) Marketing Studio section |
| **Higgsfield preset** image-to-video (curated viral templates) | `generate_video` | `higgsfield_preset` + `preset_id` from `presets_show` | |
| **Nano Banana 2 still image** (default) | `generate_image` | `nano_banana_2` | [nano-banana.md](prompting/prompt-library/nano-banana.md) |
| **Nano Banana Pro still image** (top quality, 4K, text/diagrams) | `generate_image` | `nano_banana_pro` | [nano-banana.md](prompting/prompt-library/nano-banana.md) |
| **GPT Image 2** still image (best text rendering, typography) | `generate_image` | `gpt_image_2` | [nano-banana.md](prompting/prompt-library/nano-banana.md) |
| **Higgsfield Soul 2.0 still** (realistic UGC / fashion editorial / character) | `generate_image` | `soul_2` | [prompt-library/character-sheet.md](prompting/prompt-library/character-sheet.md) |
| **Soul Cinema still** (cinema-grade stills, concept art) | `generate_image` | `soul_cinematic` | [prompt-library/character-sheet.md](prompting/prompt-library/character-sheet.md) |
| **Marketing Studio image** (one-click product image ad) | `generate_image` | `marketing_studio_image` | [prompt-library/product-showcase.md](prompting/prompt-library/product-showcase.md) |
| **DTC Ads (`ms_image`)** (brand-kit-aware ad images with avatars + ad formats) | `generate_image` | `ms_image` | See [reference.md](reference.md) Marketing Studio section |
| **Recreate an influencer** from a reference photo | **Two-step:** (1) `generate_image` (`nano_banana_2` or `soul_2`) with `medias: [{value: <uploaded image>, role: "image"}]` to generate a still, get user approval; (2) feed the approved still as `start_image` into `generate_video` (`veo3_1`, `kling3_0`, `seedance_2_0`). **Never skip the approval step.** | [prompt-library/influencer-recreation.md](prompting/prompt-library/influencer-recreation.md) |
| **Product showcase** (AI person holds/uses a product and talks about it) | **Two-step:** (1) `generate_image` with product image as reference; (2) user approves still; (3) `generate_video` with that still as `start_image`. | [prompt-library/product-showcase.md](prompting/prompt-library/product-showcase.md) |
| **UGC / selfie-style video** (cross-model) | `generate_video` on any video model | varies | [prompt-library/ugc-selfie-style.md](prompting/prompt-library/ugc-selfie-style.md). For Seedance 2.0, use [seedance-2-ugc.md](prompting/prompt-library/seedance-2-ugc.md). |
| **Create a new AI influencer** (reusable trained identity) | **`show_characters` action=train** with 5–20 reference images. Returns a `soul_id` after ~10 min; then `generate_image` with `model: soul_2` + `soul_id`. | [prompt-library/character-sheet.md](prompting/prompt-library/character-sheet.md) |
| **Create a new AI influencer** (one-off, no training) | **Two-pass:** (1) hero still via `generate_image` (`soul_2` or `nano_banana_pro`), get approval; (2) call again with the approved hero in `medias` to generate angle stills. Save to `references/influencers/`. | [prompt-library/character-sheet.md](prompting/prompt-library/character-sheet.md) |
| **UGC product selfie** (AI influencer holding a product) | Combine character hero + product photo + style references via `medias` and a multi-reference model (`nano_banana_pro`, `seedream_v4_5`, `gpt_image_2`). | [prompt-library/ugc-product-selfie.md](prompting/prompt-library/ugc-product-selfie.md) |
| **Reusable multi-subject reference** (two people in one shot, prop, environment) | **`show_reference_elements` action=create** returns an `element_id`. Embed `<<<element_id>>>` in the `prompt` for `generate_image` / `generate_video`. Works with Nano Banana, Seedream, GPT Image 2, Kling, Seedance 2.0, Cinema Studio. **Not** Soul V2 / Cinema (those need `soul_id`). | |
| **Pixar-style 3D animated ad** (anthropomorphized cartoon mascot beats) | **Multi-step:** (1) Lock cast sheet; (2) Storyboard stills via `generate_image` (`gpt_image_2`, max 5 ref images per call); (3) Animate each beat via `generate_video` (`seedance_2_0` with the storyboard still as `start_image`); (4) ffmpeg-stitch + burn captions. | [../../shared/skills/pixar-style-ad/prompting/guide.md](../../shared/skills/pixar-style-ad/prompting/guide.md) |
| **Claymation / Aardman-style ad** (sculpted plasticine, 8-beat story arc, 60–115s) | **Multi-step:** (1) Cast sheet (protagonist + supporting + narrator); (2) `generate_image` storyboard stills (`gpt_image_2`, fallback `nano_banana_pro`); (3) `generate_video` per beat (`seedance_2_0`); (4) ffmpeg-stitch (optional `fps=12,fps=24` for stop-motion judder) + burn captions. | [../../shared/skills/claymation-ad/prompting/guide.md](../../shared/skills/claymation-ad/prompting/guide.md) |
| **Add captions to a finished video** (burn timed narrator/dialogue captions onto an existing MP4) | **Out of band** (no MCP call). Use the captioning sub-skill (Whisper transcribe + Remotion render + ffmpeg chroma-key overlay). | [../../shared/skills/caption-video/prompting/guide.md](../../shared/skills/caption-video/prompting/guide.md) |

### Sora 2 is not available

Higgsfield's MCP does not expose Sora 2. If the user asks for Sora 2:

- For **text-to-video with speech**: route to **Seedance 2.0** (`seedance_2_0`, supports up to 15s, audio enabled via the `audio`-role media, embed dialogue in the prompt).
- For **ultra-realistic cinematic**: route to **Veo 3.1** (`veo3_1`).
- For **longer-form**: Seedance 2.0 caps at 15s; for longer outputs, split the script into multiple beats and stitch with ffmpeg (see "Splitting long scripts" below).

Mention the substitution and offer to proceed.

Prefer the **shortest** path: if the user only needs a single model, do not build multi-step character flows unless they ask.

## Creative layer

- **MANDATORY:** Before composing any prompt, **read the relevant `prompting/prompt-library/*.md` file** for the chosen model/workflow.
- Build **one** clear prompt paragraph; avoid keyword soup.
- For Seedance 2.0 / Veo 3.1 / Kling / Grok / Nano Banana, align with the **official vendor guides** linked in each `prompting/prompt-library/*.md` file (do not paste full vendor docs into chat; summarize checks).
- Merge slot values from the user and from **`MASTER_CONTEXT.md`** when it conflicts with defaults.

## Session setup: pick the right workspace

At the **start of each session** that will generate assets:

1. Call `list_workspaces`. If the user has one workspace, continue. If multiple, check `MASTER_CONTEXT.md` for a saved default. If absent, ask the user once and save the choice with `select_workspace` + write the workspace ID back to `MASTER_CONTEXT.md`.
2. Call `balance` to confirm credits available and surface the plan.

Higgsfield's MCP does not have an Arcads-style "product / folder / project" hierarchy. To keep generations organized, the user can browse history via `show_generations` and individual jobs via `job_display`. For DTC ad workflows specifically, use the `show_marketing_studio` widget (products, web-products, avatars, brand kits, ad references).

## Credit cost estimation (MANDATORY, show before generating)

Before firing **any** generation call, calculate and present the total credit cost to the user, and **wait for confirmation**.

### Higgsfield gives you live cost data, use it

`generate_image` and `generate_video` both accept `params.get_cost: true`. With this flag, the call **returns the cost in credits without submitting a job**. This is the best source of truth.

**Workflow:**

1. Compose the same payload you intend to submit (model, prompt, medias, duration, resolution, aspect_ratio, etc.).
2. Call the tool with `get_cost: true`. The response includes `cost`.
3. Multiply by `count` (number of variations) and sum across models if the workflow uses several.
4. Compare against the user's `balance` and warn if it would exceed.
5. Present the breakdown and ask for confirmation. **Do not submit the real job until the user confirms.**

### Cost data sources (in priority order)

1. **`get_cost: true` preflight** (most accurate, live from Higgsfield).
2. **`logs/higgsfield-mcp.jsonl`** (historical record of actual `cost` values for prior calls). Grep for entries with the same model and similar config when preflight is unavailable.
3. **`MASTER_CONTEXT.md` Credit costs** (user-provided pricing rules). Fallback only.
4. **Ask the user** (last resort; write the answer back to `MASTER_CONTEXT.md`).

`get_cost: true` is **not supported on Marketing Studio models** (`marketing_studio_image`, `marketing_studio_video`, `ms_image`). For those, fall back to logs or `MASTER_CONTEXT.md`.

### Example output to user

```
Estimated credit cost (live preflight via get_cost):
  Seedance 2.0 (8s i2v, 720p) x 1 = 96 credits
  Veo 3.1 (basic, 8s)         x 2 = 30 credits
  ----------------------------------------
  Total: 126 credits  (balance: 4,800)

Proceed? (yes/no)
```

Always wait for confirmation before firing the real (non-preflight) call.

**Exception, QA-fix retries (still images only):** After the user has confirmed the initial batch, **automatic regeneration to fix visible defects** (see [Generated image QA](#generated-image-qa-mandatory) below) does **not** require asking again for credit confirmation. Each retry is still billed. Note the extra `cost` when summarizing the session.

## Generation count: multiple variations per prompt

Higgsfield's `generate_image` / `generate_video` tools support `params.count` (1–4) for batching variations in a single call. **Prefer `count: N` over firing N separate calls.** It is the documented batch parameter and lighter on the MCP transport.

If the user wants more than 4 variations, fire multiple calls in parallel.

Present results as a numbered list so the user can compare and pick favorites.

## Nano Banana: model choice (`nano_banana_2` vs `nano_banana_pro`)

For `generate_image`:

- **Default:** `nano_banana_2` (Nano Banana 2, fast, high quality).
- **Optional:** `nano_banana_pro` when the user asks for **Nano Banana Pro** (ultimate quality, text rendering, diagrams, 4K).
- **Legacy:** `nano_banana` (budget-friendly, realistic). Use only when the user explicitly wants the older model.

**Naming gotcha:** Higgsfield exposes three distinct Nano Banana IDs. **`nano_banana_pro` is its own ID.** Do not collapse it to `nano_banana`.

Before the first Nano Banana image call in a workflow, ask: *"Use default Nano Banana 2, or Nano Banana Pro?"* If they have no preference, use `nano_banana_2`. Include the chosen `model` in the credit estimate.

## Script and dialogue

For any video that features a person speaking, **ask the user for the script** (the exact words the AI person should say). This is separate from the visual prompt.

### MANDATORY: dialogue confirmation gate

Before generating **any** video that contains spoken dialogue, the agent MUST:

1. **Extract the dialogue lines from the full prompt** and show them to the user in a dedicated block, separate from the visual/cinematography description.
2. **Present them as a clean, numbered list** with beat labels (hook / show / demo / verdict, or similar) and any silent beats clearly marked as `(silent beat, no dialogue)`.
3. **Time the dialogue against the target duration** at a natural pace (~2.5 words/sec) and flag the total spoken word count plus whether it comfortably fits.
4. **Explicitly ask for dialogue approval** before moving on (e.g. "Approve this dialogue? (yes / edit / rewrite)"). **Never assume approval from earlier confirmations.** Dialogue approval is its own gate.
5. Only after the user types `yes` (or equivalent) may you proceed to the credit cost confirmation and then generation.

**Presentation format (use this exact structure):**

```
Dialogue script (please confirm before I generate)

  1. [HOOK]    "Bro. BRO. Look what just showed up."
  2. [SHOW]    "The PAID SOCIAL stripe? Insane. Like, who greenlit this?"
  3. [DEMO]    (silent beat, thumb brushing the suede, small nod)
  4. [VERDICT] "I'm literally wearing these to the gym tomorrow."

Total spoken words: ~28  |  Target duration: 15s  |  Fits at natural pace: yes

Approve this dialogue? (yes / edit / rewrite)
```

This gate applies to **Seedance 2.0**, **Veo 3.1 / 3.1 Lite**, **Kling 3.0**, **Wan 2.7**, **Cinema Studio Video**, and **Marketing Studio video**. Any flow where the model can speak. Skip for silent flows (Grok-only modes, Nano Banana images, B-roll, pure product-hero with no voiceover).

### Model-specific notes

- **Seedance 2.0, Veo 3.1, Kling 3.0, Wan 2.7, Marketing Studio video, Cinema Studio Video:** embed dialogue in the `prompt` field using a `Dialogue: "..."` or `She speaks: "..."` pattern.
- **Seedance 2.0** specifically: audio output is enabled by attaching an audio reference via `medias` with `role: "audio"`. There is no separate `audioEnabled` flag (confirmed via model metadata). Ask the user whether they want to supply a reference voice clip / music; if yes, upload via `media_upload` and pass it as an audio-role media.
- **Veo 3.1 Lite:** pass `generate_audio: true` as a top-level param to enable audio output.
- **Grok Video / Kling 2.6 / Wan 2.6:** silent by model. If the user wants speech, redirect to Seedance 2.0 / Veo 3.1 / Kling 3.0 / Wan 2.7.
- **Nano Banana / Soul / GPT Image 2 images:** no speech (these are stills). Speech belongs in the downstream video.

## Script length to video duration (auto-select)

Use the script word count to auto-pick `duration`. Speaking pace: **~2.5 words/sec** (~150 WPM). Round **up** to the next allowed value.

### Seedance 2.0, duration range: **4–15s continuous**

| Script length | Duration |
|---------------|----------|
| 1–8 words | 4–5s |
| 9–15 words | 6–8s |
| 16–25 words | 9–12s |
| 26–35 words | 13–15s |
| **36+ words** | **Too long, offer to split** |

For no-dialogue styles (product hero, premium reveal), default to **15s**.

**Resolution:** `720p` default. `480p` for cheap test gens, `1080p` for hero deliverables.
**Aspect ratio:** `9:16` (vertical UGC/social) or `16:9` (landscape). Seedance 2.0 also supports `auto`, `21:9`, `4:3`, `1:1`, `3:4`.

### Veo 3.1, durations: **4, 6, 8s** (enum)

| Script length | Duration |
|---------------|----------|
| 1–10 words | 4s |
| 11–20 words | 6s |
| 21–28 words | 8s |
| **29+ words** | **Too long, split or switch to Seedance 2.0** |

**Aspect ratios:** `16:9`, `9:16`. **`quality` tiers:** `basic` (default), `high`, `ultra`.

### Veo 3.1 Lite, durations: **4, 6, 8s** (enum)

Same script-length table as Veo 3.1. Cheaper, faster, good for batch exploration. Supports `generate_audio: true`.

### Kling 3.0, duration range: **3–15s continuous**

| Script length | Duration |
|---------------|----------|
| 1–8 words | 4–5s |
| 9–15 words | 6–8s |
| 16–25 words | 9–12s |
| 26–35 words | 13–15s |
| **36+ words** | **Too long, split** |

**Mode:** `std` (default), `pro`, `4k`. **Sound:** `on` (default), `off`. **Aspect:** `16:9`, `9:16`, `1:1`.

### Kling 2.6, durations: **5, 10s** (enum)

| Script length | Duration |
|---------------|----------|
| 1–12 words | 5s |
| 13–24 words | 10s |
| **25+ words** | **Too long, switch to Kling 3.0 or Seedance** |

### Grok Video, duration range: **1–15s continuous**, silent

Use for fast text-to-video B-roll. Cheapest tested model in the Higgsfield catalog.

### Minimax Hailuo, durations: **6, 10s** (enum)

`minimax-2.3` variant is start-only (no end_image). `resolution: 512` blocks `end_image`. See [reference.md](reference.md).

### Wan 2.6 / Wan 2.7, duration ranges

- Wan 2.6: `[5, 10, 15]` (enum).
- Wan 2.7: 2–15s continuous, supports `audio` role media for sync.

### Cinema Studio Video / 3.0, duration ranges: **3–12s / 4–15s**

### Marketing Studio video, duration range: **4–15s continuous**

## Splitting long scripts into multiple videos

If the script exceeds the maximum duration for the chosen model:

1. **Tell the user** the script is too long and show the word/duration math.
2. **Offer two options:**
   - **Split into segments** at natural sentence boundaries into chunks that each fit. Each chunk becomes a separate generation call.
   - **Switch models.** If on Kling 2.6 (10s max), suggest Kling 3.0 or Seedance 2.0 (15s).
3. If splitting, generate each segment as a separate video (respecting the variation count).
4. **Offer to stitch** with `ffmpeg`:
   - Download segment videos locally (the `generate_video` result includes a downloadable URL).
   - `ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4` (re-encode if codecs differ).
   - Present the stitched file alongside individual segments.

## Reference images: `start_image` vs `image` role

Higgsfield models accept reference media via the `medias` array, each entry tagged with a `role`. The role name varies by model. Inspect the model's `medias[].roles` field with `models_explore` action=`get` before guessing.

Common roles:

| Role | Meaning |
|------|---------|
| `image` | Generic reference image (for image models). Drives style or identity. |
| `start_image` | First frame of the generated video. Animates from this exact image. |
| `end_image` | Final frame. Used for frame-to-frame morphing on models that support it. |
| `video` | Reference video clip (Seedance 2.0 only). Drives motion/style. |
| `audio` | Reference audio (Seedance 2.0, Wan 2.7). Voice clip or music. |

**Default rule:** When the user provides a single reference photo of a person and wants video, use `start_image`. The video animates from that exact image. **Do not** use it as a generic `image` style reference. That drops identity.

**Veo 3.1, Kling 3.0, Seedance 2.0, Wan 2.7 all support `start_image`.** Marketing Studio video and Cinema Studio Video also accept `start_image`.

## Uploading reference media

Higgsfield's MCP uses a three-step upload flow:

1. **`media_upload`** with `filename` and `content_type` (or `files[]` for batch). Returns a presigned `upload_url` and the `media_id` UUID.
2. **PUT the bytes** to the `upload_url` (run the curl command the tool emits, or do it programmatically).
3. **`media_confirm`** with `media_id` and `type` (`image` / `video` / `audio`). The media is now usable.
4. Pass `{ value: <media_id>, role: <role> }` inside `medias` on `generate_image` / `generate_video`.

You can also pass:
- A completed `job_id` from a prior generation (chains output to next input).
- An `https://` URL (must be Higgsfield CloudFront: `cdn.higgsfield.ai` or `d20rwh69pn04qo.cloudfront.net`). External URLs are rejected for some flows.

### Image preprocessing, auto-upscale small inputs

Before sending any reference image:

1. **Check dimensions.** If the longest side is below **1024 px**, upscale to **1080 px** with Lanczos resampling (preserve aspect ratio).
2. **Convert to RGB JPEG** (quality 90–95) to strip alpha channels.
3. Upload the resized file via `media_upload`.

Tiny images can cause subtle quality regressions. Auto-upscale so the user never hits the failure mode.

## Soul Characters vs Reference Elements (when to use which)

Higgsfield exposes two reusable-reference systems. Pick based on the use case:

| Need | Use | Why |
|------|-----|-----|
| **Reusable trained identity** of ONE person across many generations, identity-faithful, willing to wait ~10 min for training | `show_characters` action=train (Soul). Then `generate_image` model=`soul_2` + `soul_id`. | Highest identity fidelity. Trained on 5–20 reference images. Soul 2 and Soul Cinema only. |
| **Reusable reference** that works instantly, including multi-subject scenes, props, environments | `show_reference_elements` action=create (Element). Then embed `<<<element_id>>>` in the prompt. | Single image, multiple subjects allowed. Works with Nano Banana, Seedream, GPT Image 2, Cinema Studio, Seedance 2.0, Kling 3.0. Not Soul V2 / Cinema. |
| **One-off** AI character (no future reuse needed) | Just call `generate_image` with the reference photo in `medias` | No training, no element creation. Fastest path. |

If the user ambiguously asks "make me an AI version of me / my avatar" with no chosen path, **ask** before silently picking:

> "Two options:
>  1. Train a Soul Character (reusable, identity-faithful, needs 5–20 photos, ~10 min). Best if you'll use this person across many future generations.
>  2. Create a Reference Element (instant, single image, works with most models). Best if you want to start generating now.
>
>  Which?"

Skip the question and use **Elements** when: >1 character in one shot, non-person subject, single image, the user mentions Nano Banana / Seedream / Kling / Cinema Studio, instant result wanted.
Skip the question and use **Soul** when: words like "train," "digital twin," "identity," or 5+ photos of one person are supplied.

## Generated image QA (mandatory)

Applies to **still images** from `generate_image` (Nano Banana, Soul, Seedream, GPT Image 2, etc.). After each image returns, **visually inspect the output** (download or open the URL, or use the agent's image-reading capability).

**Look for:** extra or missing hands/fingers, wrong limb count, distorted/duplicated/merged facial features, melted or fused objects, impossible anatomy, stray limbs, obvious texture or boundary artifacts, unreadable or garbled text if text was requested.

**If something looks wrong:** Do **not** hand off the bad frame as the final deliverable without trying again. **Regenerate** with a **revised prompt** that explicitly corrects the issue (e.g. "exactly two hands, five fingers each, anatomically correct arms," "single face, no duplicate features"). Do **not** resend the identical payload and expect a different outcome.

**Retry cap:** Up to **2 regeneration attempts per originally requested image** (3 attempts total including the first). If defects remain, stop auto-retries, tell the user what still looks wrong, show the best attempt or URLs for all attempts, and ask how they want to proceed.

**Credits:** Each attempt is a separate generation and is billed. Summarize total `cost` used for that image after the QA loop ends.

**Video (optional quick check):** Before spending heavily on downstream video, you may spot-check the first frame for the same defects. Lighter scope than hero stills.

Details: [prompting/prompt-library/nano-banana.md](prompting/prompt-library/nano-banana.md).

## Execution checklist (agent)

1. **Workspace:** Ensure the right workspace is active. Default from `MASTER_CONTEXT.md` if set, else `list_workspaces` and confirm with the user.
2. **Balance:** Quick `balance` call so we can surface "running low" warnings up front.
3. **Ask for script/dialogue:** If the output is a video with a person speaking, ask for the exact words. Count words to auto-select duration. If too long, offer to split.
   - **MANDATORY dialogue confirmation gate** (before credit cost, before generation): extract dialogue from the drafted prompt, present as numbered block, wait for explicit `yes`. Skip for silent flows.
4. **Image model choice:** For `generate_image`, confirm Nano Banana 2 (default), Nano Banana Pro, GPT Image 2, Soul 2, etc. per the section above.
5. **Generation count:** Ask how many variations. Default 1. Use `count: N` (max 4) inside one call; for >4, fire parallel calls.
6. **Check `references/` folder:** Before composing the prompt, check the repo-root `references/` folder for relevant images. `references/influencers/` for person recreation, `references/products/` for product showcase, `references/aesthetics/` for style/mood. Offer to use them. Auto-upscale if needed.
7. **Upload media:** For any reference not already a Higgsfield CDN URL or job ID, call `media_upload` then PUT then `media_confirm`. Decide role per model (see "Reference images" section).
8. **Cost preflight:** Call `generate_image` / `generate_video` with `get_cost: true` and the full payload. Multiply by `count`. Present breakdown to user. **Wait for confirmation.** Skip preflight on Marketing Studio models (not supported); use logs or `MASTER_CONTEXT.md` instead.
9. **Submit the real call** with the confirmed payload (drop `get_cost`).
   - **Immediately after the call returns, append a log entry to `logs/higgsfield-mcp.jsonl`** with the config (model, duration, resolution, aspect_ratio, mediaCounts, promptWordCount, jobId, cost). Do NOT log full prompt text or any API secrets.
10. **Display results:** The MCP tool returns the job's `id`, `result_url`, `cost`. Use `job_display` to re-show a single result, or `show_generations` to browse history.
11. **Generated image QA:** For each still image, follow the QA loop. Regenerate with refined prompt up to 2 retries; bill each.
12. **Present results:** Return watch URLs, image URLs, or download URLs. If multiple variations, present as a numbered list. For stills used as starting frames, show the image and **wait for user approval** before video generation.
    - **ALWAYS open the output folder** on the user's machine after saving generated files: `open "<output_directory>"` (macOS). Save downloads to `outputs/` with a descriptive subfolder (e.g. `outputs/seedance-tests/`).
13. **Stitch if split:** If the script was split into segments, offer to stitch the final videos with `ffmpeg` and provide both the stitched file and individual segments.

## Errors (user-facing)

- **MCP not connected:** ask the user to check `claude mcp list` (Claude Code) or the Cursor MCP settings panel.
- **`structuredContent.recovery_tool='show_plans_and_credits'`:** Higgsfield is telling you the user is out of credits. The tool result includes `structuredContent.recovery_tool_args`; call `show_plans_and_credits` with those args immediately. Do not explain - hand the user the upgrade widget.
- **Adjustments returned:** `generate_image` / `generate_video` may return `adjustments` describing fallbacks (e.g. duration clamped to the nearest allowed value). Mention the adjustment to the user when summarizing results.
- **Declared-param errors:** when an invalid value is passed for a model-declared parameter, the tool returns a structured error. Read it, correct, retry.

## Supporting files

- [reference.md](reference.md) - MCP tools, parameters, model catalog, media-upload flow.
- [prompting/guide.md](prompting/guide.md) - marketing brief to MCP call.
- **Seedance 2.0:**
  - [prompting/prompt-library/seedance-2.md](prompting/prompt-library/seedance-2.md) - main Seedance 2.0 platform guide.
  - [prompting/prompt-library/seedance-2-ugc.md](prompting/prompt-library/seedance-2-ugc.md) - 9-layer UGC selfie-style formula.
  - [prompting/prompt-library/seedance-2-premium-reveal.md](prompting/prompt-library/seedance-2-premium-reveal.md) - dark-void product reveal.
  - [prompting/prompt-library/seedance-2-product-hero.md](prompting/prompt-library/seedance-2-product-hero.md) - elemental product hero.
  - [prompting/prompt-library/seedance-2-studio-lookbook.md](prompting/prompt-library/seedance-2-studio-lookbook.md) - studio lookbook with voiceover.
  - [prompting/prompt-library/seedance-2-feature-walkthrough.md](prompting/prompt-library/seedance-2-feature-walkthrough.md) - feature walkthrough demo.
  - [prompting/analyze-video/SKILL.md](prompting/analyze-video/SKILL.md) - reverse-engineer a reference video.
  - [prompting/clone-ad/SKILL.md](prompting/clone-ad/SKILL.md) - clone a reference video ad for a different product.
- **Other models:**
  - [prompting/prompt-library/influencer-recreation.md](prompting/prompt-library/influencer-recreation.md) - recreate an influencer from a reference photo.
  - [prompting/prompt-library/ugc-selfie-style.md](prompting/prompt-library/ugc-selfie-style.md) - cross-model UGC guide.
  - [prompting/prompt-library/product-showcase.md](prompting/prompt-library/product-showcase.md) - product-in-hand workflow.
  - [prompting/prompt-library/nano-banana.md](prompting/prompt-library/nano-banana.md) - Nano Banana image prompting.
  - [prompting/prompt-library/character-sheet.md](prompting/prompt-library/character-sheet.md) - 10-image character sheet from a text description (and Soul training intro).
  - [prompting/prompt-library/ugc-product-selfie.md](prompting/prompt-library/ugc-product-selfie.md) - UGC selfie-style still: character + product + style.
  - [prompting/prompt-library/veo-3-1.md](prompting/prompt-library/veo-3-1.md) - Veo 3.1 prompting.
  - [prompting/prompt-library/kling-3.md](prompting/prompt-library/kling-3.md) - Kling prompting.
- [prompting/brand-voice-starter.md](prompting/brand-voice-starter.md) - template to copy into `MASTER_CONTEXT.md`.