> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modellix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Modellix for ComfyUI

> Install Modellix custom nodes for ComfyUI, configure an API key, and build image, video, and audio workflows with live model schemas and recoverable tasks.

[modellix-comfyui](https://github.com/Modellix/modellix-comfyui) connects ComfyUI to Modellix media models. Choose a model in one **Modellix Generate** node, edit its schema-driven fields, and connect native image, video, or audio inputs. Results return as native ComfyUI media for preview, saving, or another generation step.

The package calls the [Media REST API](https://docs.modellix.ai/ways-to-use/api.md) directly. You do not need local model weights, a Modellix Client node, the CLI, or a separate Node.js server.

## Requirements

* ComfyUI **0.40.0 or later**, with its native VIDEO and V3 node APIs. The initial compatibility baseline is 0.40.0 with frontend 1.55.17.
* Python **3.10 or later**, using the interpreter that runs ComfyUI.
* A funded Modellix API key from the [Console](https://www.modellix.ai/console/api-key).
* Internet access to `api.modellix.ai`, `www.modellix.ai`, and the public HTTPS hosts used for media resources.
* ComfyUI Desktop or a single-user ComfyUI instance on your device, such as `http://localhost:8188/`. Use your configured port.

The package checks the reported ComfyUI version at startup before loading its nodes or registering routes. A version below 0.40.0, including a pre-release of 0.40.0, is rejected with a clear compatibility message. Missing or invalid version metadata also blocks registration. Update or repair ComfyUI and restart; an incompatible host does not receive partially enabled Modellix nodes.

## Install

### Registry and Manager

In ComfyUI-Manager, search for **Modellix**, confirm publisher `modellix` on [Comfy Registry](https://registry.comfy.org/publishers/modellix/nodes/modellix-comfyui), select an active version, and restart ComfyUI. Use version **0.1.1** or later for API key setup at the default Desktop address and for the node layout fix.

Versions undergoing Registry security review may be absent from Manager's active version list. Refresh the Manager catalog after Registry activates the version.

Once version 0.1.1 is active, you can install it with Comfy CLI:

```bash theme={null}
comfy node install modellix-comfyui@0.1.1
```

### Git Installation

You can also install from the GitHub repository:

**1. Clone the Node Package**

From your ComfyUI directory:

```bash theme={null}
git clone https://github.com/Modellix/modellix-comfyui.git custom_nodes/modellix-comfyui
```

**2. Install Python Dependencies**

Use the same Python interpreter as ComfyUI:

```bash theme={null}
python -m pip install -r custom_nodes/modellix-comfyui/requirements.txt
```

For the Windows portable distribution, run its bundled interpreter from the portable directory:

```powershell theme={null}
.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\modellix-comfyui\requirements.txt
```

**3. Restart ComfyUI**

Restart the existing ComfyUI process. Search for **Modellix Generate** in the node menu under **Modellix / Media**.

For Registry installations, select the published version you want in Manager and restart. For Git installations, pull the package repository, install its requirements with the host interpreter, and restart. Registry versions are immutable: a GitHub main update reaches Registry users only after a new package version is published.

## Configure Your API Key

From ComfyUI Desktop or your local browser, open **Settings → Modellix → API Key**. The password field offers:

* **Session Only**: use the key until the ComfyUI process ends.
* **Secure Save**: store the key in Windows Credential Manager, macOS Keychain, or a supported Linux system keyring. Saving requires an available, unlocked secure backend.
* **Clear**: remove the session key and saved key. The result reports any secure-storage failure. Environment fallback stays disabled in the current process until you explicitly choose it.
* **Use Environment**: enable `MODELLIX_API_KEY` fallback. A saved secure key has priority over the environment; a session key has highest priority.

Changes apply without restarting ComfyUI. Status shows only whether a key is configured and its source. The package never returns your key or saves it in ordinary ComfyUI settings, node inputs, workflow JSON, history, or PNG metadata.

Changing or clearing credentials removes the previous account's visible catalog, pricing, and schema fields. Late responses from that account cannot repopulate the form. Configure a key before loading models again.

For a headless queue, set the environment variable before starting ComfyUI:

```bash theme={null}
export MODELLIX_API_KEY="<your-api-key>"
python main.py --listen localhost
```

If secure storage is unavailable, select Session Only or use the environment variable. The package does not fall back to a plaintext credential file. Credential configuration routes accept local, same-origin requests; this setup is for local single-user ComfyUI.

If you see **Local same-origin request required**, open ComfyUI on the device running it, reload the page, and try again.

![ComfyUI Modellix API Key settings with session, secure-save, clear, and environment controls](https://mintcdn.com/modellix/1VUPPas7kfo2wZQe/images/comfyui/api-key-settings.webp?fit=max\&auto=format\&n=1VUPPas7kfo2wZQe\&q=85\&s=7d235f1600487ce13d47aeae70818aaf)

The local password field stays empty after applying a key; status shows only its source.

## Generate Your First Image

1. Add **Modellix Generate**.
2. Choose the text-to-image category and search by model name, provider, or exact slug, such as `google/nano-banana-2-lite`.
3. Enter the required prompt and review the model's defaults, limits, and pricing information when available.
4. Keep **Wait** mode and connect `images` to **Preview Image** or **Save Image**.
5. Queue the workflow. The node reports submission, task status, and downloading. Its `task_id` output identifies the remote task.

The model list comes from your authenticated live catalog. The form loads the selected model's public schema. A missing schema produces an error instead of an invented parameter form. Text-output models such as speech-to-text are outside this package's IMAGE/VIDEO/AUDIO outputs.

![Modellix Generate showing a sailboat prompt and its connected Preview Image result](https://mintcdn.com/modellix/1VUPPas7kfo2wZQe/images/comfyui/image-workflow.webp?fit=max\&auto=format\&n=1VUPPas7kfo2wZQe\&q=85\&s=ed3382ed97ec28937fae52e3e5aad53c)

A real text-to-image workflow returns the generated sailboat as a native IMAGE. Task identifiers are concealed in these screenshots.

## Work with Model Fields

Drag the lower-right corner of **Modellix Generate** to resize its status and model panels. The panels follow the node width with the Properties panel open.

Required fields appear before optional and advanced fields. The form preserves typed enum values, numeric bounds, defaults, nested objects, and arrays. When a schema has alternative branches, select the intended branch before connecting references. Arrays retain their order.

For a media field, choose a URL or a native connection. For example, an image-edit model may use an `image` array, while an image-to-video model uses separate `first_frame_image` and `last_frame_image` fields. Connect **Load Image** to the relevant IMAGE socket; Generate encodes and uploads the image automatically.

> [!NOTE]
>
> Use one source per field. Remove an entered URL before binding a native input. A scalar image field rejects an image batch with more than one image; an array field accepts the batch in its original order. Connected primitive values and URL lists are also checked against the selected field's type and limits.

Changing models preserves compatible values and bindings. Review any removed fields. The advanced JSON editor is available for complex objects and headless workflows. A changed live schema must be reviewed before the package submits a paid request.

When a saved schema changes, the form identifies affected fields and bindings and removes incompatible draft values. Queue stays blocked until you review the updated form and click **Accept Reviewed Schema**. Refresh Online, credential refresh, reopening the workflow, and New Attempt do not accept the change. Acceptance saves the reviewed schema hash without queueing work or changing the attempt nonce.

Wait until the selected model's form finishes loading before Queue. Loading or failed model changes cannot submit the previous model. Refreshing credentials fetches current data without silently approving a changed saved schema.

## Nodes and Outputs

| Node | Purpose | Outputs |
| - | - | - |
| Modellix Generate | Upload connected inputs and submit a model request once; wait or return immediately | `images`, `video`, `audio`, `task_id` |
| Modellix Get Task | Read or wait for an existing task, without creating another generation | The same outputs, followed by `status` |
| Modellix Upload Media | Upload native IMAGE, VIDEO, and AUDIO inputs independently | `urls`, `url_list`, `file_ids`, `media_types` |
| Modellix URL List | Build and merge an ordered reference list | `url_list` |

Generate, Get Task, and Upload Media are output nodes: they can run without a Preview or Save connection. Mute an unused output node or use ComfyUI's partial execution controls to exclude it from a queue.

Images, videos, and audio use separate, fixed sockets. A model's applicable media outputs are lists of native resources, preserving different dimensions, lengths, and sample rates. Unavailable media sockets block their downstream branches. The package does not emit placeholder images or empty media.

## Image, Video, and Audio Workflows

Download importable workflows, their API prompt equivalents, and input preparation instructions from [Examples](https://github.com/Modellix/modellix-comfyui/tree/main/examples). The same workflows appear in ComfyUI's Template Browser under the package's examples.

| Workflow | Connections |
| - | - |
| Text-to-image | Generate → Preview Image / Save Image |
| Image edit and multiple references | Load Image or an image batch → the edit model's image field → Preview Image |
| Text-to-video | Generate → native Save Video |
| Image-to-video | Text-to-image Generate `images` → image-to-video Generate's first-frame socket → Save Video |
| First and last frames | Two separate IMAGE connections → `first_frame_image` and `last_frame_image` |
| Reference-to-video | Ordered image references → the model's reference branch, with optional audio references when supported |
| Video transformation | Load Video → the selected V2V model's VIDEO field → Save Video |
| Speech generation | A text-to-speech model → Preview Audio / Save Audio |
| Speech transformation | Native reference AUDIO → the selected speech-to-speech field → Preview Audio |

Use references that satisfy each model's duration, size, content, and consent requirements. Modellix models have different field names and constraints; the selected model's schema and description remain authoritative. Video input and output use ComfyUI's native VIDEO objects and do not require third-party video nodes.

![A sailboat image connected to independent first and last frame inputs with a native video result](https://mintcdn.com/modellix/1VUPPas7kfo2wZQe/images/comfyui/reference-video.webp?fit=max\&auto=format\&n=1VUPPas7kfo2wZQe\&q=85\&s=ec5ffeea69695e4e6853e61d7d41bf38)

The first and last frames have separate typed connections. The completed video uses native Save Video.

![A Modellix speech model with text and voice fields connected to ComfyUI Preview Audio](https://mintcdn.com/modellix/1VUPPas7kfo2wZQe/images/comfyui/audio-workflow.webp?fit=max\&auto=format\&n=1VUPPas7kfo2wZQe\&q=85\&s=e6141bbf2a3d6833bcfb2fc0d5a06ccf)

Speech generation returns native AUDIO with its actual sample rate and a playable result.

## Submit Now and Retrieve Later

**Wait** is the default. It submits one generation request, waits within the configured local deadline, downloads results, and returns native media.

Choose **Submit only** to return the confirmed task ID immediately. This mode performs no task polling or result downloads. Its media outputs block downstream branches.

Connect `task_id` to **Modellix Get Task**:

* **Wait** continues reading the existing task until completion or the local deadline.
* **Snapshot** performs one logical task read and returns its current status. Pending or processing tasks have blocked media outputs. Queue again to refresh; this node actively queries on each queue.

Get Task and Generate's advanced `resume_task_id` input do not upload inputs or create another generation request. Use the same API key context that owns the task.

![Modellix Generate in Submit only mode connected to Get Task and an image preview, with task identifiers concealed](https://mintcdn.com/modellix/1VUPPas7kfo2wZQe/images/comfyui/task-recovery.webp?fit=max\&auto=format\&n=1VUPPas7kfo2wZQe\&q=85\&s=dcf8395781e59daf3fbed51755f6ddda)

Submit only hands the confirmed task to Get Task. Reading the result does not submit another generation.

## Upload and Combine Reference URLs

Generate uploads connected native media internally. Use **Modellix Upload Media** when you want to reuse upload URLs across nodes or combine them with existing references.

Connect one or more native media inputs and choose the upload group order. The `urls`, `file_ids`, and `media_types` output lists have matching indexes. Use `url_list` for array-valued model fields.

**Modellix URL List** accepts one HTTPS URL per line, plus optional existing and additional lists. Choose Append or Prepend for the entered lines. Blank lines are removed; duplicates, commas inside a URL, and reference order are preserved. Connect its custom `MODELLIX_URL_LIST` output to a compatible array field. Scalar fields reject this list connection.

REST uploads default to a **200 MiB per-file** limit. Team file quotas and model-specific restrictions also apply. Uploads are serial and successful content uploads can be reused while valid. Quota errors do not trigger automatic remote file deletion; see [Upload Media Files](https://docs.modellix.ai/ways-to-use/api.md#upload-media-files).

## Cancel, Resume, and Start a New Attempt

ComfyUI Cancel stops local polling, uploads, submission waits, and downloads. It does not promise to cancel remote generation or refund a charge. An in-flight submission can have an unknown outcome; check your [Console history](https://www.modellix.ai/console/logs) before starting another attempt.

Normal queues retain the node's saved attempt nonce. Repeating a queue, changing Wait to Submit only, clearing media cache, or restarting the host reuses the existing task rather than silently submitting it again. If the original response was lost and no task ID is known, the attempt remains protected against automatic replay.

Use **New Attempt** only when you intend another paid request. This changes the saved nonce; the next queue submits once. Headless clients express the same intent by explicitly changing `run_nonce`. Duplicating a node gives the copy its own instance ID.

New Attempt also clears an entered recovery ID and the previous task display. Reviewing an updated model schema alone retains the existing paid attempt and cannot replay an unknown submission. The configured local timeout includes model discovery, schema loading, and waiting for shared local work.

Task records persist separately from media cache. A missing or expired local result is downloaded again from the original task when available. An expired remote result requires your explicit choice of a new attempt. Active result files remain protected while the host may still reference them.

If a downloaded result cannot be decoded, resume the same task to fetch a fresh copy. Damaged protection records remain blocked instead of being treated as a new, unsubmitted request.

## Errors and Troubleshooting

| Message | Action |
| - | - |
| `Modellix requires ComfyUI >= 0.40.0; detected ...` | Upgrade ComfyUI to 0.40.0 or later and restart. No Modellix nodes or routes were registered. |
| `Cannot determine the ComfyUI version` | Update or repair the host so its version metadata is readable, then restart. |
| 400 / schema validation | Use the cleaned upstream field details to check required fields, branch selection, types, and model descriptions |
| 401 | Apply the correct key in Settings |
| 402 | Check balance and [billing](https://www.modellix.ai/console/billing) |
| 404 / schema unavailable | Check the requested task ID or model slug shown in the error; refresh the catalog or choose an available model |
| 413 | Reduce the input below the REST and model limits |
| 429 | Check request or file quota; do not blindly queue a new paid attempt |
| Failed or canceled remote task | Inspect the task error and ID before choosing a new attempt |
| Local timeout or download failure | Resume with Get Task or `resume_task_id` |
| Submission outcome unknown | Inspect Console history; the package will not replay the request |
| Secure storage unavailable | Use Session Only or `MODELLIX_API_KEY` |
| Schema changed | Review the affected fields and connections, then click Accept Reviewed Schema before Queue |
| Disk/cache limit | Free unused local results or adjust the documented cache limits; active files stay pinned |

Generation and upload POST requests are never automatically retried. Safe queries and downloads use bounded retries under one local deadline. Keep the task ID when reporting an issue, and never include your API key.

Get Task errors and deadlines retain the current request's task ID in the status display and its copy/recovery actions. Parameter error details omit credentials, signed URLs, and echoed request values.

See the package [README](https://github.com/Modellix/modellix-comfyui#readme) for cache locations, advanced configuration, headless prompt format, current test coverage, and [support matrix](https://github.com/Modellix/modellix-comfyui/blob/main/examples/support-matrix.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.