ComfyUI Integration Guide

1. How it connects

In this app ComfyUI is a model provider, and the model id is the workflow file name (not the checkpoint name). Images / video / audio all run through the same job: submit an API-format graph → poll the job → collect results by output type.

2. Install comfy-api-proxy locally

comfy-api-proxy turns your local ComfyUI (8188) into API 2 (8189). It requires Python 3.10+.

2.1 Start ComfyUI first

1. Launch ComfyUI as usual and confirm http://127.0.0.1:8188 opens in a browser.
2. Put the checkpoints / LoRAs / video or audio models you need into ComfyUI's models/.

2.2 Install and start the proxy

In a separate terminal:

pip install comfy-api-proxy
comfy-api-proxy

By default it forwards http://127.0.0.1:8188 to local port 8189, running in the foreground; Ctrl+C stops it. To change the port or the ComfyUI address:

comfy-api-proxy --comfyui http://127.0.0.1:8188 --port 8189

Optional: when it runs next to the ComfyUI install, pass the base directory so you can drop weights into the model folders later:

comfy-api-proxy --comfyui http://127.0.0.1:8188 --port 8189 --comfyui-base-dir D:\ComfyUI

On Windows, if comfy-api-proxy isn't recognized as a command, use:

python -m comfy_api_proxy

or py -3.12 -m pip install comfy-api-proxy followed by py -3.12 -m comfy_api_proxy.

2.3 Check the proxy is alive

Open this in a browser or terminal:

http://127.0.0.1:8189/api/v2/health

Any response means API 2 is ready. Clicking “Fetch models” in this app's settings also probes /api/v2/jobs first.

3. Prepare an API-format workflow

At generation time the app fetches JSON from ComfyUI userdata by model id, then writes in the prompt, size, seed and reference images. It must be API format (nodes as class_type + inputs), not a canvas export with nodes / links.

1. In ComfyUI settings, turn on Enable Dev mode Options.
2. A Save (API Format) entry appears in the menu — export the current graph as JSON.
3. Name it by purpose, matching the model id you tick in settings. The built-in ids are:
   • txt2img — text to image
   • img2img — image to image (needs LoadImage)
   • txt2vid — text to video
   • img2vid — image to video
   • txt2audio — text to audio
4. Drop the file into the ComfyUI user directory — any of these works (a trailing .json is optional):
   • ComfyUI/user/default/txt2img.json
   • ComfyUI/user/default/workflows/txt2img.json
   • ComfyUI/user/default/aiartengine/txt2img.json

The app writes the node prompt into the first positive CLIPTextEncode (titles containing Negative count as negative), the size into EmptyLatentImage, the seed into KSampler / RandomNoise, and uploaded reference images into LoadImage.

4. MiniMax H3 video

MiniMax H3 is an open-weight video model; its official nodes ship with recent ComfyUI builds (comfy_extras/nodes_minimax_h3.py), so no third-party nodes are needed. It supports text-to-video (T2V), image-to-video (I2V), first/last frame (FL2V) and multimodal reference (R2V), and can generate a native stereo audio track.

4.1 Required model files

Pull these weights from ComfyUI's model downloader (names must match your local models/):

• H3 diffusion model (UNet)
• Video VAE
• Audio VAE (skip it if you don't generate sound)
• CLIP (Qwen3-VL)

4.2 Built-in nodes

• MiniMaxH3ImageToVideo — text-to-video / first+last frame image-to-video (first_frame / last_frame)
• MiniMaxH3ReferenceToVideo — multimodal reference (image / video / audio)
• EmptyMiniMaxH3LatentAV — joint video + audio latent
• MiniMaxH3AddGuide — anchor image / audio guidance at a given frame

4.3 Hard size and frame constraints

H3 uses a 1×2×2 latent patch, so width / height must be a multiple of 32 (otherwise you'll see shape … is invalid for input of size); frame counts land on the 17k+5 grid at 24 fps.

This app handles it automatically: once H3 nodes are detected it snaps width/height to the nearest multiple of 32, clamps them to the native canvas scale (768 short side / 768×1344 area cap), and writes duration as 5s→124 frames, 8s→192 frames, 10s→243 frames. So even if your workflow carries a ResolutionSelector or math nodes computing frame counts, they get overridden.

4.4 Suggested minimal I2V workflow

1. LoadImage → MiniMaxH3ImageToVideo's first_frame.
2. MiniMaxH3ImageToVideo takes CLIP and the video VAE; its positive output goes to BasicGuider.
3. LATENT → sampler → VAEDecode → SaveVideo (add VAEDecodeAudio if you want sound).
4. Export with Save (API Format), name it e.g. video_minimax_h3_i2v, and place it in user/default/workflows/.

Official full examples and prompt writing: ComfyUI · MiniMax H3 tutorial.

5. Add ComfyUI in this app

1. Open Settings → Models → Add model provider → ComfyUI.
2. Set the Base URL to http://127.0.0.1:8189 (local) or your cloud endpoint.
3. Local setups can leave the key empty; if the proxy was started with --token, paste that same string into API Key.
4. After enabling, click Fetch models on the Image / Video / Audio tabs, tick what you need and set the defaults.
5. Once saved, entries such as ComfyUI · txt2img appear in the model dropdowns of image / video / audio generation nodes.

To run an image node: pick txt2img, write a prompt and execute. The task queue shows submission and polling; on failure check the run log (missing nodes, missing weights and missing workflows are all spelled out).

6. Comfy Cloud

1. Request an API Key from the Comfy developer docs. The free tier usually can't call the API.
2. In settings, change the Base URL to https://cloud.comfy.org and fill in the key.
3. Workflows still must be API format; the cloud may also pull extra items from its template directory.

7. FAQ

• Connection test failed / 404: ComfyUI runs on 8188 while this app calls 8189. Make sure comfy-api-proxy is running and the Base URL isn't set to 8188.
• Workflow not found: the file name doesn't match the model id, or the file isn't API format. Re-export with Save (API Format) into user/default/ or user/default/workflows/. Job submission goes through the proxy on 8189, while workflow reads use the “ComfyUI base address” in settings — fill that in and 8188 is never contacted. If you move ComfyUI to 8190: set the base address to http://127.0.0.1:8190 and restart the proxy as comfy-api-proxy --comfyui http://127.0.0.1:8190 --port 8189, otherwise video jobs still hit the old 8188.
• Missing nodes / models: the workflow's custom nodes and weights must already be installed on this ComfyUI instance.
• Image-to-image has no reference image: the workflow must contain LoadImage, and you must connect a reference image to the node.
• MiniMax H3 reports shape … is invalid for input of size: width/height isn't a multiple of 32 (H3 latents use 1×2×2 patching). The app snaps and clamps them automatically; if your hand-written workflow hard-codes a ResolutionSelector with values that aren't multiples of 32, delete it or switch to multiples of 32.
• An H3 workflow doesn't appear under Fetch models: put the API-format JSON into user/default/ or user/default/workflows/ first, then click Fetch models in settings again; the app classifies it as a model on the Video tab by node type.
• Do I need the legacy /prompt endpoint? No — this app only maintains API 2.

Official references: API 2 submit a job · comfy-api-proxy · API-format workflow.