视频抽卡与版本切换
2026-10 更新:旧版项目/章节/分镜页面已退役,相关页面名仅用于解释历史设计。 当前入口统一为 V2 树状工作台,见 树状工作台 与 旧页面退役清单。
本文属于“当前架构”文档,描述当前已经生效的视频版本管理机制。
要解决的问题
视频生成是抽卡:同一条提示词多跑几次,挑一张最好的。但早期实现里,每次生成都直接覆写 shots.generated_video_file_id,上一条结果没有任何入口可以找回来——用户点错一次就永久丢失上一版。
现在改为:每次生成都留档,当前使用哪一版是一个可切换的指针。
数据模型
版本信息不新增表,直接复用既有的任务链路表:
generation_task_links:resource_type = 'video'、relation_type = 'video'、relation_entity_id = shot_id,file_id指向产物文件。generation_tasks:task_kind = 'video_generation',payload里带本次生成的参数。
对应常量定义在 backend/app/services/studio/shot_video_versions.py:
VIDEO_RESOURCE_TYPE = "video"
VIDEO_RELATION_TYPE = "video"
VIDEO_TASK_KIND = "video_generation"“当前版本”不是额外字段,而是派生出来的:
is_current = (task_link.file_id == shot.generated_video_file_id)因此不存在两份状态需要同步,也不会出现“指针和版本表不一致”。
服务层
async def list_shot_video_versions(db, *, shot_id: str) -> list[ShotVideoVersionRead]
async def adopt_shot_video_version(db, *, shot_id: str, file_id: str) -> Shotlist_shot_video_versions:
- 用
select(GenerationTaskLink, GenerationTask).join(...)过滤resource_type/relation_type/relation_entity_id/task_kind,避免把别的资源或其他类型的任务混进来。 - 排序
order_by(GenerationTask.created_at.desc(), GenerationTask.id.desc())——加id是为了在created_at相同时仍有稳定顺序。 - 镜头不存在时抛
ValueError(entity_not_found("Shot")),由全局 handler 转 404。 - 从
payload.run_args.input还原model/ratio/prompt/seconds;prompt优先取input.prompt,失败任务回落run_args.prompt_preview.prompt,并带上error。
adopt_shot_video_version:
- 只写
shot.generated_video_file_id = target然后flush()。 - 不删除任何历史版本。
- 会校验
file_id确实属于该镜头,否则ValueError("file_id is not a generated video version of this shot");空白file_id抛ValueError("file_id is required")。
接口
GET /api/v1/studio/shots/{shot_id}/video-versions -> ApiResponse[list[ShotVideoVersionRead]]
POST /api/v1/studio/shots/{shot_id}/video-versions/adopt -> ApiResponse[ShotRead]ShotVideoVersionRead:
| 字段 | 说明 |
|---|---|
task_id | 任务 id |
file_id | 产物文件 id,失败时为 null |
status | 任务状态 |
is_current | 是否是当前采用的版本 |
ratio / seconds | 本次生成参数 |
prompt | 本次使用的提示词 |
error | 失败原因 |
created_at | 生成时间 |
ShotVideoVersionAdoptRequest 只有 file_id 一个字段。
前端交互
视频版本与抽卡审核在 V2 镜头面板的 VideoReviewPanel 中:
- 列出该镜头全部视频版本,保留失败原因与参考数量;
- 满意/不满意标签与备注写回
shot_video_reviews; - 采纳旧版本只移动当前指针,历史文件不删除;
- 重新生成仍需重新预览输入,不复用旧页面的
lastVideoSubmit临时状态。
「视频版本(抽卡历史)」列表按时间倒序展示每次生成:可播放的版本给视频预览与下载,非当前版本给「采用」按钮,当前版本显示「当前」标签。采用后:
- 调 adopt 接口切指针;
- 更新右侧预览;
- 重新拉取版本列表;
- 通过
onRefreshShots回调刷新分镜列表,让selectedShot.generated_video_file_id与后端一致。
最后一步是必要的:如果不回刷,界面上“当前版本”的高亮会停留在旧值。
为什么不做画布式
需求明确要求参考版本保留与替换的能力,但不要画布式交互。理由是画布(节点图)会引入一套并行的布局、连线与状态模型,而这里的真实诉求只有两点:
- 历史不丢;
- 一键换用。
用“任务链路即版本记录 + 一个可切换指针”就能满足,代价是零新增表、零新增状态同步点。界面形态保持为列表 + 「采用」,与现有的分镜工作台一致。