Connect your own Higgsfield API account, choose a model, add a prompt and optional references, and queue your workflow. Generation runs on Higgsfield's servers, and results are downloaded to your local ComfyUI output folder.

Features

Image generation and editing with GPT Image 2.5 Sunburst and Marketing Studio Image 2.0 Alpha through Higgsfield.
Text-to-video with Seedance 2.5 and Seedance 2.0.
Image-to-video with Seedance 2.5, including an optional end frame.
Multiple image, MP4 video, and WAV audio references with Seedance 2.5 Reference to Video.
Native ComfyUI IMAGE and VIDEO outputs, previews, saved paths, and request IDs.
Saved-request recovery and protection against duplicate submissions when retrying the same generation.
Backend credentials with Windows-encrypted storage or environment variables.
Five example workflows and an advanced node for additional documented image/video endpoints.

Supported model presets

| Model / route | Use case | References | | --- | --- | --- | | GPT Image 2.5 Sunburst (Higgsfield) | Generate or edit images | Optional; up to 16 images | | Marketing Studio Image 2.0 Alpha | Generate or edit images | Optional images | | Seedance 2.5 — Text to Video | Create a video from a prompt | None | | Seedance 2.5 — Image to Video | Animate a starting image | Start image, optional end image | | Seedance 2.5 — Reference to Video | Create a video guided by references | Images, videos, and audio | | Seedance 2.0 — Text to Video | Create a video from a prompt | None |

The package includes six verified endpoint presets. It does not automatically list the entire Higgsfield catalog. Availability and access depend on your API account.

The GPT Image preset uses Higgsfield's marketing-studio/image/sunburst endpoint and requires a Higgsfield API credential.

Requirements

A recent ComfyUI version with native VIDEO support and the system-user directory API.
A Higgsfield API account with a key ID, key secret, and sufficient API credits.
An internet connection for generation, reference uploads, and downloads.
Dependencies installed in ComfyUI's Python environment.

Checked on Windows with ComfyUI Easy-Install and Python 3.12. The encrypted setup helper requires Windows. Other platforms use environment variables and have not been tested here.

Installation

1. Install the custom-node folder

Use Code → Download ZIP on this repository, extract it, and place the package in:

ComfyUI/
└── custom_nodes/
    └── ComfyUI-Higgsfield/
        ├── __init__.py
        ├── nodes.py
        ├── requirements.txt
        ├── hf/
        ├── web/
        └── example_workflows/

Ensure __init__.py is directly inside ComfyUI-Higgsfield, without an extra nested repository folder.

2. Install dependencies

Windows portable / Easy-Install: open PowerShell in the folder containing both python_embeded and ComfyUI:

.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-Higgsfield\requirements.txt

Other installations: activate ComfyUI's Python environment and run this from the ComfyUI folder:

python -m pip install -r custom_nodes/ComfyUI-Higgsfield/requirements.txt

3. Configure your API credentials

Create a credential in the Higgsfield API console. It contains:

API key ID: identifies your API credential.
API key secret: authorizes requests using that credential.

If the credential is provided as KEY_ID:KEY_SECRET, split it at the colon. These values are separate from your Higgsfield login password.

Windows setup helper

For portable / Easy-Install layouts, double-click Configure API.bat inside the installed node folder. Enter the key ID and secret when prompted; input is hidden.

For other Windows layouts, run the helper with ComfyUI's Python from the ComfyUI folder:

python custom_nodes/ComfyUI-Higgsfield/configure_api.py

The helper encrypts the credential for your Windows account and saves it at:

ComfyUI/user/__higgsfield/credentials.dpapi

Run setup and ComfyUI under the same Windows account. Setup does not make an API request or start a generation.

Environment variables

Alternatively, set these variables in the ComfyUI backend's environment before launching it:

HF_API_KEY_ID=your_key_id
HF_API_KEY_SECRET=your_key_secret

Environment variables override the encrypted file. .env.example documents the names; .env files are not automatically loaded.

For a custom --user-directory, use environment variables or put the encrypted credential file in that directory's __higgsfield subfolder. Keep credentials out of workflow inputs, screenshots, and repository commits.

4. Restart ComfyUI

Search for Higgsfield in the node menu, or drag an example workflow onto the canvas.

How to use

Generate an image from text

Add Higgsfield - Generate / Edit Image.
Select a model and enter your prompt.
Choose the resolution, aspect ratio, and quality.
Leave references disconnected and queue the workflow.

Sunburst supports adjustable quality. For Alpha, leave quality at high; this route uses its API default quality. Both presets use direct generation/editing without Marketing Studio preset enhancement.

Edit an image or use image references

Connect:

Load Image → Higgsfield - Reference Images → Higgsfield - Generate / Edit Image

Upload a reference through Load Image, choose Sunburst, and describe the result you want. Add more references by connecting a Reference Images node's references output to another one's previous input.

Reference Images accepts an IMAGE batch. Chaining separate nodes also supports differently sized reference images without resizing them into one batch.

Animate an image with Seedance 2.5

Connect:

Load Image → Higgsfield - Reference Images → Higgsfield - Generate Video

Choose Seedance 2.5 - Image to Video, optionally describe the motion, select duration and resolution, and queue the workflow.

The first reference is the start frame. Append a second image reference for an end frame. This route derives its aspect ratio from the image: leave the aspect-ratio control at its default 16:9; that value is not sent to the API.

Create a video from text

Add Higgsfield - Generate Video, choose a Text to Video route, enter your prompt, and leave references disconnected.

| Route | Duration | Resolutions | | --- | --- | --- | | Seedance 2.5 | 4–30 seconds | 480p, 720p | | Seedance 2.0 Text to Video | 4–15 seconds | 480p, 720p, 1080p, 4k |

Use image, video, and audio references

Select Seedance 2.5 - Reference to Video. Build a chain using:

Reference Images for IMAGE inputs from other ComfyUI nodes.
Reference File for a local PNG, JPEG, WebP, MP4, or WAV file path.

Connect each node's output to the next node's previous input, then connect the final output to Generate Video. Reference order follows the chain. Describe how the references should guide the result in your prompt.

Example workflows

Drag a workflow into ComfyUI and replace any placeholder images or file paths before queuing:

| Workflow | Use case | | --- | --- | | 01 — Text to video | Seedance 2.5 video from a prompt | | 02 — GPT Image with a reference | Image generation/editing with a reference | | 03 — Animate an image | Seedance 2.5 image-to-video | | 04 — Multiple references | Image and video reference chain | | 05 — GPT text-to-image | Image generation without references |

Outputs

Completed media previews in the node and is saved under:

ComfyUI/output/higgsfield/<account-folder>/

Image nodes return a list of IMAGE tensors for downstream processing. Video nodes return a native VIDEO object, retaining audio present in the downloaded video. Connect it to Save Video or Get Video Components as needed. Saved paths and request IDs are also available as outputs.

New generations and recovery

generation_id is a local take label, not a model seed.

| What you want | What to do | | --- | --- | | Another result with the same prompt/settings | Change generation_id, for example take-1 to take-2 | | Resume a timed-out or interrupted request | Keep the same inputs and generation_id, then queue again | | Reuse a completed result | Keep the same inputs and generation_id | | Retrieve a saved request by ID | Use Resume Request, then Result Images or Result Video |

Changing the prompt, settings, or reference contents also creates a new request. New submissions may use API credits.

Requests are recorded in ComfyUI/user/__higgsfield/requests.sqlite3 and associated with the configured API key ID. Keep this database: it enables recovery and helps prevent duplicate submissions.

Polling uses backoff and handles completion, failure, moderation rejection, and cancellation. ComfyUI's stop button stops local waiting; it does not cancel generation already running at Higgsfield.

After an ambiguous submission timeout, check the Higgsfield console before choosing a new generation ID. The node avoids automatically repeating a submission whose outcome is unknown. It also recovers requests saved by the original release before it rejected an unexpected status URL.

Other models: advanced usage

Use Higgsfield - Custom Model (Advanced) for other documented image/video routes that follow Higgsfield's shared request lifecycle:

Find the model in the Higgsfield catalog and open its API reference.
Copy its production model ID into model_id and its request body into parameters_json.
Connect local references and use $ref1, $ref2, etc. as full JSON string values in the documented URL fields.
Connect result to Result Images or Result Video.

For example, use marketing-studio/image/sunburst with two image references:

{
  "prompt": "Combine the subject from the first image with the setting of the second image.",
  "image_urls": ["$ref1", "$ref2"],
  "resolution": "2k",
  "aspect_ratio": "auto",
  "quality": "high",
  "enhance_prompt": false
}

Every connected reference must appear in the request body. Different models use different fields and limits. The advanced node does not automatically discover models or validate every model-specific schema locally.

Node reference

| Node | Purpose | | --- | --- | | Generate / Edit Image | Generate or edit images | | Generate Video | Run the included Seedance video routes | | Reference Images | Add IMAGE inputs to a reference chain | | Reference File | Add a local image, MP4 video, or WAV audio file | | Custom Model (Advanced) | Send an exact JSON body to another documented endpoint | | Resume Request | Retrieve a request recorded for your configured API key | | Result Images | Convert an advanced/recovered result into IMAGE outputs | | Result Video | Convert an advanced/recovered result into a VIDEO output |

Troubleshooting

| Issue | What to check | | --- | --- | | Nodes do not appear | Check folder nesting, install dependencies in ComfyUI's Python, and restart | | Missing credentials / HTTP 401 | Configure both credential values; check environment overrides | | HTTP 403 | Check API access and credit balance | | HTTP 404, 423, or 503 | Check model access and availability in your API account | | Invalid parameters / HTTP 422 | Check the route's resolution, duration, reference fields, and schema | | Concurrency or rate limit | Let existing requests finish before submitting more | | Polling timeout | Queue again with unchanged inputs and generation_id | | Unexpected status URL on an older release | Update, restart ComfyUI, and queue the same workflow with the same generation_id |

Scope and testing

Designed for personal, local ComfyUI; multi-user mode is not supported. The package uses backend REST requests and polling, so no public webhook receiver is required.

Image and video results are supported. Audio-only output, 3D artifacts, Marketing Studio preset browsing, and a complete automatic model catalog are outside the current scope. Local uploads and downloads have a 1 GiB-per-file limit; downloads also have a ten-minute limit. Provider-specific limits still apply.

Run the offline tests from the repository folder:

python -m unittest discover -s tests -v

At this README update, 36 tests passed, covering authentication isolation, polling, retries, recovery, ownership, reference payloads, downloads, and duplicate protection. The eight nodes and five workflows were also checked against the development ComfyUI installation. A completed Sunburst request was retrieved through the live API; not every route has been tested with a paid generation.

Documentation

Model presets were checked against the documentation on September 24, 2026. API availability and account access can change.

Creator

Sherif Oneway : https://www.youtube.com/sherifoneway

Visit the channel for more from Sherif Oneway.