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

# Mage for ComfyUI

> Run Mango, Cherry, Seed Audio, and every other Mage model as ComfyUI nodes: install from ComfyUI-Manager or the Comfy CLI, add your Mage API key, and queue. No GPU and no model downloads.

Mage for ComfyUI is an open-source custom node pack, `comfyui-mage`, that runs Mage's image, video, and audio models from your ComfyUI workflows. The models run on Mage's servers, so the nodes need no GPU and no model downloads. Each run spends Gems from the Mage account whose API key you set.

<Note>The nodes are in beta at `0.x`, so their inputs may still change.</Note>

## Install

<Tabs>
  <Tab title="ComfyUI-Manager">
    1. Open **ComfyUI-Manager** and select **Custom Nodes Manager**.
    2. Search for **Mage** and select **Install**.
    3. Restart ComfyUI when asked.
  </Tab>

  <Tab title="Comfy CLI">
    ```bash theme={null}
    comfy node install comfyui-mage
    ```
  </Tab>

  <Tab title="Manual">
    Clone the repository into `custom_nodes` and install its requirements with the Python environment ComfyUI uses.

    ```bash theme={null}
    cd ComfyUI/custom_nodes
    git clone https://github.com/mage-space/ComfyUI-Mage
    pip install -r ComfyUI-Mage/requirements.txt
    ```
  </Tab>
</Tabs>

The nodes depend on the [Python SDK](/api/sdks/python), `mage-space`, and on packages ComfyUI already ships. They need a recent ComfyUI.

## Add your API key

Create a key in [API → API Keys](https://www.mage.space/api?tab=api-keys), then do one of the following:

* Set the `MAGE_API_KEY` environment variable before starting ComfyUI.

  ```bash theme={null}
  export MAGE_API_KEY="mage_sk_..."
  ```

* Or copy `config.ini.example` to `config.ini` in the `ComfyUI-Mage` folder and paste the key after `api_key =`.

The environment variable wins when both are set. The key is never stored in your workflows, so you can share them safely.

## Nodes

The nodes are in the **Mage** category.

| Node | Makes | Inputs |
| - | - | - |
| **Mage Mango Image** | IMAGE | Prompt, model, aspect ratio, resolution, and seed; optional reference images, or the image to edit. |
| **Mage Cherry Video** | VIDEO | Prompt, model, aspect ratio, resolution, duration, and seed; optional reference images and a source video. The video includes sound. |
| **Mage Seed Audio** | AUDIO | Prompt, duration, and seed; an optional image for the audio to match. |
| **Mage Generate (any model)** | IMAGE, VIDEO, or AUDIO | Model family, variant, prompt, seed, and any other fields as JSON; optional reference images, first and last frames, and a video. |

Each node also outputs the result's `url`. Mage keeps outputs for 30 days, so save anything you want to keep with ComfyUI's save nodes.

The option lists on Mango, Cherry, and Seed Audio come from the API reference, so they match the [model pages](/api/models/overview). A variant may offer fewer values than its family lists; a model refuses a value it does not offer before any Gems are spent.

### Mage Generate

**Mage Generate** runs any model in the API. Choose the family in `architecture`, optionally a variant in `model_id`, and put the model's other fields in `extra_config` as a JSON object, for example:

```json theme={null}
{ "aspect_ratio": "16:9", "resolution": "720p", "duration": "5" }
```

Connect `images` for reference images, `first_frame` and `last_frame` for models that start or end a video on an image, and `video` for a source video. A model that takes no such input refuses it before anything is uploaded. Only the output that matches what the model makes carries a value: a node connected to a different one stops with a message naming the output to use instead.

## Costs and caching

* Every run spends Gems at the model's listed price. The node shows the request's status and the Gems it cost while it runs.
* The seed is fixed by default, so queueing the same inputs again reuses ComfyUI's cached output instead of paying for a new run. Change the seed, or set it to randomize, when you want a variation.
* Stopping the queue cancels every Mage request the workflow started, including one whose submission was still being answered. Cancelled runs are not refunded.
* A request your balance cannot cover, or a value the model does not offer, fails the node with the API's message before any Gems are spent.

## Characters and references

Mention your saved characters and references by `@handle` in any prompt, exactly as on mage.space. See [Characters and references](/api/inputs#characters-and-references).

## Troubleshooting

| Message | What to do |
| - | - |
| No Mage API key | Set `MAGE_API_KEY` or create `config.ini`, then restart ComfyUI. |
| `insufficient_gems` | Add Gems to the account that owns the key. |
| `invalid_config` | The model does not take one of the values or fields you set. Its model page lists what it accepts. |
| A model takes no video input, or no frame image | Disconnect that input, or pick a model that takes it. |
| The node is missing after installing | Restart ComfyUI and check its console for an import error; install `requirements.txt` with ComfyUI's own Python. |

## Privacy

Images and videos you connect to a node are uploaded to Mage storage and deleted after 30 days, like the outputs. The nodes send nothing else and collect no telemetry.

## Source

The nodes are MIT-licensed on [GitHub](https://github.com/mage-space/ComfyUI-Mage) and published to the [Comfy Registry](https://registry.comfy.org/nodes/comfyui-mage).

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/api/sdks/python">
    The client the nodes are built on.
  </Card>

  <Card title="Models" icon="layer-group" href="/api/models/overview">
    Every model with its fields, options, and price.
  </Card>
</CardGroup>