AI Art Engine EN
菜单

Guide · ComfyUI

ComfyUI 接入教程

本软件只走 ComfyUI API 2（POST /api/v2/jobs）。 本机默认的 8188 没有这套接口，需要在旁边再跑 comfy-api-proxy（默认 8189）；云端直接填 https://cloud.comfy.org。

1. 它怎么接

ComfyUI 在本软件里是一个模型提供商，模型 id = workflow 文件名（不是 checkpoint 名）。 图片 / 视频 / 声音都走同一套任务：提交 API 格式图 → 轮询 job → 按输出类型取结果。

场景 Base URL API Key
本机 http://127.0.0.1:8189 可空（proxy 默认无鉴权）
Comfy Cloud https://cloud.comfy.org 必填（付费档才开放 API）
不要把 Base URL 写成 http://127.0.0.1:8188 或带 /v1。 直连 8188 是旧的 /prompt，本软件不会用。

2. 本机安装 comfy-api-proxy

comfy-api-proxy 把本机 ComfyUI（8188）转成 API 2（8189）。需要 Python 3.10+。

2.1 先启动 ComfyUI

  1. 按你平时的方式打开 ComfyUI，确认浏览器能打开 http://127.0.0.1:8188。
  2. 需要用到的 checkpoint / LoRA / 视频或音频模型先放进 ComfyUI 的 models/。

2.2 安装并启动代理

另开一个终端：

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

默认把 http://127.0.0.1:8188 转到本机 8189，前台运行，Ctrl+C 停止。 需要改端口或 ComfyUI 地址时： 

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

可选：与 ComfyUI 安装目录同机时，加上根目录，便于以后往模型目录放权重：

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

Windows 若 comfy-api-proxy 不是命令，用：

python -m comfy_api_proxy

或 py -3.12 -m pip install comfy-api-proxy 后再 py -3.12 -m comfy_api_proxy。

2.3 确认代理活着

浏览器或终端访问：

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

能返回即表示 API 2 已就绪。本软件设置里点「拉取可用模型」也会先探活 /api/v2/jobs。

代理默认只绑 127.0.0.1。不要对局域网裸开 8189；若必须外网访问，先看官方 --token / CORS 说明。

3. 准备 API 格式 workflow

生成时本软件会按模型 id去 ComfyUI userdata 取 JSON，再写入提示词、尺寸、seed、参考图。 必须是 API 格式（节点是 class_type + inputs），不能是带 nodes / links 的画布导出。

  1. 在 ComfyUI 设置里打开 Enable Dev mode Options（开发者模式）。
  2. 菜单出现 Save (API Format)，把当前图画导出为 JSON。
  3. 按用途命名，与设置里勾选的模型 id 一致。内置目录为：
    • txt2img — 文生图
    • img2img — 图生图（需 LoadImage）
    • txt2vid — 文生视频
    • img2vid — 图生视频
    • txt2audio — 文生声音
  4. 把文件放到 ComfyUI 用户目录，任选其一即可（文件名带不带 .json 均可）：
    • ComfyUI/user/default/txt2img.json
    • ComfyUI/user/default/workflows/txt2img.json
    • ComfyUI/user/default/aiartengine/txt2img.json

本软件会把节点指令写入第一张正向 CLIPTextEncode（标题含 Negative 的当负向）；尺寸写入 EmptyLatentImage；seed 写入 KSampler / RandomNoise；参考图上传后写入 LoadImage。

也可在设置里手动添加已有 workflow 文件名（不必用内置那五个 id）。 图里的 checkpoint 名必须和本机 models/ 里的文件一致。

4. MiniMax H3 视频

MiniMax H3 是开源权重的视频模型，官方节点已内置在较新的 ComfyUI 里 （comfy_extras/nodes_minimax_h3.py），无需安装第三方节点。 支持文生视频（T2V）、图生视频（I2V）、首尾帧（FL2V）、多模态参考（R2V）， 并可同步生成原生立体声音轨。

4.1 需要的模型文件

在 ComfyUI 的模型下载里拉齐这些权重（名字以本机 models/ 为准）：

  • H3 扩散模型（UNet）
  • 视频 VAE
  • 音频 VAE（不生成声音可省略）
  • CLIP（Qwen3-VL）

4.2 内置节点

  • MiniMaxH3ImageToVideo — 文生视频 / 首尾帧图生视频 （first_frame / last_frame）
  • MiniMaxH3ReferenceToVideo — 多模态参考（图片 / 视频 / 音频）
  • EmptyMiniMaxH3LatentAV — 视频 + 音频联合 latent
  • MiniMaxH3AddGuide — 在指定帧锚定图片 / 音频引导

4.3 尺寸与帧数硬约束

H3 的 latent 采用 1×2×2 分块，width / height 必须是 32 的整数倍（否则会报 shape … is invalid for input of size）；帧数按 24fps 落在 17k+5 网格上。

本软件已自动处理：检测到 H3 节点后，会把宽高就近对齐到 32、再压到原生画布量级 （768 短边 / 768×1344 面积上限），并把时长按 5s→124 帧、8s→192 帧、10s→243 帧写入。 所以 workflow 里即便挂了 ResolutionSelector 或自算帧数的数学节点，也会被本软件覆盖。

4.4 最小 I2V workflow 建议

  1. LoadImage → MiniMaxH3ImageToVideo 的 first_frame。
  2. MiniMaxH3ImageToVideo 接 CLIP 与视频 VAE，正向输出接 BasicGuider。
  3. LATENT → 采样器 → VAEDecode → SaveVideo（有声音再接 VAEDecodeAudio）。
  4. 用 Save (API Format) 导出，命名如 video_minimax_h3_i2v，放到 user/default/workflows/。

官方完整示例与提示词写法： ComfyUI · MiniMax H3 教程。

5. 在本软件里添加 ComfyUI

  1. 打开设置 → 模型 → 添加模型提供商 → ComfyUI。
  2. Base URL 填 http://127.0.0.1:8189（本机）或云端地址。
  3. 本机可空 Key；若 proxy 加了 --token，把同一串填进 API Key。
  4. 启用后，在图片 / 视频 / 声音页签分别「拉取可用模型」并勾选，设默认项。
  5. 保存后，图片生成 / 视频生成 / 声音生成节点的模型下拉里会出现 ComfyUI · txt2img 等。

跑一条图节点：选 txt2img，写指令，执行。任务队列里能看到提交与轮询；失败时看执行日志（缺节点、缺权重、workflow 找不到都会写明）。

6. 云端 Comfy Cloud

  1. 在 Comfy 开发者文档 申请 API Key。免费档通常不能调 API。
  2. 设置里 Base URL 改为 https://cloud.comfy.org，填入 Key。
  3. workflow 仍须是 API 格式；云端还可能从模板目录拉到额外项。

7. 常见问题

  • 连接测试失败 / 404：ComfyUI 在 8188，但本软件打的是 8189。先确认 comfy-api-proxy 在跑，Base URL 不要写成 8188。
  • 未找到 workflow：文件名与模型 id 不一致，或不是 API 格式。用 Save (API Format) 再放到 user/default/ 或 user/default/workflows/。 提交任务走 proxy 的 8189，读取 workflow 走设置里的「ComfyUI 本体地址」。 填了本体地址就不会再连 8188。ComfyUI 改到 8190 时：本体地址填 http://127.0.0.1:8190，并把 proxy 重开为 comfy-api-proxy --comfyui http://127.0.0.1:8190 --port 8189， 否则视频任务仍会打到旧的 8188。
  • 缺节点 / 缺模型：workflow 里的自定义节点和权重必须已装在这台 ComfyUI 上。
  • 图生图没有参考图：workflow 里要有 LoadImage；节点上要连参考图。
  • MiniMax H3 报 shape … is invalid for input of size：说明宽高不是 32 的整数倍 （H3 latent 采用 1×2×2 分块）。本软件会自动对齐并压到原生画布；若你手写的 workflow 里 固定了 ResolutionSelector 且数值不是 32 的倍数，删掉它或改成 32 的倍数即可。
  • H3 workflow 在「拉取模型」里看不到：先把 API 格式 JSON 放到 user/default/ 或 user/default/workflows/，再回设置里「拉取可用模型」； 本软件按节点类型把它识别为「视频」页签下的模型。
  • 要不要接旧版 /prompt？：不必。本软件只维护 API 2。

官方说明： API 2 提交任务 · comfy-api-proxy · API 格式 workflow。