AutoGineer
Generated banner for Higgsfield Soul Id
Generated logo for Higgsfield Soul Id

Higgsfield Soul Id

Higgsfield AIOfficialPublished by Higgsfield AI

  • Skill
  • Workflow
  • Data and AI
  • MIT
  • Medium risk
Download ZIP

From the author

Train a Soul Character — a personalized model on a person's face that Higgsfield uses for identity-faithful image and video generation. Use when: "create my Soul", "train my face", "make my digital twin", "build me an avatar", "learn my appearance", "create a character of me", "set up identity for video", "I want my face in generated images". Chain: train Soul (one-time, returns reference_id) → use in higgsfield-generate via `--soul-id <id>` with models like `text2image_soul_v2` or `soul_cinematic`. NOT for: one-shot face swaps (use higgsfield-generate with --image), named-character / non-photo avatars (use higgsfield-generate with prompt).
— the description by Higgsfield AI

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The higgsfield-soul-id skill provides a structured workflow to train a custom identity model, known as a Soul, based on a set of provided face photos. This trained model acts as a persistent reference that can be utilized across various Higgsfield generation tasks to maintain facial identity in resulting images and videos. The process involves uploading a set of images, initiating the training, and managing the resulting reference ID for future use.

What it does

  • Trains a personalized identity model from 5 to 20 face photos.
  • Supports different model variants for static image or cinematic video generation.
  • Provides a reference ID for use in subsequent generation commands.
  • Includes tools to list and retrieve existing trained identity models.
  • Handles the upload and processing of local image files for training.

When to use it

  • When you need to generate images or videos featuring a specific person consistently.
  • When you want to create a digital twin or avatar based on your own appearance.
  • When you have a collection of varied face photos ready for model training.
  • When you need to set up a reusable identity reference for multiple generation tasks.

Advantages

  • Enables identity-faithful generation across different prompts and styles.
  • Provides a reusable reference ID for streamlined generation workflows.
  • Offers specific model variants optimized for either image or cinematic output.
  • Supports a range of input photos to improve identity capture.

Usage examples

“Train a new Soul named John using these photos.”
The agent initiates the training process using the provided images and returns a reference ID once the Soul is ready for use.
“Use my John Soul to generate a cinematic video of him walking in the rain.”
The agent uses the previously trained reference ID with the soul_cinematic model to generate the requested video.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/higgsfield-ai/higgsfield-soul-id/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip higgsfield-soul-id.zip -d .agents/skills

Documentation by Higgsfield AI

Higgsfield Soul Character

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

Step 0 — Bootstrap

Before any other command:

  1. If higgsfield is not on $PATH, install it:

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

  2. If higgsfield account status fails with Session expired / Not authenticated, ask the user to run higgsfield auth login (interactive) and wait for confirmation.

  3. Soul training requires a paid plan (Basic+). If higgsfield account status shows free plan, tell the user before submitting.

UX Rules

  1. Be concise. No raw IDs in chat. Just say "Soul ready" with a name reference.

  2. Detect language and respond in it. CLI flags stay English.

  3. Ask for the smallest set of inputs: name + photos. Pick a sensible model variant.

  4. Polling is silent — training takes minutes. Don't repeat status updates.

Workflow

  1. Get name. One word, used for later reference. Ask if missing.

  2. Get photos. 5–20 face photos, varied angles and lighting. Local paths or already-uploaded IDs both work — --image accepts either.

  3. 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.

  4. 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.

  5. Wait. higgsfield soul-id wait <id>. Silent. Default timeout 30m.

  6. 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

--soul-id is sent as the model's custom_reference_id. For a curated Soul style, list styles with higgsfield preset list soul-v2 and pass the chosen id as --style_id on text2image_soul_v2. --style_id cannot be combined with --image.

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

Files

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Claude Code frontmatter, Needs network access

Security

What our scanner noticed· Medium risk

  • Instructions that use the network
  • Downloads piped into a shell

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Higgsfield AI
Publisher
Higgsfield AI (Official)
Source
higgsfield-ai/skills · higgsfield-soul-id · commit 2700040
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Higgsfield AI or Higgsfield AI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download higgsfield-soul-id.zip