From 6b3f5a6a2a27374f3a16d4b0c436b0e7020e8775 Mon Sep 17 00:00:00 2001
From: yibo <bboonnee@gmail.com>
Date: Thu, 20 Aug 2026 22:10:35 +0800
Subject: [PATCH] Ref2VA 加参考视频/URL 直填 + docs/todo/done 任务追踪目录

---
 CHANGELOG.md                                     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/README.md                                   | 20 ++++++++++++++++++++
 docs/done/h3-console-build-and-deploy.md         | 19 +++++++++++++++++++
 docs/done/h3-console-reliability-and-ux-fixes.md | 31 +++++++++++++++++++++++++++++++
 docs/todo/quality-tuning-plan.md                 | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/todo/verify-video-reference-on-gpu.md       | 40 ++++++++++++++++++++++++++++++++++++++++
 h3-console/server.py                             | 48 +++++++++++++++++++++++++++++++++++-------------
 h3-console/static/index.html                     | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------
 minimax-h3/api.py                                | 46 ++++++++++++++++++++++++++++++++++++++++++----
 9 files changed, 355 insertions(+), 34 deletions(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/done/h3-console-build-and-deploy.md
 create mode 100644 docs/done/h3-console-reliability-and-ux-fixes.md
 create mode 100644 docs/todo/quality-tuning-plan.md
 create mode 100644 docs/todo/verify-video-reference-on-gpu.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4896610..d063245 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,51 @@
 # 变更记录
 
+## 2026-08-20（夜，又续七）— Ref2VA 加参考视频/URL 直填，本地开发，⚠️ 没有 GPU 没测过
+
+**背景**：用户脱离了公司网络，只能靠 `qwen.wudaima.com/console` 这条公网线路访问服务器，
+SSH 和局域网直连都不通了。今晚在本地 Mac 上改代码，**明天回公司网络才能真正跑一次生成**
+验证——这条改动因此比之前几轮多一层风险：语法/接口层面本地能自测，但视频参考这条链路
+从没在真实 GPU + 真实模型上跑过。
+
+读了 https://docs.comfy.org/zh/tutorials/video/minimax/minimax-h3 对照现状，发现两件事：
+1. R2V（参考生视频）协议规格是最多 9 张参考图 + 3 段参考视频（各带自己的音轨）+ 3 段独立
+   音频，prompt 里用 `<Picture N>`/`<Video N>`/`<Audio N>` 标记引用；我们只做了参考图。
+2. 但实际跑模型的那层 pipeline（DiffSynth-Studio 的 `MiniMaxH3Pipeline`）本来就支持
+   `references` 列表里放 `{"type":"video","video":[...]}` / `{"type":"video_audio",...}` /
+   `{"type":"audio",...}`——**这是我们自己代码的封装没跟上，不用换模型**。
+
+**这次先做参考视频（图片已经支持多选，音频先不做，用户明确选的范围）**：
+
+- `minimax-h3/api.py`：`GenReq` 加 `reference_video_urls`（`max_length=3`，对应协议规格上限）。
+  `_references()` 从"只吐 image 类型"扩展成图片+视频都处理：视频先下载到临时文件（`read_video_audio`
+  只认本地路径），调 `diffsynth.utils.data.audio_video.read_video_audio()` 解码+对齐音轨，
+  读不到音轨（`waveform is None`）就退化成 `"video"`（静音）类型，读到了就用 `"video_audio"`
+  （pipeline 对这两种类型的字段要求不同，"video" 类型强制不能带 audio 字段，混用会报错）。
+  ⚠️ **`read_video_audio` 的 `height`/`width`/`num_frames` 参数我用的是输出视频自己的分辨率/
+  帧数**（跟 `_keyframes()` 处理首末帧的方式一致），这是没验证过的简单假设——pipeline 其实
+  另外暴露了 `ref_video_short_edge`/`ref_video_max_pixels` 两个参数专门做参考视频自己的归一化
+  （`worker()` 里已经按默认值传给 `pipe()` 了，只是从没真正生效过）。**明天上 GPU 如果参考
+  视频的运镜/动作锁不住，先怀疑这个 decode 分辨率选择，不是模型不支持。**
+- `h3-console/server.py`：`/v1/assets` 加视频类型支持（`.mp4/.mov/.webm`），上限从图片的
+  20MB 提到视频的 200MB；没有引入新的解码依赖（PyAV/opencv），改用轻量魔数校验（mp4/mov
+  是 `ftyp` box、webm 是 EBML 头）挡明显不是视频的文件，跟图片那边 `PIL.Image.verify()`
+  同样的"校验但不做重活"思路。响应里加了 `kind` 字段（`image`/`video`），前端不用再猜。
+- `h3-console/static/index.html`：参考图 tab 加"参考视频"多选上传框（最多3段，跟后端上限
+  一致）+ 一个"粘贴图片/视频 URL"输入框（按扩展名判断类型，不经过我们的上传接口，用户已经
+  有公网可访问的素材时省一次搬运）。图片/视频缩略图统一走一个 `appendThumb()` helper，
+  重跑（`prefillCreate`）和任务详情页的参考素材展示也跟着更新成图片+视频都渲染。
+
+**本地验证过的部分（不需要 GPU）**：`node --check` 过了 JS 语法；起本地 uvicorn 实测
+`/v1/assets`——合法图片/合法 magic-byte 的 mp4 都能传上去且 `kind` 字段正确，改了后缀但内容
+不是视频的文件、完全不支持的扩展名都正确 400。页面渲染正常，新增的 DOM 元素都在。
+
+**完全没验证过的部分**：`_references()` 里视频这段代码、`read_video_audio` 的调用方式、
+"video"/"video_audio" 类型选择的分支逻辑——本地没有 GPU 也没有装 DiffSynth-Studio，纯靠读
+源码（`diffsynth/pipelines/minimax_h3_audio_video.py`、`diffsynth/utils/data/audio_video.py`
+的函数签名和注释）写的，**明天部署到服务器后第一件事应该是拿一段真实参考视频端到端跑一次**。
+
+---
+
 ## 2026-08-20（夜，又续六）— 下载文件名统一叫 file.mp4 的问题
 
 **背景**：用户发现下载多个任务的视频，文件名都叫 `file.mp4`——存到同一个下载目录会互相
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..d6091a4
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,20 @@
+# docs 索引
+
+按状态分两个目录：一件事没做完在 `todo/`，做完验证过了挪到 `done/`（`mv` 过去，不是复制）。
+每份文档自己保持简短，完整的踩坑记录/实测数据以顶层 `CHANGELOG.md` 为准，这里的文件只做
+索引和"现在该干什么"的摘要，不重复 CHANGELOG 已经写过的细节。
+
+## todo
+
+- [verify-video-reference-on-gpu.md](todo/verify-video-reference-on-gpu.md) — Ref2VA 新加的
+  参考视频功能（2026-08-20 本地写的，没有 GPU 没测过），明天回服务器第一件事要验证
+- [quality-tuning-plan.md](todo/quality-tuning-plan.md) — 为什么生成视频画质比 ComfyUI 官方
+  演示差很多：分辨率/Turbo步数/CFG/negative prompt 几个待实测方向，按优先级排好了
+
+## done
+
+- [h3-console-build-and-deploy.md](done/h3-console-build-and-deploy.md) — h3-console 从零
+  构建到部署上线，公网访问改走 `qwen.wudaima.com/console`
+- [h3-console-reliability-and-ux-fixes.md](done/h3-console-reliability-and-ux-fixes.md) —
+  上线后的一系列可靠性修复（假运行中、并发竞态、任务落盘、下载文件名）+ 常用功能（重跑、
+  回收站、rows 动态帧数校验）
diff --git a/docs/done/h3-console-build-and-deploy.md b/docs/done/h3-console-build-and-deploy.md
new file mode 100644
index 0000000..9ef8714
--- /dev/null
+++ b/docs/done/h3-console-build-and-deploy.md
@@ -0,0 +1,19 @@
+# h3-console：从零构建到公网可访问
+
+**完成时间**：2026-08-20。
+
+给 `minimax-h3/` 的四后端 API（`gateway.py` + 4× `api.py`）加了一层 Web 管理台：三个 tab
+（文生视频 T2V / 首尾帧 I2V / 参考图 R2V）+ 上传 + 任务列表 + fl2va/ref2va 弹性调度器。
+
+- 部署在服务器 `/data/models/minimax-h3/console/`，两个进程共享同一份数据库/图片目录：
+  局域网 `:8080`（开弹性调度器）+ 公网子路径专用 `:8081`（不开调度器，避免两个调度器互抢）。
+- 公网访问：`http://qwen.wudaima.com/console`。原计划用独立域名 `gateway.wudaima.com`，实测
+  确认这条线路走不通（缺口在 frp 服务端 `60.205.214.169`，不是这台机器能改的），改走
+  `qwen.wudaima.com` 的 `/console` 子路径，frp 按 `locations` 做路径分流，不影响原有服务。
+- 弹性调度器（kill+restart 某张 GPU 卡切 fl2va/ref2va）全链路在真实 GPU 上验证过：提交任务 →
+  没有对应分区的空闲后端时先排队而不是直接 503 → supervisor 探测到需求后自动 flip 一张卡 →
+  新后端 ready 后自动把排队任务提交上去 → 跑完 → 下载。
+
+完整过程、踩过的坑（PID 提取正则写错、调度器连续 flip 好几张卡、`pkill -f` 误杀自己的 SSH
+会话等）见顶层 `CHANGELOG.md` 里 2026-08-20「h3-console 部署上线」「新增 h3-console 管理台」
+「公网访问改走 qwen.wudaima.com/console 子路径」这几节，以及 `h3-console/README.md`。
diff --git a/docs/done/h3-console-reliability-and-ux-fixes.md b/docs/done/h3-console-reliability-and-ux-fixes.md
new file mode 100644
index 0000000..eac8590
--- /dev/null
+++ b/docs/done/h3-console-reliability-and-ux-fixes.md
@@ -0,0 +1,31 @@
+# h3-console：可靠性修复 + 常用功能补齐
+
+**完成时间**：2026-08-20，部署上线之后的一系列迭代（均已部署并验证）。
+
+## 可靠性修复
+
+- **任务卡在假"运行中"**：所在后端进程被重启（弹性调度器 flip 分区）后，gateway 会 404，
+  但 console 原来遇到非 200 一律静默跳过、保留上次已知状态，导致 status 永远停在
+  `running`。改成 404 时直接判 `failed` 并写清原因。
+- **并发提交竞态**：`create_video()` 首次提交、轮询时顺手提交、后台对账循环每 5 秒扫描，
+  三条路都可能在同一个任务还没拿到 `gateway_id` 的窗口里并发提交给 gateway，导致同一条
+  任务在两张卡上各烧一遍 GPU。加了进程内的提交占坑集合堵住这个窗口。
+- **`api.py` 任务记录改成落盘**：原来只在内存里，弹性调度器 kill+restart 某张卡是常规操作
+  （不是稀有事件），进程重启就把内存里的任务记录清空。改成每次状态变化都往 sqlite 写一份，
+  进程重启后能读回来。
+- **下载文件名统一叫 `file.mp4`**：下载接口没设 `Content-Disposition`，浏览器只能从 URL
+  （以 `/file` 结尾，没扩展名）猜文件名。加上 `filename="h3-{任务id}.mp4"`。
+
+## 常用功能
+
+- **重跑按钮**：详情页加「重跑」，把当初的参数/上传素材灌回新建任务表单，用户确认无误后
+  自己点提交——不是静默后台重新提交（第一版是静默提交，用户反馈后改成回填表单）。
+- **软删除/回收站**：任务列表加「⋯」菜单删除、左下角加回收站入口带恢复，不碰 gateway/api.py
+  上的任务本身。
+- **后端状态行补上 running/queued**：之前明明有任务在跑也只显示 `ok`，看不出哪张卡忙。
+- **frames 上限改按 rows（分辨率×帧数）动态判定**：原来硬编码 124，跟分辨率无关一刀切，
+  改成按显存安全线动态判定，448×256/576×320 这些低分辨率档能跑到 362 帧（15秒）。
+- **任务详情页加显式"时长"字段**：原来只显示帧数，用户得自己心算除以 24fps。
+
+完整排查过程和实测数据见顶层 `CHANGELOG.md` 对应日期的各节（标题里能直接搜到，比如
+「修复 console 任务提交竞态」「api.py 任务记录改成落盘」「下载文件名统一叫 file.mp4」）。
diff --git a/docs/todo/quality-tuning-plan.md b/docs/todo/quality-tuning-plan.md
new file mode 100644
index 0000000..cd0a3c6
--- /dev/null
+++ b/docs/todo/quality-tuning-plan.md
@@ -0,0 +1,53 @@
+# 画质改进方案：为什么我们的视频比 ComfyUI 文档演示的差很多
+
+**背景**：对照 https://docs.comfy.org/zh/tutorials/video/minimax/minimax-h3 （官方 ComfyUI
+工作流文档）跟我们现在的 `api.py`/`t2va.py`/console 默认参数，找出的差距，按影响力排序。
+都还没动手实测，需要真实 GPU，明天回服务器再做。
+
+## 1. 分辨率——大概率是最大的差距
+
+H3 原生分辨率是 1344×768（短边 768px）。我们线上默认 **832×480**，只有原生像素量的约 40%。
+真实上限被 `api.py` 的 `ROWS_LIMIT=20000`（帧数×宽×高的显存安全线）卡死——这是 Turing 显卡
+fp32-only（无高效 bf16/fp16 attention）导致的显存代价，不是随手设的参数。
+
+**要做的实测**：在服务器上直接跑一次接近原生的分辨率（比如 1344×768，短时长/低帧数控制
+rows 不超限），跟现在的 832×480 默认档同 prompt/seed 对比，看画质差距有多大、显存/耗时代价
+多大。`ROWS_LIMIT` 支持 `H3_ROWS_LIMIT` 环境变量临时覆盖，不用改代码就能测。
+
+## 2. Turbo 4 步 vs 关闭 Turbo 跑 20+ 步——现成的开关，从没系统测过
+
+文档里 T2V/I2V 用的是 8 步蒸馏 LoRA，我们下载的两个 LoRA 文件名都写死是 `turbo_4step`
+（`fl2va`/`ref2va` 各一个）。不用换文件就能验证的路径：console 早就支持关掉 Turbo、跑 20/50
+步全精度（`turbo=false`），但**默认值是"Turbo 开/4步"**（为了速度），从没系统对比过画质。
+
+**要做的实测**：同 prompt/seed，Turbo 开(4步) vs 关(20步) 各跑一条，对比帧间差异/音频响度/
+肉眼观感。之前在纯文生视频上测过一次类似的（结论是步数越多帧间差异越小、音质越好，见
+`CHANGELOG.md` 「15 秒时长实测」一节），但没有在现在的默认分辨率/R2V 场景下重新验证过。
+
+## 3. CFG scale / negative prompt——完全没调过
+
+pipeline 本身支持 `cfg_scale`（默认 1.0，等于没有 CFG 引导）和 `negative_prompt`（默认空
+字符串），我们的 `api.py`/`t2va.py` 从来没传过这两个参数，一直骑着默认值裸跑。ComfyUI 文档
+没有明确给出推荐值（蒸馏模型常见把 guidance 焙进 LoRA 里，不一定需要开 CFG），这是一个完全
+没做过 A/B 的空白。
+
+**要做的实测**：先确认默认值是不是真的最优——`cfg_scale` 调到 2-3 试试是否画质提升，同时看
+是否会因为蒸馏 LoRA 的缘故反而变差（过度引导在蒸馏模型上有时会出伪影）。`negative_prompt`
+可以先加几个常见负面词（模糊、抖动、变形）试试。
+
+## 4. audio_flow_shift——同样裸跑默认值
+
+`audio_flow_shift` 默认 3.0，从没被覆盖过，音频质量没调过。跟 `flow_shift`（视频的）性质
+类似，值得跟着上面的实测一起做个粗调。
+
+## 5. 8 步 Turbo LoRA——需要下载新文件，不是参数调整
+
+文档里 T2V/I2V 用的是 8 步蒸馏 LoRA，我们只有 4 步版。如果第 2 项（关 Turbo 跑 20+ 步）验证
+画质确实好很多、但耗时代价太高，可以考虑换一个 8 步版 LoRA 做折中——**这个需要先找到/下载
+对应的模型文件，不是改个参数就行**，工作量和网络下载时间都要单独评估（服务器出口带宽约
+5.9MB/s，见顶层 `CLAUDE.md`「硬件的三条硬限制」）。
+
+## 建议的实测顺序
+
+1 和 2 不需要下载任何新文件、不需要改代码，最快能出结果，优先做。3、4 需要小改 `api.py`
+把这两个参数串上（目前完全没有入口）。5 最后再看要不要投入。
diff --git a/docs/todo/verify-video-reference-on-gpu.md b/docs/todo/verify-video-reference-on-gpu.md
new file mode 100644
index 0000000..7e24308
--- /dev/null
+++ b/docs/todo/verify-video-reference-on-gpu.md
@@ -0,0 +1,40 @@
+# 验证：参考视频（Ref2VA video reference）端到端跑通
+
+**状态**：代码已写完（2026-08-20 夜），**完全没有在真实 GPU 上跑过**。本地 Mac 开发机没有卡，
+也没装 DiffSynth-Studio，`_references()` 里视频这段是纯读 pipeline 源码写的，语法和上传校验
+本地测过，生成效果没测过。
+
+## 改了什么
+
+- `minimax-h3/api.py`：`GenReq` 加 `reference_video_urls`（最多 3 段）。`_references()` 把参考
+  视频下载到临时文件，调 `diffsynth.utils.data.audio_video.read_video_audio()` 解码+对齐音轨，
+  读不到音轨就用 `"video"`（静音）类型，读到了用 `"video_audio"` 类型。
+- `h3-console/server.py`：`/v1/assets` 加 mp4/mov/webm 支持，200MB 上限，轻量魔数校验。
+- `h3-console/static/index.html`：参考图 tab 加视频多选上传 + URL 直填两条路径。
+
+## ⚠️ 最大的不确定性：视频解码分辨率的选择
+
+`read_video_audio(path, height, width, num_frames, fps=24)` 的 `height`/`width`/`num_frames`
+现在传的是**输出视频自己的分辨率和帧数**（跟 `_keyframes()` 处理首末帧图片的方式一致）。这是
+没验证过的简单假设——pipeline 其实另外暴露了 `ref_video_short_edge`/`ref_video_max_pixels`
+两个参数，专门用来做参考视频自己的归一化（`worker()` 里已经按默认值传给 `pipe()` 了，只是从
+没真正生效过，因为这条链路从没跑过）。
+
+## 验证步骤
+
+1. 部署到服务器（`server.py`/`api.py` 都要重启，跟着 README 的安全重启法：`ss` 按端口找 PID
+   kill，不要 `pkill -f`；重启前确认 `/v1/backends` 四张卡都空闲）。
+2. 找一段几秒钟的短视频（比如已有的某条历史生成产物），通过 h3-console 的参考图 tab 上传，
+   提交一个 R2V 任务。
+3. 确认任务能跑完（不是在 `_references()` 这步就报错——先验证代码本身没有语法/接口层面的
+   bug，这一步失败大概率是 `read_video_audio`/pipeline 调用姿势不对）。
+4. 跑完了看输出：参考视频里的角色/风格/运镜是不是真的被锁住了。如果锁不住（生成结果跟没给
+   参考视频差不多），先怀疑上面那条"解码分辨率假设"，试试把 `read_video_audio` 的
+   `height`/`width` 换成按 `ref_video_short_edge` 算出来的值,而不是输出分辨率。
+5. 如果视频带音轨，确认走的是 `"video_audio"` 分支，产出的音频里能听出参考视频的声音特征
+   （不是纯粹被输出侧的文本/音频生成盖过去）。
+
+## 参考
+
+代码和排查思路的完整记录见顶层 `CHANGELOG.md`「2026-08-20（夜，又续七）— Ref2VA 加参考视频/
+URL 直填，本地开发，⚠️ 没有 GPU 没测过」。
diff --git a/h3-console/server.py b/h3-console/server.py
index e4a2647..b222429 100644
--- a/h3-console/server.py
+++ b/h3-console/server.py
@@ -83,26 +83,48 @@ init_db()
 
 
 # ---------------- 资产上传 ----------------
-# api.py 的 GenReq 只认 URL 字段（first_frame_url / reference_image_urls），内部用
-# urllib.urlopen 拉取。所以上传接口的活是「收文件 -> 落盘 -> 吐一个后端能拉到的 URL」，
-# 不改 api.py 一行代码。
+# api.py 的 GenReq 只认 URL 字段（first_frame_url / reference_image_urls /
+# reference_video_urls），内部用 urllib.urlopen 拉取。所以上传接口的活是「收文件 -> 落盘 ->
+# 吐一个后端能拉到的 URL」，不改 api.py 生成逻辑一行代码。
+IMAGE_EXTS = (".jpg", ".jpeg", ".png", ".webp")
+VIDEO_EXTS = (".mp4", ".mov", ".webm")
+MAX_VIDEO_BYTES = 200 * 1024 * 1024  # 参考视频比参考图重得多，20MB 装不下几秒钟的片段
+
+# 轻量魔数校验，不是完整格式解析——只为挡住"随便改个后缀的非视频文件"。mp4/mov 都是 ISO
+# base media 容器，前 12 字节里第 4-7 位是 "ftyp"；webm 是 EBML 容器，固定以这 4 字节开头。
+# 没有为此新引入解码依赖（PyAV/opencv），跟这个 venv 里其它依赖保持一致地轻。
+def _looks_like_video(head: bytes, ext: str) -> bool:
+    if ext == ".webm":
+        return head[:4] == b"\x1a\x45\xdf\xa3"
+    return len(head) >= 12 and head[4:8] == b"ftyp"  # .mp4 / .mov
+
+
 @router.post("/v1/assets")
 async def upload_asset(file: UploadFile = File(...)):
     ext = Path(file.filename or "").suffix.lower()
-    if ext not in (".jpg", ".jpeg", ".png", ".webp"):
-        raise HTTPException(400, f"不支持的文件类型 {ext}，只收图片(jpg/png/webp)")
+    is_video = ext in VIDEO_EXTS
+    if not is_video and ext not in IMAGE_EXTS:
+        raise HTTPException(
+            400, f"不支持的文件类型 {ext}，只收图片({'/'.join(e[1:] for e in IMAGE_EXTS)})"
+                 f"或视频({'/'.join(e[1:] for e in VIDEO_EXTS)})")
     body = await file.read()
-    if len(body) > MAX_UPLOAD_BYTES:
-        raise HTTPException(413, f"文件超过 {MAX_UPLOAD_BYTES // 1024 // 1024}MB 上限")
+    limit = MAX_VIDEO_BYTES if is_video else MAX_UPLOAD_BYTES
+    if len(body) > limit:
+        raise HTTPException(413, f"文件超过 {limit // 1024 // 1024}MB 上限")
     aid = uuid.uuid4().hex[:16]
     path = ASSETS / f"{aid}{ext}"
     path.write_bytes(body)
-    try:
-        Image.open(path).verify()  # 校验确实是能解码的图片，不是随便什么二进制
-    except Exception:
-        path.unlink(missing_ok=True)
-        raise HTTPException(400, "文件不是有效图片")
-    return {"id": aid, "url": f"{_public_base()}/assets/{aid}{ext}"}
+    if is_video:
+        if not _looks_like_video(body[:16], ext):
+            path.unlink(missing_ok=True)
+            raise HTTPException(400, "文件不是有效视频")
+    else:
+        try:
+            Image.open(path).verify()  # 校验确实是能解码的图片，不是随便什么二进制
+        except Exception:
+            path.unlink(missing_ok=True)
+            raise HTTPException(400, "文件不是有效图片")
+    return {"id": aid, "url": f"{_public_base()}/assets/{aid}{ext}", "kind": "video" if is_video else "image"}
 
 
 def _public_base() -> str:
diff --git a/h3-console/static/index.html b/h3-console/static/index.html
index 9963d51..0eff27d 100644
--- a/h3-console/static/index.html
+++ b/h3-console/static/index.html
@@ -49,7 +49,7 @@
   button.submit:disabled { opacity: .5; cursor: default; }
   .hint { font-size: 12px; opacity: .65; margin: 6px 0 4px; line-height: 1.5; }
   .thumbrow { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 6px; }
-  .thumbrow img { height: 60px; border-radius: 4px; }
+  .thumbrow img, .thumbrow video { height: 60px; border-radius: 4px; }
   .status-done { color: #2a7; } .status-failed { color: #c33; } .status-running { color: #a70; } .status-queued { color: #777; }
   .err { color: #c33; font-size: 13px; margin-top: 8px; }
 
@@ -148,8 +148,17 @@
     <label>Prompt</label>
     <textarea id="ref2va-prompt" rows="10" placeholder="..."></textarea>
     <label>参考图（可多选，没有张数上限，越多序列越长越慢）</label>
-    <input id="ref2va-refs" type="file" accept="image/*" multiple onchange="uploadMulti()">
+    <input id="ref2va-refs" type="file" accept="image/*" multiple onchange="uploadMulti('ref2va-refs','image')">
     <div class="thumbrow" id="ref2va-thumbs"></div>
+    <label>参考视频（可多选，最多 3 段，会带上视频自己的声音；协议规格上限，不是随便定的）</label>
+    <input id="ref2va-videos" type="file" accept="video/*" multiple onchange="uploadMulti('ref2va-videos','video')">
+    <div class="thumbrow" id="ref2va-video-thumbs"></div>
+    <label>或直接粘贴已经在别处的图片/视频 URL（不经过我们的上传，省一次搬运）</label>
+    <div class="row">
+      <div><input id="ref2va-url-input" type="text" placeholder="https://.../xxx.jpg 或 .mp4"></div>
+      <div style="flex:0"><button type="button" class="submit" style="margin-top:0" onclick="addRefUrl()">添加</button></div>
+    </div>
+    <div class="err" id="ref2va-url-err"></div>
     <div class="row">
       <div><label>分辨率</label><select id="ref2va-res" class="res-select"></select></div>
       <div><label>时长</label><select id="ref2va-dur" class="dur-select"></select></div>
@@ -182,7 +191,7 @@
 // 否则子路径部署时请求会打到域名根路径，而不是我们这个子路径。
 const H3_BASE = "__H3_BASE_PATH__";
 
-const uploaded = { 'fl2va-first': null, 'fl2va-last': null, 'ref2va-refs': [] };
+const uploaded = { 'fl2va-first': null, 'fl2va-last': null, 'ref2va-refs': [], 'ref2va-videos': [] };
 let jobsCache = [];
 let trashCache = [];
 let viewingTrash = false;
@@ -290,29 +299,61 @@ async function uploadFile(file) {
   return await r.json();
 }
 
+// 图片用 <img>、视频用 <video controls muted>——缩略图这一层不区分是上传来的还是直接粘贴
+// URL 来的，两条路径（uploadMulti/addRefUrl）都调这个函数，视觉上完全一致。
+function appendThumb(container, url, kind) {
+  const el = kind === 'video' ? document.createElement('video') : document.createElement('img');
+  el.src = url;
+  if (kind === 'video') { el.controls = true; el.muted = true; }
+  container.appendChild(el);
+}
+
 async function uploadTo(inputId) {
   const el = document.getElementById(inputId);
   if (!el.files[0]) return;
   try {
     const res = await uploadFile(el.files[0]);
     uploaded[inputId] = res.url;
-    const thumbs = document.getElementById('fl2va-thumbs');
-    const img = document.createElement('img'); img.src = res.url; thumbs.appendChild(img);
+    appendThumb(document.getElementById('fl2va-thumbs'), res.url, 'image');
   } catch (e) { document.getElementById('fl2va-err').textContent = '上传失败: ' + e.message; }
 }
 
-async function uploadMulti() {
-  const el = document.getElementById('ref2va-refs');
-  const thumbs = document.getElementById('ref2va-thumbs');
+// kind 是 'image' 或 'video'，两个上传框（参考图/参考视频）共用这一个函数，
+// 只是目标数组、缩略图容器、期望的文件类型不同。
+async function uploadMulti(inputId, kind) {
+  const el = document.getElementById(inputId);
+  const thumbs = document.getElementById(kind === 'video' ? 'ref2va-video-thumbs' : 'ref2va-thumbs');
   for (const f of el.files) {
     try {
       const res = await uploadFile(f);
-      uploaded['ref2va-refs'].push(res.url);
-      const img = document.createElement('img'); img.src = res.url; thumbs.appendChild(img);
+      uploaded[inputId].push(res.url);
+      appendThumb(thumbs, res.url, kind);
     } catch (e) { document.getElementById('ref2va-err').textContent = '上传失败: ' + e.message; }
   }
 }
 
+// "粘贴 URL" 这条路径不经过我们的 /v1/assets——用户已经有一个别处能公网访问的图片/视频链接时，
+// 没必要先下载再上传再吐 URL 绕一圈。按扩展名判断图片还是视频，判断不出来就报错，不瞎猜。
+function addRefUrl() {
+  const input = document.getElementById('ref2va-url-input');
+  const errBox = document.getElementById('ref2va-url-err');
+  errBox.textContent = '';
+  const url = input.value.trim();
+  if (!url) return;
+  const bare = url.split('?')[0].split('#')[0].toLowerCase();
+  if (/\.(mp4|mov|webm)$/.test(bare)) {
+    uploaded['ref2va-videos'].push(url);
+    appendThumb(document.getElementById('ref2va-video-thumbs'), url, 'video');
+  } else if (/\.(jpg|jpeg|png|webp)$/.test(bare)) {
+    uploaded['ref2va-refs'].push(url);
+    appendThumb(document.getElementById('ref2va-thumbs'), url, 'image');
+  } else {
+    errBox.textContent = '看不出是图片还是视频——URL 需要以 .jpg/.png/.webp 或 .mp4/.mov/.webm 结尾';
+    return;
+  }
+  input.value = '';
+}
+
 // 分辨率/时长/Turbo/步数/Seed 五个字段，三个 tab 结构完全一样，抽出来一份读取逻辑。
 function readParamSelects(prefix) {
   const res = RESOLUTIONS.find(r => r.value === document.getElementById(prefix + '-res').value);
@@ -340,10 +381,13 @@ async function submitJob(kind) {
       ...readParamSelects('fl2va'),
     };
   } else if (kind === 'ref2va') {
-    if (uploaded['ref2va-refs'].length === 0) { errBox.textContent = '请先上传至少一张参考图'; return; }
+    if (uploaded['ref2va-refs'].length === 0 && uploaded['ref2va-videos'].length === 0) {
+      errBox.textContent = '请先上传至少一张参考图或一段参考视频'; return;
+    }
     body = {
       prompt: document.getElementById('ref2va-prompt').value,
       reference_image_urls: uploaded['ref2va-refs'],
+      reference_video_urls: uploaded['ref2va-videos'],
       ...readParamSelects('ref2va'),
     };
   }
@@ -360,14 +404,14 @@ async function submitJob(kind) {
 // 重跑：不直接提交，而是把这条任务当初的 req 灌回"新建任务"表单（对应的 tab、参数、
 // 已上传的图片 URL 都原样带过去），跳到 /newtask.html，用户看一眼确认无误后自己点提交——
 // 跟正常新建任务走的是同一条路径、同一次人工确认，不是绕过表单直接后台再发一次请求。
-function setThumbs(elId, urls) {
+function setThumbs(elId, urls, kind = 'image') {
   const box = document.getElementById(elId); box.innerHTML = '';
-  urls.forEach(u => { if (!u) return; const img = document.createElement('img'); img.src = u; box.appendChild(img); });
+  urls.forEach(u => { if (u) appendThumb(box, u, kind); });
 }
 
 function prefillCreate(req) {
   const kind = (req.first_frame_url || req.last_frame_url) ? 'fl2va'
-    : (req.reference_image_urls || []).length ? 'ref2va' : 'text';
+    : ((req.reference_image_urls || []).length || (req.reference_video_urls || []).length) ? 'ref2va' : 'text';
 
   document.querySelectorAll('.tabs button').forEach(b => b.classList.toggle('active', b.dataset.tab === kind));
   ['text', 'fl2va', 'ref2va'].forEach(t => document.getElementById('tab-' + t).style.display = (t === kind ? 'block' : 'none'));
@@ -404,7 +448,9 @@ function prefillCreate(req) {
     setThumbs('fl2va-thumbs', [req.first_frame_url, req.last_frame_url]);
   } else if (kind === 'ref2va') {
     uploaded['ref2va-refs'] = (req.reference_image_urls || []).slice();
-    setThumbs('ref2va-thumbs', uploaded['ref2va-refs']);
+    uploaded['ref2va-videos'] = (req.reference_video_urls || []).slice();
+    setThumbs('ref2va-thumbs', uploaded['ref2va-refs'], 'image');
+    setThumbs('ref2va-video-thumbs', uploaded['ref2va-videos'], 'video');
   }
 
   showCreate();
@@ -579,11 +625,17 @@ async function refreshDetail() {
     }
 
     let refThumbs = '';
-    const imgs = [];
+    const imgs = [], vids = [];
     if (req.first_frame_url) imgs.push(['首帧', req.first_frame_url]);
     if (req.last_frame_url) imgs.push(['尾帧', req.last_frame_url]);
     (req.reference_image_urls || []).forEach((u, i) => imgs.push(['参考图'+(i+1), u]));
-    if (imgs.length) refThumbs = `<div class="thumbrow">${imgs.map(([label,u]) => `<img src="${u}" title="${label}">`).join('')}</div>`;
+    (req.reference_video_urls || []).forEach((u, i) => vids.push(['参考视频'+(i+1), u]));
+    if (imgs.length || vids.length) {
+      refThumbs = `<div class="thumbrow">`
+        + imgs.map(([label,u]) => `<img src="${u}" title="${label}">`).join('')
+        + vids.map(([label,u]) => `<video src="${u}" title="${label}" controls muted></video>`).join('')
+        + `</div>`;
+    }
 
     box.innerHTML = `
       <div class="back" onclick="showCreate()">← 新建任务</div>
diff --git a/minimax-h3/api.py b/minimax-h3/api.py
index a54c852..6210ffc 100644
--- a/minimax-h3/api.py
+++ b/minimax-h3/api.py
@@ -67,6 +67,10 @@ class GenReq(BaseModel):
     # 短边 480 时约 390 行，而目标视频本身才 14430 行。
     reference_image_urls: list[str] = []
     ref_image_short_edge: int = Field(480, ge=64, le=2048)
+    # 参考视频（Ref2VA 的第二种引用类型）。2026-08-20 新加，本地开发机没有 GPU，还没在真实
+    # 模型上跑过一次——pipeline 层的 references 协议支持 "video"/"video_audio" 两种（帧列表
+    # +可选音轨），细节见 _references()。上限 3 段是文档写的 R2V 协议规格，不是这里随便定的。
+    reference_video_urls: list[str] = Field(default_factory=list, max_length=3)
 
     @model_validator(mode="after")
     def _check_rows(self):
@@ -200,11 +204,45 @@ def _keyframes(req):
         indices.append(index)
     return (images, indices) if images else (None, None)
 
+def _fetch_to_tmp(url: str, suffix: str) -> str:
+    """视频不像图片那样能直接从内存 bytes 解码——PyAV 要能 seek 的文件，最简单的办法是
+    先落一份临时文件再读，读完调用方自己删。"""
+    import tempfile
+    fd, path = tempfile.mkstemp(suffix=suffix)
+    with os.fdopen(fd, "wb") as f, urllib.request.urlopen(url, timeout=120) as resp:
+        f.write(resp.read())
+    return path
+
 def _references(req):
-    """参考图按请求顺序取下来。尺寸交给 pipeline 按 ref_image_short_edge 归一，这里不动。"""
-    if not req.reference_image_urls:
-        return None
-    return [{"type": "image", "image": _fetch_image(url)} for url in req.reference_image_urls]
+    """参考图/参考视频按请求顺序取下来拼成 pipeline 要的 references 列表。
+
+    图片这段是原来就有的：尺寸交给 pipeline 按 ref_image_short_edge 归一，这里不resize。
+
+    视频这段是 2026-08-20 新加的，⚠️ 本地开发机没有 GPU，从没在真实模型上跑过一次——
+    height/width 用 req 的输出分辨率、num_frames 用 req.frames，是"参考视频≈目标视频
+    同尺寸同时长"这个简单假设，不是从官方文档验证过的最优值。pipeline 其实另外单独暴露了
+    ref_video_short_edge/ref_video_max_pixels 两个参数用来做参考视频自己的归一化（在
+    worker() 的 pipe() 调用里已经按默认值传了），如果真机测试发现参考视频的运镜/动作锁不住，
+    先怀疑这里的 decode 分辨率选择，不是模型不支持。
+    有无音轨（read_video_audio 读不到音轨时返回 None）决定 type 是 "video" 还是
+    "video_audio"——pipeline 对 "video" 类型强制要求不能带 audio 字段，两者不能混用。
+    """
+    refs = [{"type": "image", "image": _fetch_image(url)} for url in req.reference_image_urls]
+    if req.reference_video_urls:
+        from diffsynth.utils.data.audio_video import read_video_audio
+        for url in req.reference_video_urls:
+            ext = os.path.splitext(url.split("?")[0])[1] or ".mp4"
+            path = _fetch_to_tmp(url, ext)
+            try:
+                frames, audio, sr = read_video_audio(path, height=req.height, width=req.width,
+                                                      num_frames=req.frames, fps=24)
+                if audio is not None:
+                    refs.append({"type": "video_audio", "video": frames, "audio": audio, "sample_rate": sr})
+                else:
+                    refs.append({"type": "video", "video": frames})
+            finally:
+                os.unlink(path)
+    return refs or None
 
 def worker():
     from diffsynth.utils.data.audio_video import write_video_audio
--
libgit2 0.21.4