PRYX ComfyUI Higgsfield SOUL ID

This node doesn't generate anything. It's the odd one out in the pack - everything else calls an image or video endpoint and hands you pixels, while SOUL ID trains a character on Higgsfield's servers and gives you back a UUID. That UUID is the character. Wire it into a SOUL generator and it turns up in every image, no reference photo attached.

You know the local version: train a LoRA from 15–25 images. Same idea here, except the weights live somewhere you can't reach and you rent them per image. Higgsfield announced SOUL ID in July 2025 as a LoRA fine-tuner for their SOUL model, which is the mechanism in one sentence.

SOUL itself is closed-weight, squarely in the "call it or don't have it" bucket. People argue about whether it's secretly a Flux finetune; nobody can prove it, and it hardly matters when you can't run it.

How it works

Three actions, and they're genuinely different code paths.

validate_only is the default and it's the honest one. It checks name length, the model_version value, and counts images - zero network calls. The pack's test suite asserts it never even constructs an API client. Run it before you spend anything.

train is where money happens. It PNG-encodes each connected image, uploads them through Higgsfield's presigned upload flow, then fires a single POST /v1/custom-references with input_images as a list of image_url. It returns immediately with the character ID and a queued status - no waiting for training. And it won't retry: if that POST times out ambiguously, the client flags it rather than resubmitting a paid training for you.

check does a plain GET on /v1/custom-references/{id} and hands you the JSON. reference_id must be a valid UUID, so junk gets rejected before any request goes out.

The caching is worth knowing. Asked "did you change?", the node deliberately ignores the image inputs for validate_only and train, so re-queuing a downstream generator can't silently retrain your character. Flip side: swap in a different image set without touching the name and ComfyUI can decide nothing changed and hand back the cached result instead of training. If you're retraining, change the name. check always re-runs, which is what you want from a poller.

The inputs that matter

action, as above. name, 1–100 characters. And model_version - v1, v2 or cinema - which isn't cosmetic: it has to match the SOUL family that will use the finished ID.

Then images, your training batch, and optionally references (a Reference Collector's output) for extra ordered images. Total is 1–100, batch first then references, and anything that isn't an image is rejected outright - the tooltip says so and the code enforces it. A connected IMAGE batch gets split frame by frame, so a Load Image batch of thirty photos is thirty training images.

reference_id is the field that trips people. You need it for check, and it must be cleared for train; the node raises "Clear reference_id to start a NEW training, or select check for the existing training" rather than guessing your intent.

Outputs are custom_reference_id (a STRING, empty for validate_only) and status (JSON diagnostics). Both feed the generator's custom_reference_id and, where supported, custom_reference_strength - on SOUL 2 that runs 0 to 1, defaulting to 1.0.

Caveat from bundled catalog revision 2026-10-21.2: SOUL 2 and SOUL Cinema expose custom_reference_id; SOUL Standard doesn't. If your SOUL Standard model-info panel has no such input, a v1 ID has nowhere to go yet. That's the API, not the node.

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/PRYX-STUDIO/pryx-comfyui-higgsfield.git
python -m pip install -r ./pryx-comfyui-higgsfield/requirements.txt

Windows portable users:

..\python_embeded\python.exe -m pip install -r .\pryx-comfyui-higgsfield\requirements.txt

Three dependencies - higgsfield-client, httpx, jsonschema. No model downloads, no torch roulette. Wants ComfyUI 0.35.0+ and a 1.53.6+ frontend. Paste your key into Settings → PRYX ComfyUI Higgsfield → Credentials as key-id:key-secret, or set HF_KEY (or HF_API_KEY plus HF_API_SECRET) on a headless box. Restart, hard-reload the browser.

Where people get burned

Training has no price guard. The estimate_only and max_usd net on every other node in this pack does not extend here - there's no estimate route for training, so train just submits. Validate, read the count, then commit.

Don't poll with train. Every run is a new paid submission. check exists so you don't, and because the node returns instantly you'll be tempted.

Restarting ComfyUI loses the ID. It survives in a saved workflow, but a fresh execution of the same train node trains another character. Copy the UUID out.

Don't expect local-grade results from eight selfies. One to 100 is the API's hard range, not a quality recommendation. The 15–25 varied-shot habit from local LoRA training is the better starting point.

An empty generator output isn't the ID's fault. A SOUL generator left in estimate_only returns empty images. That's the billing mode, not a broken reference.