> ## 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) 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.
* A local, single-user ComfyUI instance, accessed at `http://localhost:8188/` or your configured localhost port.
## Install
Git clone is the available installation channel. Registry metadata is included in the package; Registry and Manager availability must be confirmed separately before using those channels.
From your ComfyUI directory:
```bash theme={null}
git clone https://github.com/Modellix/modellix-comfyui.git custom_nodes/modellix-comfyui
```
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
```
Restart the existing ComfyUI process. Search for **Modellix Generate** in the node menu under **Modellix / Media**.
To update, pull the package repository, install its requirements with the host interpreter, and restart ComfyUI.
## Configure Your API Key
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.
For a headless queue, set the environment variable before starting ComfyUI:
```bash theme={null}
export MODELLIX_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.
## 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.
## Work with Model Fields
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.
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.
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.
## 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.
## 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#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 |
| - | - |
| 400 / schema validation | 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 | Refresh the catalog or verify the task ID; 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 | Refresh and review the fields and connections before queueing |
| 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.
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.