Skip to content
H3 多参考 Manifest 与生成输入快照

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_id
  • file_id(FileItem)
  • asset_type / asset_id / asset_version_id
  • reference_role:角色身份/造型、场景、道具、服装、镜头构图、上一镜
  • source:auto / manual / uploaded
  • sort_order
  • is_pinned
  • is_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:

  1. 角色身份版本;
  2. 角色当前造型;
  3. 场景;
  4. 道具;
  5. 服装。

图片来自 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 前做两件事:

  1. 补齐 manifest:@ 已解析、但还没有 active binding 的资产,按资产版本取第一张可用图片补进本次请求清单(source=prompt_mention,不写数据库绑定);仍受 9 张上限约束。
  2. 替换标签:按 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:

  1. 读取 active bindings;
  2. 生成 manifest 与 IRReference(图N);
  3. 构建 H3 IR,显式传入 references,不再自动收集;
  4. 生成最终 H3 prompt;
  5. 返回参考文件顺序、音频、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 继续。