H3 多参考 Manifest 与生成输入快照
本文属于“当前架构”,描述 P6 / C11 已落地的实现。
1. 核心原则
预览与真实提交必须使用同一份:
ShotAssetVersion
→ ShotReferenceBinding(有序 manifest)
→ IR references / Subject-Picture 编号
→ 最终 H3 Prompt
→ Generation Input Snapshot
→ GenerationTask run_args任何一步重新自动推荐或读取“最新版本”都会破坏一致性,因此 P6 正式路径使用显式 manifest,而不是旧 IR 的自动资产收集。
2. 数据模型
shot_reference_bindings
shot_idfile_id(FileItem)asset_type/asset_id/asset_version_idreference_role:角色身份/造型、场景、道具、服装、镜头构图、上一镜source:auto / manual / uploadedsort_orderis_pinnedis_active
同一镜头同一文件唯一;删除参考图是 is_active=false,不是物理删除历史绑定。
shot_prompt_references
保存自然语言提示词中的 @ 引用:
- 资产类型/ID/版本
- 原始 mention
- 字符区间
shot_generation_snapshots
不可变生成输入:
- 镜头/项目/章节/场次
- 模型/供应商
- manifest(文件、资产、版本、角色、顺序)
- 最终 prompt / 自然语言 prompt / 高级 prompt
- @ 引用
- 音频参考(file_id、说话人、标签)
- 镜头资产版本
- 比例、分辨率、时长、input_hash
3. 自动推荐
优先读取 P5 shot_asset_versions:
- 角色身份版本;
- 角色当前造型;
- 场景;
- 道具;
- 服装。
图片来自 P4 已采纳候选(asset_image_candidates.is_adopted),旧资产在没有版本候选时,仅当版本就是当前版本才回退到旧图片槽位。
项目开启 projects.auto_use_latest_candidate 后:
- 造型版本还没有已采纳候选时,自动推荐会使用该版本最新一张成功候选;
- 已采纳候选仍然优先,不会被后来的抽卡结果挤掉;
- 开关默认关闭,入口在镜头参考素材面板的「自动使用最新候选」。
历史镜头没有 ShotAssetVersion 时,只按真实业务关联兜底:
ShotCharacterLink→ 角色当前身份/造型版本;ShotDetail.scene_id→ 场景当前版本。
不按文件名、目录名或模糊字符串猜测资产。找不到图片时返回明确错误。
规则:
- 软推荐 3–7 张,硬上限 9 张;
- 不添加无关素材;
- 人工删除的自动项不会再次推荐;
- 人工锁定项不能被自动推荐删除;
- 超过硬上限阻止生成,不做静默截断。
4. @ 引用
正则解析 @名称:
- 角色正式名 +
character_aliases别名; - 场景、道具、服装名称;
- 同名/别名歧义返回未解析或使用该镜头已保存的明确引用,不做随机绑定;
- 解析结果保存稳定 asset_id/version_id;角色改名后,历史 @ 引用仍按
shot_prompt_references指向同一 Character; - 未解析
@进入阻塞错误。
4.1 @名称 → H3 官方标签
用户不需要手写 <Subject N>。build_generation_preview 在构建 IR 前做两件事:
- 补齐 manifest:
@已解析、但还没有 active binding 的资产,按资产版本取第一张可用图片补进本次请求清单(source=prompt_mention,不写数据库绑定);仍受 9 张上限约束。 - 替换标签:按 IR 参考顺序计算
Subject N(同一资产多张图共用一个 Subject),把@小王替换为<Subject 1>;未解析或没有可用图片的提及进入blocking_errors,不会把裸@小王交给 H3。
自由生成工作台另有一套轻量语法(没有资产库):
@1/@图1→<Subject 1>,并补<Picture 1>定义;@v1→<Video 1>;@文件名→ 按上传文件名匹配;- 出现
@时自动补全 H3 六段;没有@时保持一句话原文。
4.2 视线锁定
台词行已有结构化 target_character_id(听者角色)。IR 会优先按它找到对应 <Subject N>;只有该字段缺失或受话人没有参考图时,才回落到“第一个非说话角色”。群像镜头不应依赖回落。
对白镜头必须在 <d> 外写清三件事,缺一不可:
<Subject 1> (S1), with their eyes fixed on <Subject 2>, their face angled
three-quarters toward <Subject 2>, and their pupils resting on the eyes of
<Subject 2>, says, <d>[Chinese] …</d>单角色镜头不虚构对话对象;旁白/画外音/电话声不加视线句。
4.3 运镜与故事板
- 一个镜头只写一个主导运镜;复杂路径优先单镜头
Arc Shot,路径超过约 180° 或跨多组人物时拆成[Shot 1]/[Shot 2]; - 角色图 + 运镜参考视频走 Ref2VA,写
<Video 1> is the camera-movement reference for [Shot 1],并声明不复制参考视频的服装/背景/文字; - 故事板只是一张参考图:
<Picture N> is a storyboard reference for [Shot 1]-[Shot K],面板边框/编号/标签只是规划标记,不进入成片;8–10 秒最多映射 2–3 个面板。
shot_details.storyboard_panels 保存面板映射:
[
{"index": 1, "start_seconds": 0, "end_seconds": 2.5, "framing": "medium two-shot",
"subjects": ["Subject 1", "Subject 2"], "notes": "林晚转身看向苏陌"},
{"index": 2, "start_seconds": 2.5, "end_seconds": 5, "framing": "close-up",
"subjects": ["Subject 1"], "notes": "林晚抬眼"}
]渲染器会写成:
<Picture 4> is a storyboard reference for [Shot 1]-[Shot 1]. ...
Panel 1 maps to 0.00–2.50s: medium two-shot; subjects: Subject 1, Subject 2.
Panel 2 maps to 2.50–5.00s: close-up; subjects: Subject 1.
The panel borders, numbers, and labels are planning marks only and do not appear in the video.约束:
- 故事板参考图名称必须含「故事板 / storyboard」,否则面板映射不写入提示词;
- 面板结束时间必须大于起始时间,且不超过镜头时长;
- 面板时间区间不能重叠;
- 没有故事板参考图时,只配置面板不会生成任何
<Picture N>。
4.4 提示词 Linter
render_h3 在返回前执行 _lint_dialogue_contract,发现以下问题时写入 warnings:
<d>外仍有未翻译的@提及;<d>外出现引号包裹的文本(可能被朗读);<d>外出现说话动词但没有台词标签;<Audio N>定义未绑定(Sx);- 同一个
[Shot N]出现多个主导运镜。
Linter 只提示不自动改写的项(引号、说话动词)由审核台人工确认;@ 与运镜问题会直接影响生成稳定性,应在预览阶段处理。
预览接口同时返回结构化 issues:
{"level": "blocking", "code": "at_reference", "message": "@小王 没有可用的参考图…"}level 为 blocking / warning / info;code 目前包括 at_reference、audio_same_text、camera_multi_move、storyboard_panel、audio_reference、reference_manifest、general。前端按级别显示数量并按 code 分组,避免把“必须改”和“建议改”混在一起。
镜头参考面板的提示词输入框上方提供「插入 @ 引用…」下拉,选项来自项目角色/场景/道具/服装;选中后插入 @名称 。直接输入 @ 仍然有效,后端负责解析、补绑定和阻塞未解析引用。
5. 预览与生成
build_generation_preview:
- 读取 active bindings;
- 生成 manifest 与 IRReference(
图N); - 构建 H3 IR,显式传入 references,不再自动收集;
- 生成最终 H3 prompt;
- 返回参考文件顺序、音频、prompt、warnings、blocking_errors、input_hash。
提交前一致性校验:
create_video_task接受预览返回的expected_input_hash;- 若提交时重新构建的 manifest/prompt/音频/参数 hash 不一致,返回冲突并要求刷新预览;
- 不静默使用新的自动推荐或最新资产版本。
高级 prompt:
- 可覆盖最终 prompt;
- 必须校验
<Picture N>/<Audio N>不超过 manifest/音频上限; - 不再静默修补编号。
编号与实际图片顺序
图N只按「真正进入请求的有效图片」连续递增;- 某条绑定缺文件被跳过时,不会留下 图1、图3 的空洞;
- 预览同时返回
manifest(绑定视角)与request_manifest(实际请求顺序 + token); - UI 预览、
images数组、Renderer 的<Picture N>和任务reference_file_ids使用同一次构建结果; - 用户调整素材后,
input_hash变化,旧预览失效,必须重新预览后才能提交; - 快照保存 manifest 的
token、file_id、资产 ID/版本与顺序,后续换图不改写历史快照。
5.1 手动添加与替换
POST /api/v1/studio/shots/{id}/reference-bindings/from-asset:
- 支持从项目已关联的角色/场景/道具/服装当前版本添加;
- 支持把镜头已确认首帧作为
shot_composition参考; - 资产必须属于镜头所在项目;
- 按 file_id 去重,仍受 9 张上限约束;
- 人工添加项默认锁定,删除前需先解锁。
首帧参考不是全局强制项:系统不会自动调用图片 API 生成首帧,也不会把所有模型都当作支持首帧。
create_video_task 使用同一 preview 构建 run_args,并写 shot_generation_snapshots。
新路径默认 auto_adopt=false:生成完成只新增候选,不自动覆盖当前视频。
6. 固定音色样本与音频参考
P6 正式路径区分:
characters.voice_id:供应商 TTS 音色 ID;character_voice_samples:可提交给 H3 的固定音频样本 FileItem。
项目 use_dialog_audio_as_reference 关闭时,不添加任何参考音频。开启时:
- 按镜头对白说话人查找已启用固定样本;
- 说话人不明确、缺少样本或超过 3 人时阻止 P6 生成;
- 不使用其他角色音频兜底;
- 音频编号与最终 H3 prompt 的
<Audio N>使用同一份快照; - 旧视频入口继续保留原有台词配音参考行为,供历史任务兼容。
上传接口:POST /api/v1/studio/characters/{id}/voice-samples;迁移 047-add-character-voice-samples.sql。
7. 准备度
在既有 readiness 上追加:
- 参考绑定存在、文件存在;
- 参考图不超 H3 上限;
- 镜头资产版本存在;
- 提示词 @ 引用均可解析;
- 既有模型/供应商/时长/任务/参考帧检查继续生效。
P9-C 起,GET /api/v1/studio/shots/{id}/p6-readiness 同时返回 quality_checks,与硬性 checks 分离:
blocking:说话角色/场景资产不存在、跨项目引用等,无法正确构建输入;warning:声音描述缺失、场景版本未进入参考图、短镜头多机位等;info:已满足约束或优化建议。
场景连续性检查会核对:
ShotDetail.scene_id与ShotAssetVersion(scene)是否一致;- 场景参考图是否实际进入 active manifest;
- 场景参考图版本是否与
ShotAssetVersion(scene)一致。
用户主动移除场景参考时保留其选择,只返回 scene_reference_missing,不静默恢复。
8. API
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/v1/studio/shots/{id}/reference-bindings | 参考列表 |
POST | .../reference-bindings/recommend | 自动推荐 |
POST | .../reference-bindings/from-asset | 从项目资产/已确认帧添加 |
PATCH/DELETE | .../reference-bindings/{bid} | 锁定/启停/删除 |
POST | .../reference-bindings/reorder | 排序 |
POST | .../reference-bindings/upload | 镜头专属上传 |
POST | .../prompt/resolve | 解析 @ |
PUT | .../prompt | 保存提示词 |
POST | .../generation-preview | 同源预览 |
POST | .../generation | 单镜头生成 |
GET | .../generation-snapshots | 快照历史 |
GET | /api/v1/studio/generation-snapshots/{id} | 快照详情 |
GET/POST/DELETE | /api/v1/studio/characters/{id}/voice-samples | 固定音色样本 |
9. 当前边界
- 图片上传只做镜头参考,不自动生成图片;
- 旧视频入口仍支持台词配音参考;P6 正式路径使用固定音色样本;
- 额度门禁、批量任务、视频审核在 C12/C13/C14 继续。