BoosAPI/docs/superpowers/specs/2026-06-18-digital-human-comfy-video-entry-design.md

数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计

日期:2026-06-18 分支:feat/comfy-cloud-adapter 状态:已通过调查,待用户复审

背景

LTX2.3 说话头像工作流(comfy/video_digital_ltx2.json)已就绪并通过 Comfy Cloud 校验 (节点+模型全兼容,probe node_errors:{})。但 BoosAPI 数字人 UI 没有「视频/动画工作流」 入口,无法触发「肖像图 + 旁白音频 → 说话视频」这一步。本设计补齐贯穿三层的入口。

现状(调查结论)

• BoosAPI 数字人前端 src/web/pages/DigitalHuman.tsx:仅 3 个选择器——ttsWorkflow、 imageWorkflow(从 mediaWorkflows 选,默认含 "image" 的)、frameTemplate(HTML 模板)。 无视频/动画工作流选择器。流程是「生成图片 + TTS + HTML 模板合成」,不做说话头像动画。
• BoosAPI 后端 src/routes/digital_human.rs 的 pixelle_request_body(~line 2053):转发 text/mode/title/backend_provider/workflow_source/n_scenes/video_fps/frame_template/ template_params/prompt_prefix/bgm_*/media_workflow/tts_workflow/ref_audio。 不转发 api_video_workflow;workflow_source 写死 runninghub/selfhost(无 comfy)。
• Pixelle pixelle_video/pipelines/asset_based.py(~line 693):动画步读 context.request.get("api_video_workflow");audio_path 仅当 _get_api_workflow_info (查 api_media,只 api/ 通道)匹配到 audio_driven_i2v 能力时才注入 → comfy 工作流 拿不到 audio_path。
• Pixelle 工作流执行按前缀路由:runninghub 走 RunningHub,其余(含 comfy/)走 comfyui_url(= BoosAPI /comfy-cloud 适配器)。comfy/video_digital_ltx2.json 已在 /workflows/media 列出(已加 video_ 前缀)。
• 已完成的前置:comfy-cloud 适配器(已验证)、comfy/video_digital_ltx2.json(标记 image_path/audio_path/prompt,probe 通过)、media.py 转发 image_path(已打补丁)。

已确认决策

1. 加完整视频入口:前端选择器 + 后端转发 + Pixelle 音频注入,三层都改。
2. 视频工作流选择器列 video_* media 工作流(含 comfy/video_digital_ltx2.json)。
3. 单人肖像说话头像;不做多人。

三层改动设计

层 1:前端 src/web/pages/DigitalHuman.tsx

• 新增 state apiVideoWorkflow(默认空=不启用动画,保持现有「图片+HTML」行为向后兼容)。
• 新增「视频工作流(可选)」<select>:选项 = mediaWorkflows.filter(name 含 "video"), 含空选项「不生成视频(仅图片合成)」。
• 提交 payload 增加 apiVideoWorkflow 字段;draft 持久化同步。

层 2:BoosAPI 后端 src/routes/digital_human.rs

• pixelle_request_body 增加:

  if let Some(value) = optional_string(body, &["apiVideoWorkflow", "api_video_workflow"]) {
      request_body["api_video_workflow"] = json!(value);
  }
  

• 若所选视频工作流以 comfy/ 开头,确保 workflow_source 不会阻断(comfy 工作流靠前缀 路由,workflow_source 主要影响 media/tts 默认通道;api_video_workflow 独立按前缀执行, 无需改 workflow_source。实现时验证不冲突)。
• 可选转发 api_video_params(若前端给了音频驱动等参数)。本期最小化:只转发 api_video_workflow。

层 3:Pixelle pixelle_video/pipelines/asset_based.py

• 动画步注入 audio_path 的条件放宽:除 api_media 能力匹配外,当 api_video_workflow 以 comfy/ 开头时,也注入 audio_path = frame.audio_path(comfy 工作流的 $~audio_path! 标记需要它)。最小改动:在 audio_driven_i2v 判断旁边加 comfy 前缀分支。
• 镜像内置文件,改后重启容器,备份到 /opt/Pixelle-Video/patches/。

数据流(目标)

DigitalHuman.tsx: 选 comfy/video_digital_ltx2.json (apiVideoWorkflow)
  → BoosAPI digital_human.rs: request_body.api_video_workflow
  → Pixelle /api/video/generate/async: context.request.api_video_workflow
  → asset_based.py 动画步: 注入 image_path(media.py已补)+ audio_path(本期补)+ prompt
  → media() comfy 前缀 → comfyui_url=/comfy-cloud 适配器 → Comfy Cloud LTX2.3
  → 说话视频 → 帧合成/HTML 模板 → 成片

验证

• 前端 typecheck:npm run typecheck:web。
• 后端构建:cargo build -j 2。
• Pixelle 改动:语法校验 + 重启 healthy。
• 端到端:数字人任务选 comfy/video_digital_ltx2.json,确认 Comfy Cloud 出现 job、 注入了 image_path+audio_path、出说话视频。

非目标

• 不改 comfy-cloud 适配器(已完成)。
• 不做多人对话数字人。
• 不重构数字人现有「图片+HTML 合成」路径(视频入口为可选叠加,默认不启用,向后兼容)。
• 不动 RunningHub 数字人路径。

提交约定

分支 feat/comfy-cloud-adapter。前端、BoosAPI 后端分别提交(项目内,受版本控制); Pixelle 改动在容器内 + 备份 patches/(非本仓库)。中文 commit。