Higgsfield Text-to-Image (Direct API)

Let's get the important part out of the way: Higgsfield Text-to-Image does not run on your machine. Type a prompt, pick a model, and the heavy lifting happens on Higgsfield's servers using your API key. Your GPU just sits there. That's either exactly what you wanted or a dealbreaker, so it's worth knowing up front.

Why would you want that? Because the models in the dropdown - Soul 2.0, Seedream 4 (ByteDance), Reve - are all closed, API-only products. You can't download Seedream 4 or Soul 2.0 weights and run them locally, no matter how big your card is. This node is the honest shortcut: the same flagship closed models everyone else gets through a website or an SDK, sitting inside a ComfyUI graph where you can chain them into your existing workflow and save straight to the output folder.

How it works

Mechanically it's a thin bridge. The node takes your prompt, aspect ratio and resolution, optionally uploads a reference image, then calls the higgsfield_client SDK's subscribe() with those arguments and waits for the job to finish on their side. When it does, it downloads the resulting image URL and converts it back into a ComfyUI IMAGE tensor. Nothing is generated locally, and there's no model file to download - the pack's requirements.txt is just higgsfield-client, httpx, and Pillow.

That's also where the cost lives: you pay per generation. Failed and NSFW requests aren't charged, but everything that succeeds is real money, so don't wire this into a big batch loop and walk away.

The inputs that matter

Of the required inputs, only two deserve your attention:

• prompt - multiline, and it's the whole game. These models follow instructions well; write like you're describing a photograph, not a checklist.
• model - the dropdown: higgsfield-ai/soul/standard (Soul 2.0, the photorealistic one and the default), reve/text-to-image, and bytedance/seedream/v4/text-to-image (Seedream 4). Start with Soul for people and realism, Seedream for more "generative" looks.

aspect_ratio gives you ten presets (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9) with 2:3 as the default, and resolution is 1K / 2K / 4K, defaulting to 2K. 4K costs more and isn't obviously better for most use cases - 2K is a sane default.

Two optional inputs earn their keep: reference_image takes an IMAGE and uploads it for style/character consistency (Higgsfield's "Soul ID" trick - the thing that makes their selfie app so good), and api_key lets you drop in key:secret right on the node if you don't want to bother with the file or env var.

Outputs

You get three: image (the IMAGE tensor - wire it into a preview or Save Image), cache_key (a deterministic fingerprint of your request, made for the ComfyUI-API-Optimizer "Hash Vault" so identical prompts can hit a cache instead of your wallet), and info (a status string with the model, resolution, timing, and the saved filename).

Install and the key

Easiest route is ComfyUI Manager - search "Higgsfield". Otherwise:

cd ComfyUI/custom_nodes
git clone https://github.com/jeremieLouvaert/ComfyUI-Higgsfield-Direct.git
pip install -r ComfyUI-Higgsfield-Direct/requirements.txt

Then get a key at cloud.higgsfield.ai and either create a higgsfield_api_key.txt in your ComfyUI root containing your_api_key:your_api_secret, set HF_KEY as an environment variable, or paste it into the node. Restart ComfyUI and you'll find everything under AKURATE/Higgsfield.

The classic failure mode is exactly this: running the node with no key anywhere. You get a clear error listing the four ways to provide one, so it's self-explanatory. The other trap is forgetting this is a paid hosted service with content moderation - it's the closed-API lane, not the uncensored local lane. If you want that, this isn't the node; if you want Seedream 4 quality without a monster rig, it absolutely is.