Skip to content
视频提示词链路与参考图

视频提示词链路与参考图

2026-10 更新:旧版项目/章节/分镜页面已退役,相关页面名仅用于解释历史设计。 当前入口统一为 V2 树状工作台,见 树状工作台 与 旧页面退役清单。

本文属于“当前架构”文档,描述当前已经生效的视频提示词链路。

H3 提示词格式以官方 h3-prompt-writing Skill 为依据(上游 MiniMax-AI/MiniMax-H3 commit d21241f0a4b3acbb34c97dae47fa417b7065e438);DyeingTime 的业务约束在此之上叠加。

为什么要有 IR 层

视频提示词不能直接由“镜头数据 → 一句话”拼出来,原因是:

  • 同一份镜头信息要输出给不同供应商、不同模型,各自要求的格式不同(例如 H3 要求英文六段式并限制字数)。
  • 参考图顺序、说话人编号、图片编号必须在提示词正文和实际上传的图片列表之间严格一致,否则模型会把 图2 认成另一个人。

因此链路被拆成两段:

镜头业务数据
→ IR(结构化中间表示)
→ 渲染器(按目标模型输出格式)
→ 最终视频提示词

IR 是唯一事实来源:参考图列表、主体定义、对白行、镜头语言都先在这里定稿,再交给渲染器。

IR 层

代码在 backend/app/chains/prompts/ir.py。

模型作用
IRReference一张参考图:token(图1…)、kind、name、file_id
IRAudioReference一条音色参考音频:Audio N、说话人、file_id
IRPicture首帧/尾帧/关键帧槽位,用于 I2VA/FL2VA/L2VA 对齐句
IRSubjectDefinition主体定义(角色/场景/道具/服装的外观描述)
IRShot镜头语言:景别、机位、运镜、时长
IRDialogueLine一句对白:说话主体、文本、情绪、line_mode、音频标签
IRPrompt汇总以上内容,是渲染器的唯一输入;含 reference_mode

入口是:

def build_video_prompt_ir(...) -> IRPrompt

相关常量:

  • MAX_REFERENCE_IMAGES:参考图上限(转发 short_drama_rules.MAX_REFERENCE_IMAGES,当前 9)。
  • DEFAULT_VIDEO_DURATION_SECONDS = 5.0:镜头未配置时长时的兜底。

参考图顺序:角色卡永远是 图1

backend/app/services/studio/generation/frame/build_context.py 定义了固定优先级:

_REFERENCE_KIND_PRIORITY = {"character": 0, "scene": 1, "prop": 2, "costume": 3}

build_ordered_shot_frame_references 会先按该优先级稳定排序,再去重、再分配 token = f"图{len(mappings) + 1}"。所以:

  • 角色卡即使排在入参列表最后,也一定是 图1。
  • 同类内保持调用方(前端)传入的顺序。
  • 未识别的类别排在最后,且不会被丢弃。

这条顺序是安全的,因为上传图片列表与提示词里的“实体名 → token”替换都在服务端生成:app/services/studio/generation/frame/derive_preview.py 用 images=[mapping.file_id for mapping in context.ordered_refs] 构造上传列表,前端只提交实体名。

人物卡的双重判定

一个角色“和镜头关联”不等于“这个镜头里出现了这个角色”。如果只按关联插卡,纯空镜也会被塞进角色参考图,污染生成结果。

因此在 _collect_asset_references 里,角色需要同时满足:

  1. 该角色已关联当前镜头;
  2. 该角色的名字出现在当前镜头的剧本语料里。

剧本语料由 _shot_script_corpus(pack) 拼成,包含 title、script_excerpt、shot_description、action_beats、dialogue_summary;刻意不含 previous_shot_summary / next_shot_goal——相邻镜头出现的角色不代表本镜头出场。

判定函数是 _character_appears_in_shot(*, name, corpus) 的子串命中。因为 dialogue_summary 的构造方式是 f"{line.speaker_name or '角色'}:{line.text}",所以“该角色有台词”会被自然覆盖。

未命中时不会静默丢弃,而是追加一条可解释的警告,例如:

角色「林晚」已关联该镜头,但本镜头剧本内容里没有出现,本次未插入该角色卡

场景、道具、服装不参与该判定,仍只看有没有绑定文件。

渲染器

backend/app/chains/prompts/renderers/__init__.py 对外暴露:

def uses_h3_prompt_format(*, provider: str = "", model: str = "") -> bool
def get_video_renderer(*, provider: str = "", model: str = "") -> VideoRenderer
def render_video_prompt(...)

H3 渲染器在 renderers/h3.py,关键约束:

  • H3_MAX_PROMPT_CHARS = 7000
  • H3_RECOMMENDED_WORD_RANGE = (350, 500);实际校验按 word_range_for_duration() 自适应:
    • 4–6 秒:200–300 词;
    • 7–10 秒:300–400 词;
    • 11 秒以上:350–500 词。
  • 输出结构由 h3_label_for(kind, subject_index, picture_index) 生成标签,保证“主体编号 / 图片编号”与 IR 一致。
  • 部分段落(主体定义、摘要、留存分析)在模型未产出时有 fallback 实现,避免整段缺失。

输入模式与渲染分支

IRPrompt.reference_mode 决定 H3 走哪套结构:

模式渲染结构关键要求
reference六段 Ref2VA<Subject N> is ...、<Audio N>、retention_analysis
first / keyI2VA 三段首行 <Picture 1> 对齐 0.00 秒
lastL2VA 三段首行 <Picture 1> 对齐总时长
first_lastFL2VA 三段Picture 1 对齐 0.00,Picture 2 对齐总时长
first_last_keyFL2VA 三段关键帧不会上传,预览会给 warning
text_onlyT2VA 三段无图片对齐句

首帧/尾帧/纯文本模式不再把角色卡、场景卡当作 <Picture N> 编号;这些模式只保留 IRPicture 槽位和文字描述,避免提示词编号与实际上传图片错位。

音频参考

参考音频只在 reference 模式生效。解析顺序:

build_run_args / preview_prompt_and_images
→ resolve_video_reference_audio_file_ids()
→ 按说话人去重,每个说话人取第一条已生成配音,最多 3 条
→ build_video_context(reference_audio_file_ids=...)
→ IR.build_video_prompt_ir(audio_file_ids=...)
→ H3 渲染 <Audio N>

写法:

<Audio 1> is the voice-timbre reference for <Subject 1> (S1).
<Audio 1>: reference - its vocal timbre guides the dialogue delivery of <Subject 1> without copying the original signal.
<Subject 1> (S1) says in the voice timbre referenced from <Audio 1>, <d>[Chinese] ...</d>

音频是音色参考,不是原声复用;retention_analysis 固定用 reference。没有参考音频时,提示词不写 <Audio N>,但台词仍保留 <d>[Chinese] ...</d> 和 (Sx)。

预览接口与真实生成共用同一个音频解析函数,响应里的 audio_file_ids 顺序就是 <Audio N> 的顺序。

需要 LLM 生成正文时走:

def build_h3_agent_variables(ir: IRPrompt) -> dict[str, str]
class H3VideoPromptAgent(AgentBase[H3Prose])
async def generate_h3_prose(...)

代码在 backend/app/chains/agents/h3_video_prompt_agent.py。

默认视频模型

视频生成任务的模型不可由请求体指定:build_run_args 一律通过 resolve_default_video_model(db) 读取 ModelSettings.default_video_model_id, 因此「当前默认模型」决定了所有视频生成实际使用的供应商与模型。

当前生效配置(运行库 model_settings):

项值
默认视频模型MiniMax-H3(优云智算供应商 a04dc839…,base https://cp.compshare.cn)
备用视频模型minimax-h3(PIX 供应商 db1fec41…,保留可选,不再默认)

决策背景:

  • 默认模型由产品方指定为优云智算的 MiniMax-H3(历史生成结果可用,供应商链路能正常出片);
  • PIX 的 minimax-h3 曾作为默认并被成功使用过,现降级为备用;
  • 已知风险:优云智算链路上曾出现一次任务载荷中提示词中文乱码 (generation_tasks 中 task_kind=video_generation 的 run_args.input.prompt 全为 ?); 该条任务虽成功出片,但画面与提示词不对应。若默认切回优云智算后再次出现乱码, 优先排查供应商 API 的编码/请求体序列化,必要时切回 PIX;
  • 40–150 集短剧要求跨集画风一致,默认模型保持单一供应商/模型是硬约束; 如需切换,在「模型设置」页修改默认视频模型即可,代码无需变更。

短剧创作纪律

backend/app/chains/prompts/short_drama_rules.py 是无 IO、无 LLM 的纯常量与纯函数层,供 IR 与校验复用:

  • SUBTITLE_SAFE_AREA_RATIO = 0.15:画面下部约 15% 作为字幕安全区。
  • micro_expression_quota(duration_seconds):按镜头时长给出微表情配额。
  • CHARS_PER_MINUTE = 150、MAX_SINGLE_UTTERANCE_CHARS = 50:口播节奏与单句上限。
  • estimate_dialogue_seconds(...):按标点估算对白时长。
  • action_beats_for_duration(duration_seconds):按时长给出动作拍点数量。
  • ABSTRACT_WORD_RULE / find_abstract_words(text):拦截“唯美”“电影感”这类不可拍摄的抽象形容。

参考图模式

backend/app/services/studio/generation/video/build_context.py 定义:

REFERENCE_MODE = "reference"
REFERENCE_MAX_IMAGES = 9
REQUIRED_FRAMES_BY_MODE = {...}   # 权威定义,含 REFERENCE_MODE: ()

参考图模式与首尾帧模式互斥:它不使用分镜帧,参考图由服务端按 IR 的有序参考列表解析:

resolve_reference_mode_file_ids(db, shot_id=...)

客户端提交 images 为空是正常的——服务端会覆盖。

缺图必须是可执行的 400

validate_images_count(reference_mode, images) 在参考图模式下的两支报错都写明了原因与下一步:

  • 0 张:reference_mode=reference 需要至少 1 张参考图,但本镜头没有可用参考图。角色卡只在剧本中出现该角色时才会插入;空镜请改用 text_only。
  • 超过上限:reference_mode=reference 最多支持 9 张参考图,当前 N 张

生成前准备度

get_shot_video_readiness(db, *, shot_id, reference_mode) 返回逐项检查,当前 8 项:

key含义
extraction_ready镜头提取结果已确认(或已标记无需提取)
duration_ready镜头时长已配置
prompt_ready视频提示词可用
reference_frames_ready当前参考模式所需的帧齐备
reference_images_ready参考图模式下能解析到至少 1 张参考图
video_model_ready默认视频模型可用
provider_ready该模型供应商可用
no_active_video_task当前没有进行中的视频任务

reference_images_ready 与 reference_frames_ready 的分工很重要:前者管“参考图有没有”,后者管“分镜帧够不够”。空镜在参考图模式下会在这里被判为未就绪,而不是等到提交后收到 400。

生成端点(POST /api/v1/film/tasks/video)在构造任务参数之前会再跑一次同一套检查,未就绪直接返回 409:

Shot is not ready for video generation: reference_images_ready: ...

V2 镜头面板读取 reference_images_ready / p6-readiness 的结论,在参考图不可用时显示阻塞项并要求补齐素材;不会静默回落到 text_only 后继续提交。

另有一个项目级的开工预检:

GET /api/v1/studio/projects/{project_id}/production-readiness

检查项目是否有默认文/图/视频/音频模型、风格是否就绪、是否有可用的视频比例、角色是否有音色、分镜是否有参考帧等,用于开工前一次性暴露阻塞项。

说话人、声音描述与连续性约束(P9-C)

正式 H3 生成链路在 IR 中新增以下硬约束;它们进入最终 Prompt、生成预览和不可变 ShotGenerationSnapshot,并参与 input_hash。

镜头语言优先级

  • camera_shot / angle / movement 是结构化权威字段;
  • Prompt 会写入 Camera language is fixed by the production fields: ...,并明确要求忽略描述中冲突的景别/角度/运镜;
  • 自由描述只作画面补充,不得反向覆盖三个下拉字段。

说话人来源

  • 对白说话人只来自 ShotDialogLine.speaker_character_id。
  • 不用角色名、参考照片、演员资料或性别刻板印象推断声音。
  • ShotVideoPromptPackRead.dialogues 与 IRDialogueInput / IRDialogueLine 保留:
    • speaker_character_id
    • voice_description(来自 characters.voice_description)
  • 没有确认说话人时,质量检查给出 warning,不随机绑定;用户可在镜头编辑页人工指定。

声音描述

没有音色参考时,H3 台词句输出:

<Subject 1> (S1), using this voice profile: <英文声学描述>, says, <d>[Chinese] …</d>

有音色参考时:

<Subject 1> (S1), in the voice timbre referenced from <Audio 1>, says, <d>[Chinese] …</d>
  • 声音描述仅用于文字约束,不等于音色身份锁定。
  • 有 <Audio N> 时不再输出文字 voice profile:IR 清空该台词的声音描述,Renderer 再做一次兜底清理;音色只由音频参考约束。
  • 没有 <Audio N> 时,声音描述必须放台词前、使用英文声学特征,不得放在 </d> 后,也不写用途评价。
  • 项目关闭 use_dialog_audio_as_reference 时不上传音频参考,只保留文字描述。
  • 项目开启时仍走固定音色样本;样本缺失/说话人不明确会进入质量检查或阻塞。

无对白镜头

没有任何结构化台词且没有自定义同期声时,IR 写入:

No spoken dialogue is requested; characters do not speak. Use only ambient room tone and natural physical sounds.

用于阻止模型自行发明对白、口型和声音。

默认单一连续镜头

IRShot.continuity 默认追加:

  • 场景已知:Keep the entire video in one continuous scene at <场景>; keep the background layout, lighting direction and character positions consistent; use continuous camera movement and do not cut to another location.
  • 场景未知:Keep one continuous scene and consistent background; do not cut to another location.

场景名兜底顺序:ShotDetail.scene_id → ShotAssetVersion(scene)。兜底只补 Prompt 上下文,不自动把场景图加入参考图列表,避免覆盖用户选择。

高级 Prompt 仍然优先,但不会静默补齐;若缺少 <d>、无对白或连续性约束,质量检查返回 warning,由用户决定修改高级 Prompt 或清空后使用自动渲染。

fallback 正文策略

文本模型不可用时不把中文画面描述直接塞进 H3 正文:

  • fallback 仍输出官方六段/三段结构;
  • 中文 visual、动作拍点、氛围、构图、连续性建议不进入英文正文;
  • 镜头语言从内部枚举映射为 medium shot / eye-level angle / static camera 等自然英文;
  • Subject 定义使用 <Picture N> 来源和英文主体类型;
  • 预览给出 warning:中文骨架可能被 H3 朗读为旁白,建议配置文本模型或提供英文高级 Prompt。

这不是“官方 Skill 已提升模型质量”的证明;它只保证输入结构合规并避免明显的中文旁白风险。

LLM 正文的确定性兜底

H3 正文由文本模型生成,但文本模型不能决定是否保留关键约束。render_h3 在装配阶段对 LLM 正文做只补缺失项的处理:

  • 缺少台词时补 _dialogue_fragment;
  • 缺少 voice profile 时补 voice profile;
  • 缺少“非说话角色沉默”时补该句;
  • 缺少“只有对白行会被朗读”时补 no-narration 约束;
  • 无对白但正文未声明时补 No spoken dialogue;
  • 缺少连续性时补 Continuity:。

这样即使文本模型改写或省略,最终 Prompt 仍保留结构化的说话人、声音和场景约束。

正文语言与旁白风险

H3 官方正文以英文为主,<d> 内保留原语言台词。P9-D1 实测发现:使用中文结构骨架时,H3 会把非 <d> 的画面描述朗读成旁白。

因此当前行为:

  • 有结构化台词时追加:Only the dialogue lines are spoken; do not read the shot description, subject definitions, summary, retention analysis, or continuity text aloud. No narration or voiceover.
  • 文本模型不可用、回落到中文骨架时,预览 warning 明确提示“H3 可能把非 <d> 文本朗读成旁白”;
  • 需要干净对白测试时,应配置可用文本模型,或在高级提示词中使用英文正文并显式声明 no narration。

朗读安全校验

自动渲染路径本身会追加 no-narration / no-speech 约束;高级提示词路径绕过了渲染器, 因此预览阶段额外执行 collect_speech_safety_checks:

  • 有台词但提示词没有“只朗读 <d>、不朗读描述”的约束 → warning;
  • 无台词但提示词没有明确无对白/无旁白 → warning;
  • <d> 之外出现“旁白/画外音/Narrator/Voiceover”标记 → warning;
  • <d> 之外出现“环境音/镜头说明/画面描述/Camera/Shot description”标记 → warning。

这些校验只提示、不自动改写用户提示词,也不阻止提交;用户应补齐约束后再生成。

质量检查分级

ShotVideoReadinessRead.quality_checks 与硬性 checks 分开:

  • blocking:说话角色/场景资产不存在、跨项目引用等,无法正确构建输入;会阻止提交;
  • warning:声音描述缺失、场景参考未进入 manifest、短镜头多机位、高级 Prompt 绕过等;
  • info:已满足的约束或可优化建议。

前端在镜头看板、工作台镜头面板和分镜工作室都展示同一组级别与修复建议;不会把 warning 当成硬性阻塞。

视频比例继承链

resolve_effective_video_options(db, *, shot_id, shot_detail, requested_ratio) 按以下顺序取值:

请求参数 ratio
→ shot_details.override_video_ratio
→ projects.default_video_ratio

全部为空时返回 400,报错会指出是哪个字段缺失;传入非法值时返回 400 并带上来源字段名(shot_details.override_video_ratio / projects.default_video_ratio)。

因此 VideoGenerationTaskRequest.ratio 是可选的——不传就按继承链解析。

相关文档