Comfly 视频供应商
用途
通过服务端统一凭据，在项目和画布中使用 MiniMax H3。VVICAT 对外只展示一个模型，并根据输入素材和输出尺寸自动选择 Comfly 工作流。
使用前准备
Comfly 凭据由部署者通过服务端环境变量统一配置，不会发送到浏览器，也不能在个人设置中填写或覆盖：
COMFLY_ENABLED=true
COMFLY_TOKEN=
COMFLY_BASE_URL=https://vvicat-comfly-prod.vvicat.dev
COMFLY_APP_ID=0COMFLY_ENABLED 不填或设为 true 时启用；设为 false 时停止新任务提交和已有任务轮询，变更后需重启 Web 与视频 Worker。启用时 COMFLY_TOKEN 必填。COMFLY_BASE_URL 不填时使用上面的生产地址；不同环境必须提供与该环境 workflow 目录匹配的地址和 token。COMFLY_APP_ID 不填时为 0。
Comfly 管理 token 仅用于管理接口，不属于 VVICAT 运行时配置，也不得代替 COMFLY_TOKEN。
配图占位
- 页面：管理后台的模型配置
- 状态：Comfly 供应商与 MiniMax H3 模型已启用
- 重点区域：供应商状态、模型修订和积分价格
- 脱敏要求：不得显示 token、邮箱、余额或请求日志
操作步骤
- 部署者配置环境变量并重启 Web 与视频 Worker。
- 管理员进入 管理后台 → 模型配置，确认 Comfly 供应商和
MiniMax H3模型已启用，并发布完整价格修订。 - 用户在个人、项目或画布设置中选择
MiniMax H3。 - 提供 1–3 张图片或 1 个参考视频，选择时长、分辨率和比例后提交。
当前自动路由：
| 条件 | Workflow ID |
|---|---|
| 1 / 2 / 3 张图片，不指定尺寸 | 1518 / 1519 / 1520 |
| 1 个参考视频 | 1521 |
| 1 / 2 / 3 张图片，指定分辨率和比例 | 1540 / 1541 / 1542 |
图片工作流支持 720p、1K、2K 与 16:9、9:16，系统会换算为工作流需要的宽高。所有已接入工作流支持 5–15 秒整数时长。旧配置中的工作流模型 ID 会自动兼容为 MiniMax H3；历史账号或项目中保存、但当前模型已不再声明的能力字段（如 fps）会在执行时忽略，不会阻断任务。
结果与状态
VVICAT 为每次请求生成幂等任务 ID，提交后由视频 Worker 轮询 Comfly。pending 和 running 保持处理中；success 仅在工作流没有节点错误且返回视频文件时归档到 VVICAT 存储；failed、canceled 或工作流输出中的 Error: 会结束任务并显示错误。即使 Comfly 因生成了文件而返回成功，VVICAT 也不会保存已知由内部错误产生的无关视频。
已启用的 MiniMax H3 会进入项目配置和画布“视频生成”节点的模型下拉，无需用户侧 API Key。工作流 ID 不会显示给用户。
权限和限制
- 用户只能选择
MiniMax H3；供应商连接、模型启停和价格由管理员维护。 - 部署者可通过
COMFLY_ENABLED=false停止服务；模型仍会显示，但提交或轮询会返回COMFLY_DISABLED。 /api/user/api-config会拒绝为 Comfly 提交用户级 token 或 Base URL。- 当前仅支持 1–3 张图片或 1 个参考视频；纯文本、4–9 张图片、2 个视频、音频及混合输入会明确失败，不会错误路由。
- 当前目录使用上表 workflow ID。若测试环境没有相同 ID，部署者需先在 Comfly 同步工作流，不能直接复用生产 ID。
- Comfly 成功响应必须返回可下载的首个
files项；缺失文件时任务会失败，避免保存空产物。 - 工作流节点不得把
Error:文本当作正常提示词继续生成；VVICAT 会将这类返回判定为失败。
常见问题
管理后台已启用，但生成时报 COMFLY_TOKEN_MISSING
目录启用不代表当前进程一定已加载 token。检查 Web 和视频 Worker 的 COMFLY_TOKEN，然后重启进程。
任务返回 COMFLY_DISABLED
检查 Web 与视频 Worker 的 COMFLY_ENABLED。需要恢复服务时设为 true 或删除该变量，然后重启两个进程。
已启用模型但画布视频节点没有显示
确认管理员已启用供应商和模型、且已发布价格修订，然后刷新画布。Comfly 不要求个人设置中存在 API Key。
提示素材数量不支持
当前至少需要 1 张图片或 1 个视频。图片最多 3 张，视频最多 1 个；暂不支持参考音频。
测试环境返回 workflow 不存在
确认 COMFLY_BASE_URL 指向目标环境，并在该环境创建或同步同 ID workflow；token 和 workflow 目录必须属于同一环境。