higgsfield-soul-id

Teaches the system one person's face from a handful of photographs, once, so that the same recognisable person can then appear in every picture and video you make afterwards.

WHEN TO USE

SCOPE

USE FOR

Train a reusable identity model from 5 to 20 photos of one person's face.
Build a digital-twin avatar you can reuse across future generations.
Set up a consistent character identity before generating Soul-powered video.

NOT FOR

A one-off face swap that doesn't need a trained, reusable identity.
A named or non-photo character avatar that isn't based on a real face.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (8)

Higgsfield Soul Character

Train a face-faithful identity model. Reusable across all Soul-powered generations.

Step 0 — Bootstrap

Before any other command:

If higgsfield is not on $PATH, install it:

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

If higgsfield account status fails with Session expired / Not authenticated, ask the user to run higgsfield auth login (interactive) and wait for confirmation.
Soul training requires a paid plan (Basic+). If higgsfield account status shows free plan, tell the user before submitting.

UX Rules

Be concise. No raw IDs in chat. Just say "Soul ready" with a name reference.
Detect language and respond in it. CLI flags stay English.
Ask for the smallest set of inputs: name + photos. Pick a sensible model variant.
Polling is silent — training takes minutes. Don't repeat status updates.

Workflow

Get name. One word, used for later reference. Ask if missing.
Get photos. 5–20 face photos, varied angles and lighting. Local paths or already-uploaded IDs both work — --image accepts either.
Pick variant.
- --soul-2 — for image generation (default)
- --soul-cinematic — for cinematic / video work Choose based on user's stated downstream use. Default to --soul-2.

Submit.

higgsfield soul-id create --name "<name>" --soul-2 --image ./photo1.png --image ./photo2.png ...
higgsfield soul-id create --name "<name>" --soul-2 --image <upload_id> --image <upload_id> ...

CLI auto-uploads paths. Captures returned reference id.

Wait. higgsfield soul-id wait <id>. Silent. Default timeout 30m.
Deliver. "Soul <name> ready. Use in generate with --soul-id <id>."

Use the Soul

Once trained, pass to higgsfield-generate:

higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <ref_id> --quality 2k --wait
higgsfield generate create soul_cinematic --prompt "..." --soul-id <ref_id> --quality 2k --wait

Listing existing Souls

higgsfield soul-id list                   # all references
higgsfield soul-id get <id>               # one by id

Errors

Minimum Basic plan required — user is on free plan; tell them.
Training failed — check photos quality (5+ unique faces, well-lit).
Session expired → higgsfield auth login.

Reference docs

references/photo-guide.md — what photos work best
references/troubleshooting.md — common training failures

Account or credentials required

2 FOR YOU · 1 FOR THE AGENT

All items below are required.

01
Install the Higgsfield CLI
Install the higgsfield CLI if it isn't on $PATH: curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh.
02
Sign in with Higgsfield auth login
Run higgsfield auth login interactively if higgsfield account status reports a session expired or not authenticated.
```
higgsfield auth login
```
03
Have a Basic plan or higher
Soul training requires a paid Higgsfield plan (Basic or above); accounts on the free plan cannot submit a training job.

Listed as free: Connected services may require an account or charge fees.

This skill ships inside the Higgsfield AI Skills plugin.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add higgsfield-ai/skills --skill "higgsfield-soul-id" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Higgsfield AI Skills plugin package selected for your AI tool.

PLUGIN MARKETPLACE

Add the marketplace, then install the plugin

Typed inside the agent's own prompt, not in a terminal. The marketplace is called higgsfield, which is the part after the @.

/plugin marketplace add higgsfield-ai/skills

02
```
/plugin install higgsfield@higgsfield
```

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

Same repository

higgsfield-brandkit
Create and extend complete visual brand systems through the Higgsfield CLI and bundled deterministic local tooling: palettes, SVG logo marks, typography, mockups, social graphics, packaging, signage, merchandise, posters, presentation decks, and editable PPTX/PDF brandbooks. Preserves official supplied assets, persists approvals locally, and regenerates only dependent outputs. Use when: "create a brand kit", "make a visual identity", "design a logo and brandbook", "apply this logo to branded assets", "make packaging or signage", or "extend our existing branding". Chain with higgsfield-generate for general image production and Marketing Studio brand-kits when importing website metadata for ads. NOT for unbranded image generation (use higgsfield-generate), product catalog photography (use higgsfield-product-photoshoot), website implementation (use higgsfield-websites), or native Figma/Canva/PSD/AI delivery.Read full description
higgsfield-generate
Generate images/videos/3D assets/audio via Higgsfield AI. Defaults: GPT Image 2.5 for image/design/text, Seedance 2.5 for video, Nano Banana 2/Lite/Pro for character/reference images, Marketing Studio for ads, Seed Audio 1.0 for audio. Use when: "generate an image", "make a video", "animate this photo", "image-to-video", "edit/stylize/remix this image", "reframe this video", "edit this video from a sketch", "create a 3D model/GLB", "create a sound effect", "make music", "text-to-audio", "create an ad", "make a UGC video", "unboxing", "presenter video", "import product from URL", or "analyze video virality". Supports generic generation, workflows, Marketing Studio, and Virality Predictor. Chain with higgsfield-soul-id for face/identity consistency. NOT for: Soul training, brand systems/brandbooks (use higgsfield-brandkit), photoshoots, cards, YouTube thumbnails (use higgsfield-youtube-thumbnail), explainers (use higgsfield-video-explainer), playable games/assets (use higgsfield-game-generation), or TTS.Read full description
higgsfield-marketplace-cards
Generate marketplace product image cards through Higgsfield: compliant main image, secondary product images, and A+ style content modules. Use when the user asks for marketplace listing images, product detail cards, secondary product images, product infographics, lifestyle listing shots, A+ style content, marketplace image sets, or sales-ready product visuals. Backend owns marketplace compliance references and prompt templates; this skill only routes user intent to the CLI. NOT for generic brand product photography without marketplace/listing context (use higgsfield-product-photoshoot), video generation or UGC ads (use higgsfield-generate), or Soul Character training (use higgsfield-soul-id).Read full description
higgsfield-product-photoshoot
Generate brand-quality product images through Higgsfield product-photoshoot prompt enhancement on GPT Image 2 / gpt_image_2. Entry point for professional brand/product visuals. Use when: "product photo", "studio shot", "lifestyle image", "Pinterest pin", "hero/banner", "carousel", "ad creative", "Meta ads", "virtual try-on", "model wearing", "person holding product", "closeup with hands", "levitating/floating/splash product", "CGI/surreal product", "restyle", "seasonal/aesthetic variation", or any product, brand, or paid-social creative. Modes: product_shot, lifestyle_scene, closeup_product_with_person, moodboard_pin, hero_banner, social_carousel, ad_creative_pack, virtual_model_tryout, conceptual_product, restyle. Backend assembles the final prompt; never freehand it. NOT for: no-product text-to-image (use higgsfield-generate), branded avatar video (use higgsfield-generate Marketing Studio), marketplace listing cards (use higgsfield-marketplace-cards), Soul Character training (use higgsfield-soul-id).Read full description
higgsfield-video-explainer
Build a complete non-photoreal narrated explainer or story video from ordered 10-second blocks: one narrator, one universal style key, one Seed Audio take and one Gemini Omni clip per block, then server-side assembly with explainer_video. Use when: "make an explainer video", "explain this in a video", "turn this topic or document into a narrated video", "tell this story as an animated video", "make a faceless narrated video", or "show me explainer styles". Supports live CMS presets, custom style references, mascot/faceless modes, two aspects, and optional burned subtitles. NOT for: photoreal films, ads/UGC, talking heads, podcasts, motion typography reels, one-off clips without narration, or editing a finished video.Read full description
higgsfield-websites
Build, edit, and deploy full-stack websites, apps and games via the Higgsfield CLI (higgsfield website …). Each is a React 19 + TanStack Start SSR app in one Cloudflare Worker (D1/R2/KV/DO/Containers). THREE product types, picked via --type on create: website (standalone, no Higgsfield integration — references/website-flow.md), app (Sign in with Higgsfield + fnf SDK, Quanta — references/app-flow.md), game (realtime multiplayer rooms — references/game-flow.md). Routes to the right flow; each carries its own rules and deploy/publish gates. Use when: "build me a website", "make a landing page", "create a web app", "build a SaaS dashboard / portfolio", "make me a game", "deploy this site", "publish". Also owns GAME ART: "make a spritesheet", "tileable texture", "animate a 3D character", game music/SFX — see the game-* references. NOT for: single image/video/audio generation (higgsfield-generate), product photos (higgsfield-product-photoshoot), marketplace cards (higgsfield-marketplace-cards).Read full description

Higgsfield Soul Character

Step 0 — Bootstrap

UX Rules

Workflow

Use the Soul

Listing existing Souls

Errors

Reference docs

Account or credentials required

Install just this skill

Install the whole plugin

Add the marketplace, then install the plugin

What's inside

More skills

higgsfield-brandkit

higgsfield-generate

higgsfield-marketplace-cards

higgsfield-product-photoshoot

higgsfield-video-explainer

higgsfield-websites