跳到主要内容

接入 ComfyUI workflow

ArcReel 可以把一份 ComfyUI API 格式 workflow 接成图像或视频调用端点。workflow 决定模型、节点和固定参数；节点绑定告诉 ArcReel 应把提示词、尺寸、素材等请求数据写到哪里，以及从哪个节点取回产物。

如果你只需要配置云端模型，请先阅读供应商与模型配置。本页适用于由你维护 ComfyUI 服务和 workflow 的场景。

1. 准备工作与连通性检查​

开始前请准备：

  • 一台 ArcReel 服务端能通过 HTTP 访问的 ComfyUI；
  • 已在 ComfyUI 中成功运行、所需模型和自定义节点均已安装的 workflow；
  • 从 ComfyUI 导出的 API 格式 JSON；
  • 如 ComfyUI 位于反向代理之后，准备对应的 Base URL 和 API Key。

ArcReel 与 ComfyUI 之间只有 HTTP。素材经 POST /upload/image 传到 ComfyUI 的输入区，产物经 /history 与下载接口取回，不需要两台机器共享文件系统，也不需要把 ArcReel 的媒体目录挂给 ComfyUI。ComfyUI 跑在本机还是另一台机器上，走的是同一条代码路径，配置方式没有区别——本机部署只是把 Base URL 填成本地地址。

1.1 新建 comfyui 供应商​

在「设置 → 供应商」新增供应商，协议选 comfyui，填写 Base URL。ComfyUI 本身通常不鉴权，API Key 可以留空；只有反向代理需要凭据时才填。这条协议没有模型发现步骤：一份 workflow 就是一个型号，模型行由你为它挑选调用端点（见第 2 节）。

保存时的连通性检查以 API Key 作 Bearer 裸打 /system_stats，留空则不带任何凭据，读到的 ComfyUI 版本会回显在设置页。

若你的反向代理用的是自定义请求头（而不是 Authorization: Bearer）鉴权，这条探针会被代理挡下、报成不可达——它不支持端点定义 auth 节里的自定义头。这种情况下探针的结论没有参考价值，请以端点的「预览请求」和「测试连接」为准：那两条路径才会按 auth 节把 API Key 注入请求头或查询参数。

2. 导出并导入 workflow​

ComfyUI 的导出菜单有两项，只有其中一项能用：

  • Export：画布存档，带 nodes 数组与 links，记的是节点在画布上的位置和连线。它没有 class_type，ComfyUI 的 /prompt 接口不收这种形状，因此 ArcReel 直接拒绝并提示改用另一项。
  • Export (API)：以节点 id 为键的节点表，正是提交给 /prompt 的形状。导入这一份。

导入步骤：

  1. 在「设置 → 调用端点」导入 API workflow JSON。
  2. 给端点填写能区分用途的名称，并确认媒体类型是图像还是视频。
  3. 检查自动识别的节点绑定（见第 3 节）。
  4. 确认正向提示词与产物节点。这两项必须有落点，且不同语义不能占用同一个字段。
  5. 保存端点，再到「供应商」为 ComfyUI 供应商的模型行选择这份端点。

一行模型对应一份 workflow。workflow 中使用的 checkpoint、LoRA、采样器等固定值不会出现在模型行里；要修改它们，请在 ComfyUI 中修改 workflow、重新导出，再用「重新导入」更新端点。重导入会尝试按节点身份重新匹配既有绑定，标为「需确认」的项目必须人工复核。

3. 节点绑定​

ComfyUI 没有统一的参数化约定，导出物里每个节点只有 inputs、class_type 和标题，哪个节点收提示词、哪个产出成片只能推断。ArcReel 把推断收在导入这一步，并且只产出候选：唯一最高分的候选标为「自动识别」，多个候选同分时不自动选、交你挑，一个候选都没有时你可以从全部节点入口里手选。这份 workflow 确实没有的能力请标为「不支持」，ArcReel 之后不再为它推断，也不会往图上写这一项。

3.1 常用绑定​

绑定ArcReel 的行为
正向提示词写入不含 Avoid: 行的提示词正文；必填
负向提示词把正文中的 Avoid: 排除项追加到该节点的原有字面值
首帧、尾帧、参考图上传本次提供的素材，再把 ComfyUI 返回的引用名写入读图节点
宽、高根据画幅比例和分辨率档换算，并按各自步长向下对齐
帧数根据秒数与帧率换算，并对齐到 步长 × n + 1
帧率只读绑定；ArcReel 从 workflow 读取字面值用于换算，不会改写它
种子按该条目的策略决定是否改写
产物节点从该节点输出中取回最终图像或视频；必填

3.2 让 ArcReel 认准某个节点​

推断认错节点、或同分候选太多时，有两种办法不必每次手选：

  • 标题约定。 在 ComfyUI 里把节点标题改成 ARCREEL:<语义键>（如 ARCREEL:prompt、ARCREEL:seed、ARCREEL:output），ArcReel 会把它当成仅次于手动绑定的最强信号，压过任何按输入名或节点类型得出的猜测。前缀大小写不敏感，冒号之后取第一个词作语义键，后面可以继续写你自己看的说明。这份标记留在 workflow 里，重新导出、重新导入后依然有效。

  • 外部约定节点族。 若 workflow 已经用了下面这几家的输入节点来声明对外参数，ArcReel 直接按它们的声明认领，不必再改标题：

    节点族节点类型前缀参数名取自
    ComfyUI-DeployComfyUIDeployExternalinput_id 输入
    comfy-packCPackInput节点标题
    ComfyUI-Serving-ToolkitServingInputargument 输入

    参数名规范化（转小写、非字母数字并成下划线）后与语义键相同才算命中，例如 Reference Images 与 reference_images 等价。

两种办法都只是把候选的分数抬高，最终仍以你在导入界面上确认并保存的绑定为准。

4. 尺寸、时长与种子​

4.1 固定尺寸​

只有宽和高都已绑定时，ArcReel 才按画幅比例和分辨率档改写尺寸。只绑一侧不算：派生出的宽高只写得进绑了的那一侧，出片比例既不是 workflow 原生的也不是你选的，比两侧都不绑更糟。因此缺任一侧即整维判为「尺寸固定」，界面禁用分辨率选择器，尺寸跟随 workflow 自己的值。

两侧都绑定时，若每个绑定入口都读得出同一个正整数字面值，分辨率选择器的空值占位会显示由它推出的原生档位（如「workflow 原生（480p）」），让你看得见「不选档位会得到什么」；字面值读不出或彼此不一致时不显示。尺寸判为固定的那一支没有这个值——那一支由界面直接说明尺寸由 workflow 决定。

图像档位为 512px、1K、2K、4K，视频档位为 480p、720p、1080p、4K。它们是换算目标，不保证任意 workflow 或显存配置都能跑得动。

4.2 固定时长与空档位​

视频时长档位为空有三种原因，界面会分别说明：

  • 未绑定 frames：ArcReel 没有任何指针指向帧数所在的输入，时长完全由 workflow 固定，提交时不写帧数。
  • 绑了 frames，但读不到帧率来源：既没有 fps 只读绑定，也没有在帧数条目上手填帧率，秒数换算不出来。这不是这份 workflow 天生时长固定，而是一份可修的定义——补一个 fps 绑定或在帧数条目上手填帧率，ArcReel 才换算得出时长档位（补齐之后仍可能落进下一支）。
  • 绑了 frames、帧率也读得到，但换算不出一档能原样写回这份 workflow 的整秒时长：例如 81 帧 @ 24fps 折成 3 秒，而按 3 秒换算回去是 73 帧；帧数入口接的是链接、或写着 1 这类占位值读不出片长时，同样凑不出这一档。一个名为「原生」、选中却会改动原图的档位比没有档位更坏，所以这一档不给出。这一支里只有「每个帧数入口都写着自己的片长」这一种形态提交时不改写帧数；另两种没有片长可保，帧数仍按规划层借来的秒数写入。

三支之外，帧数与帧率都可用且能原样写回时，ArcReel 按 原生秒数 = round((字面帧数 − 1) ÷ 帧率) 推出该 workflow 的原生时长作为默认档位；「能原样写回」判的是它的逆向换算 frames = round(秒数 × 帧率) + 1 按步长对齐后是否还等于字面帧数。默认档位你可以在模型行里增删。

档位为空不是「模型未配置可用时长」这类通用错误。剧本规划仍会借一份篇幅参考档位以免卡住，但实际出片时长始终由 workflow 决定。

4.3 三种种子策略​

策略记在每个种子条目上，一份 workflow 里可以混用：

  • 未绑定种子：ArcReel 不碰 workflow 的种子字段；
  • random：有请求种子时用它，否则每次提交生成一个新种子。同一份 workflow 里所有 random 条目写同一个值——双采样器各随机一次会让同一次生成不可复现；
  • keep：一个字节都不动，请求自带的种子也顶不掉它。

视频结果记录的是本次实际生效的种子（全是 keep 时即 workflow 的字面值）和实发 workflow 的指纹，据此可以核对某一版是照哪份图、用哪个种子出的。

4.4 素材没给满时的改图​

首尾帧和参考图都是「绑定了但这次没给值」就要改图：读图节点留在图里会按 workflow 里写死的文件名去读上一张图，模型照着它出片，而你根本没选过那张图。

  • 首帧、尾帧：这次没给值就删掉对应的读图节点，以及因此不再可达的下游支路。
  • 参考图：按张数依次填，多出来的格子删掉。前提是 ArcReel 认得这个格子接到的入口是可选的或来自两两合并节点；认不出来时不删，而是把最后一张重复填进多余的格子——宁可构图偏一点，也不凭猜测摘掉一个必需输入、让 ComfyUI 在提交时报错。一张都没给时读图节点保持底稿字面值。

若待删支路连到产物链路，任务会以 comfyui_image_drop_unsupported 拒绝；请补齐图片，或换一份能接受该输入组合的 workflow。

5. 提示词​

提示词按原文直发，ArcReel 不翻译，也不改写。因此请选用读得懂你所写语言的模型：中文提示词要配能读中文的模型才有效，否则模型只会对着一段它读不懂的文字出片。就视频而言 Wan 系列官方即推荐中文提示词；图像侧 Qwen-Image、Kolors 为中英双语。其余模型多以英文训练，用中文下达的构图与动作往往被忽略——把提示词改写成英文比反复调参更有效。

提示词正文里的 Avoid: 行不随正文发给模型。绑定了负向提示词节点时，这些排除项会追加到该节点的原有字面值之后；没有绑定就只是丢弃——正文里看不见它们，workflow 里也不会出现。workflow 有独立负向提示词节点的，请务必绑上。

6. 预览与测试连接​

端点详情页提供两张测试卡，参数、凭证与素材由两卡共用——中间换掉任何一项，两卡说的就不是同一件事了：

  • 预览请求只渲染将要发往 /prompt 的 workflow、鉴权和换算说明，不访问 ComfyUI。预览中的凭据会被打码；素材位置显示的是占位描述而非真实上传后的引用名。
  • 测试连接视频端点与图像端点都提供。它真实上传素材、提交 workflow、轮询执行并下载产物，会占用 ComfyUI 的队列和 GPU。点之前请先在预览里核对节点、尺寸、帧数、种子和本次被删的节点。

测试任务在 ComfyUI 队列中显示为 endpoint-test-…（后缀是一段随机串，以免连测几次时上传的素材互相覆盖）。取消或超时时，ArcReel 会尽力同时叫停远端：新版 ComfyUI 按任务 ID 取消；旧版则先查队列，排队中的删掉，正在执行的只在确认当前运行项就是本任务时才打断——/interrupt 不认 id，认错会停掉别人的活。网络故障可能让远端叫停失败，因此取消后仍应回 ComfyUI 队列看一眼。

7. 运行与存储​

  • 上传素材保存在 ComfyUI 的 input/arcreel/ 下，与你自己传的图分开。ArcReel 不会自动清理这些文件，它们会随使用累积；请按自己的留存要求监控磁盘，需要时直接删除该目录下的内容。
  • 默认并发数为 1。一台只有一张 GPU 的 ComfyUI 提高并发通常只会让更多任务在远端排队；仅在机器容量允许时调高。
  • 视频任务的轮询超时可配：「设置 → 视频轮询超时（秒）」，最低 60 秒，改动对之后开始处理的任务生效。ComfyUI 跑在你自己的显卡上又要排队，默认值对大图未必够，按实际出片耗时调。图像任务这一维没有可配项，取一个够宽的固定上限。
  • 视频任务提交后会保存 ComfyUI 的 prompt_id。ArcReel 重启后可继续轮询同一任务，不会重新上传或重复提交。
  • 图像任务不支持重启后续跑：prompt_id 无处持久化，生成中重启会把该任务标为丢失，避免让你的显卡把同一张图再跑一遍。
  • 一次执行产出多个文件时，两条通道都按端点媒体类型的扩展名白名单取第一个匹配的产物；视频任务额外在结果上挂一条提示，图像任务只写日志。
  • 产物容器白名单：视频端点收 .mp4 / .mov / .m4v，图像端点收 .png / .jpg / .jpeg / .webp。成片按固定的 .mp4 资源路径入库、字节原样保存，故只收得下 ISO BMFF 这一族；SaveWEBM 之类导出的 .webm 会被判产物类型不符，请在保存节点上改选 mp4（SaveVideo 选 h264-mp4）。落盘后 ArcReel 还会按文件头核一遍真实容器：名字写着 .mp4、内容却是别的容器时同样拒收，不留一份打不开的成片。

8. 常见失败​

失败码含义与处理
comfyui_upload_failed素材未上传成功。检查地址、凭据、网络和 ComfyUI 磁盘后重试
comfyui_node_errorsComfyUI 拒收 workflow。通常是缺模型、节点不存在或参数越界；到 ComfyUI 修复后重新导入
comfyui_job_lost队列和历史都找不到 prompt_id，通常是 ComfyUI 重启；重新生成
comfyui_execution_error某个节点执行失败；按报出的节点在 ComfyUI 检查模型、节点和输入
comfyui_interrupted执行被人工或其他客户端中断；确认队列状态后重试
comfyui_output_missing绑定的产物节点没有输出文件；检查产物节点及其上游链路
comfyui_output_type_mismatch产物扩展名不在该端点的容器白名单内；改绑实际导出最终媒体的那个节点，或在保存节点上改选受支持的格式
comfyui_output_container_mismatch扩展名对得上，但文件内容不是该端点应产出的容器；在保存节点上改选受支持的格式
comfyui_image_drop_unsupported缺少素材时要删的支路影响了产物；补齐素材或改用另一份 workflow

comfyui_upload_failed、comfyui_job_lost 与 comfyui_interrupted 是一时的环境问题，失败码卡与项目页据此给出「再试一次」；其余六项指向端点配置，要回端点详情改绑定，或在 ComfyUI 里修好 workflow 再重新导入。

如果任务显示多个产物但只保留了一个，这是当前通道的选择规则，不代表 ComfyUI 少生成了文件。先在预览中确认产物节点，再到 ComfyUI 历史记录核对完整输出。

9. 费用与执行时长​

ComfyUI 跑在你自己的机器上，ArcReel 不知道这次出片值多少钱，因此默认把每次调用的费用记为 0；测试连接同样记 0。执行时长照常记录，用量页上这些调用有完整的耗时与次数，只是金额那一列是 0。

若要把自建 GPU 的成本分摊进 ArcReel 的用量统计，可以在该供应商的模型行上填一个你自己核算出的单价和币种：图像按每次调用计，视频按每秒乘以时长计。填了之后调用照常记账，金额按这个单价算出来。这个数字完全由你决定，ArcReel 不会替你估算，也不会因此改变任何生成行为。

费用记 0 不等于不花钱——它花的是电、显卡占用和排队时间。不要在其他重要任务占用同一张 GPU 时反复测试。