Higgsfield - Generate / Edit Image

There's no checkpoint to download here. GPT Image 2.5 Sunburst and Marketing Studio Image 2.0 Alpha are API products, so a node that calls the API is the only door in. HFImageGenerate is that door: your prompt goes to api.higgsfield.ai, the result is downloaded into your output folder, and the pixels come back as an ordinary IMAGE tensor. Downstream, your upscaler and your Save Image node have no idea the picture came off someone else's GPU.

The catch is the one the KB gives for every API node: a local generation is free after electricity, and this is metered on every call.

What it actually does

Your inputs become a JSON body, POSTed to the model's route and then polled on Higgsfield's status endpoint with backoff until the request reaches a terminal state. On success the returned media URL is downloaded to ComfyUI/output/higgsfield/<key-folder>/ and read back into a float IMAGE tensor (RGB, 0–1), previewed in the node. On failure or moderation you get an error instead - but the request is still recorded for later.

Two things to know up front: the waiting happens inside the node, so a busy queue is a stalled one (and a 429 is what you get for hammering it), and the image is downloaded before you see it, so a failed request costs you the generation and nothing else.

The inputs that matter

• model - the preset. GPT Image 2.5 Sunburst (Higgsfield) is the flexible one: adjustable quality, up to 16 reference images, the marketing-studio/image/sunburst route. Marketing Studio Image 2.0 Alpha is the plainer route and takes its quality from the API default.
• prompt - required; empty strings are rejected. For edits, describe the change, not the whole image.
• resolution - 1k, 2k, 4k, default 2k. Aspect ratio has an auto option plus the usual eight; auto lets the model pick, which is fine for generation and rarely what you want for a strict layout.
• quality - high (default), low, medium, xhigh, max. Only Sunburst does anything with it; Alpha raises an error on anything but high, which reads like a bug the first time and is actually a guardrail.
• generation_id - not a seed. The tooltip says it plainly: change it for a new paid generation, keep it to resume or reuse a result. Leave it at take-1, bump it to take-2 when you want another roll of the dice.
• references (optional) - takes an HF_REFERENCES chain built by Reference Images or Reference File. Editing is just generation with a reference attached.
• timeout_seconds - 30 to 7200, default 1800: the local patience budget, not an instruction to Higgsfield.

Out: images (an IMAGE list, so a downstream single-image node runs once per result), saved_paths (a JSON string of the on-disk files), and request_id. That last one is genuinely useful - paste it into Resume Request to re-download the same result later without paying again.

Install

Search Higgsfield in ComfyUI Manager, or:

cd ComfyUI/custom_nodes
git clone https://github.com/w0ver/Higgsfield-api-comfyui-nodes ComfyUI-Higgsfield

The folder name matters - __init__.py has to sit directly inside it. requirements.txt is one line (requests), so the README's pip step is a no-op in a normal ComfyUI environment; the real setup is credentials. On Windows, double-click Configure API.bat (or run python custom_nodes/ComfyUI-Higgsfield/configure_api.py) and paste your key ID and secret from open.higgsfield.ai. Everywhere else, export HF_API_KEY_ID and HF_API_KEY_SECRET in the environment that launches ComfyUI. A .env file in the folder is not auto-loaded - the number one reason people get a 401 on first run.

Where people get burned

• HTTP 401 - a credential value is missing, or you exported it in your shell rather than the ComfyUI backend's environment. On Windows the encrypted file is per-account: run setup and ComfyUI as the same user.
• HTTP 403 - key is fine, account isn't: no access to that model, or out of credits.
• HTTP 422 - the route refused your combination of resolution/aspect/quality/references. Sunburst's ceiling is 16 reference images.
• Queue stalls then the node errors with a timeout - the request is saved. Queue again with the same prompt, settings and generation_id and it resumes the existing job instead of buying a new one.
• A status of nsfw - moderation, and it's terminal. No node can talk a hosted filter out of a refusal, which is why the KB says to keep anything a filter would refuse on your own machine.
• Multi-user mode - not supported; the nodes refuse to run rather than share one credential across sessions.

One security note, because this category has already been weaponized once (ComfyUI_LLMVISION shipped credential-stealing malware): your credentials here live in the backend environment or an encrypted file, never in the workflow, and the code refuses to send them to any host the API response didn't point to.