视频生成台
只做一件事：让已经定死的画面动起来，并且留下可追溯的记录。
视频模型在这里负责三件事：动作、运镜，以及把旁白念出来。主体长相、服装、场景、色板、光线、构图、屏幕文字在 S1/S2 已经锁死，这一层不允许重新创作。它一旦开始"发挥"，整条片子的一致性就崩了。
旁白不再走独立配音。 台词写进提示词，由模型直接念——这是这套流程和传统做法最大的不同，也是这一层最需要盯的地方。
一、进来的前提
四样东西缺一不可，缺一样就退回上一段：
| 要件 | 在哪 | 缺了会怎样 |
|---|---|---|
03-生成清单.md | short-video-prompt 产出，且 G2 已过 | 不知道该出几段、每段多长 |
| 每段台词原文 | 清单的逐段提示词里 | 模型不知道念什么，会自己编 |
| 资产图 / 首帧 | 04-素材/01-资产图/、04-素材/02-首帧/ | 主体每段一个样 |
KIE_API_KEY | 环境变量 | 提交不了任务 |
没有首帧不等于不能做：纯氛围、空镜、转场可以直接文生。但有主体出现的段落必须有图，这是硬线。
没有台词的段落可以不做旁白，比如空镜、纯音乐段。但一旦这段要说话，台词就必须进提示词——这是现在唯一的声音来源。
二、三种模式，互斥不可混用
平台一个请求只能选一种，字段越界就变成另一个模式，任务会直接失败。
| 模式 | 必填 | 什么时候用 | 明确禁止 |
|---|---|---|---|
text 文生 | prompt | 空镜、氛围、纯背景光效、转场 | 带 first_frame_url / last_frame_url |
first 首帧图生 | prompt + first_frame_url | 默认走这个：需要锁定起始构图 | 带 last_frame_url |
first-last 首尾帧 | prompt + 首帧 + 末帧 | 需要同时锁起始和结束、保证相邻段能接 | — |
清单里的「参考图」模式怎么落
short-video-prompt 的清单模式列可能是「首尾帧 / 参考图 / 文生」。当前模型没有参考图模式——reference_image_urls 这类字段在这个模型上不开放。所以要做一次映射：
| 清单写的是 | 实际提交成 | 说明 |
|---|---|---|
| 首尾帧 | first-last | 直通 |
| 参考图 | first | 把参考图当首帧用，锁起始构图 |
| 文生 | text | 直通，但只对无主体镜头成立 |
这一步不是妥协，是能力边界。 如果某段确实需要"参考图锁主体 + 自由构图"，只能靠首帧把构图也一起锁掉，或者回到 S2 改切段。
三、参数口径
| 参数 | 取值 | 默认 | 说明 |
|---|---|---|---|
duration | 4–15 整数秒 | 5 | 超 15 拆镜，低于 4 交后期做动效或裁切 |
aspect_ratio | 9:16 / 16:9 / 1:1 / 3:4 / 4:3 / 21:9 / adaptive | 9:16 | adaptive 只给文生，图生必须写死比例 |
resolution | 480p / 720p | 480p | 默认控制生成成本；需要正式交付清晰度时显式传 720p |
generate_audio | true / false | true | 不能关。旁白就在这条音轨里，关了等于没声音 |
web_search | true / false | false | 只对文生可用，一般不用 |
三条容易踩的：
- 比例必须与实际输出一致。模型返回明显不符比例或带黑边的结果，判质量失败，不许 letterbox 之后当成片交上去。
- 音频必须开。旁白、环境音全在这一轨里。只有纯空镜确实不需要声音时才用
--no-audio。 duration写整数。传 5.5 会被拒。
四、七步流程
① 读清单 → ② 定模式 → ③ 写视频提示词 → ④ 提交 → ⑤ 轮询下载 → ⑥ 媒体体检 → ⑦ 抽帧质检
① 读清单，先判能不能跑
逐段核对三件事，对不上就停下来问，不要猜：
- 每段的
duration是否在 4–15 之间（超了先拆） - 声明的首帧文件是否真的存在
- 引用的素材编号是否都在资产清单里
② 定模式
按第二节的表逐段定，一整个项目尽量统一。混用不是错误，但混用会让相邻段衔接更难看。
③ 写视频提示词
按 references/video-prompt.md 的七段结构写。两条核心：
- 只描述"变化"，不重新描述"是什么"。 首帧已经给了模型产品长什么样，提示词再描述一遍，等于让它按文字重画，一致性立刻丢。
- 台词照抄稿子，一字不改。 旁白现在由模型直接念，台词原文必须进提示词。改一个字，字幕就对不上音。
④ 提交
python scripts/kie_seedance.py create \
--prompt "…" --mode first \
--first 04-素材/02-首帧/S01_f01_v1.png \
--duration 6 --out 04-素材/03-片段/S01_v1.mp4 --wait
提交成功后立刻把 taskId 和指纹写进台账，再去做别的事。先做后记，中途断了就找不回来。
④-2 整条片子批量跑（默认 5 路并发）
一段一段串行跑，6 段就是半小时以上，而且大部分时间在等。批量并发跑，总时长约等于最慢的那一段。
# 先预演，把拼装好的请求体看一眼
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-片段 --dry-run
# 确认后真跑，默认 5 段同时
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-片段
# 被限流就降
python scripts/kie_seedance.py batch --tasks tasks.json --out-dir 04-素材/03-片段 --concurrency 2
任务表格式见 assets/batch-tasks-example.json，每段一条，mode / first / last / duration / prompt 含义与单条命令一致。
并发不是越快越好，它有个真实的坑：台账会被写乱。
5 段同时跑完，如果每段一结束就去改 00-生成台账.md，五次写入会互相覆盖，最后只剩一段的记录。正确做法是：
① 批量跑完，收下汇总里的 items（已按清单顺序排好）
② 一次性回写台账：五段一起写，而不是跑一段写一段
③ 回写后立刻核对：清单几段，台账就该有几行
如果你更想边跑边记，那就把并发降到 1——串行 + 边跑边记，是唯一不会写乱的方式。这个取舍自己定，但不能既并发又零散写。
被限流的表现是 code != 200 或 HTTP 429，不是"画面变差"。看到这类报错先降并发，不要改提示词。
失败不中断：一段挂了，其余照跑，最后看汇总里的 failed。想要"一错就停"加 --stop-on-error，它会停止提交新任务，已经在跑的不受影响。
⑤ 轮询下载
--wait 会一直等到下载完成。也可以分开做：create 拿到 taskId → wait --task-id。
轮询间隔从 6 秒起逐步拉长到 30 秒，上限 15 分钟。超时不代表失败，先查状态再决定。
⑥ 媒体体检（脚本判）
# 有台词的段：音轨必须存在
python scripts/inspect_clip.py --file 04-素材/03-片段/S01_v1.mp4 \
--ratio 9:16 --duration 6 --expect-audio
# 无台词的空镜：应当没有音轨
python scripts/inspect_clip.py --file S02_v1.mp4 --no-expect-audio
查五件客观事实：文件在不在、大小是否正常、时长对不对、比例对不对、音轨在不在。通过只说明"下到了能播的文件"，不说明画面能用，更不说明台词念对了。
音轨这一项现在比以前重要：旁白就在这条音轨里。没有音轨 = 这段没声音，等于废片；有音轨但念错字，脚本查不出来，只能听。
⑦ 抽帧质检 + 听声（人判）
画面：抽至少三个点（开头、中段、结尾），按 references/clip-review.md 的七项看。
声音：旁白现在由模型念，所以每一段带台词的片段必须听一遍，对照原稿核三件事：
| 听什么 | 判据 |
|---|---|
| 有没有漏句 | 原稿几句，就应听到几句 |
| 有没有念错字 | 关键词、品牌名、数字对不对 |
| 有没有多余声音 | 不该出现的配乐、旁人、杂音 |
念的和稿子不一致时，不要将就。 两种处理：重出这一段，或改字幕去贴合实际念的内容。唯一不能做的是照原稿打字幕——观众听到的和看到的对不上，比念错本身更伤。
这一项必须听。含糊关键字可重复转写至少三次辅助比对，逐句人工终审后把结论写入 04-素材/00-台词定案.json；见 references/clip-review.md。
五、三层状态，别混成一个
| 状态 | 谁判 | 含义 |
|---|---|---|
| 媒体通过 | 脚本 | 文件完整、参数符合、音轨在 |
| 画面通过 | 人看 | 主体没变、没畸形、能接上下一段 |
| 台词通过 | 人听 | 台词念全了，关键词没念错 |
三个都过，状态才能写「质量通过」。
把"下载完成"当"可用"，是这条链上最常见的错误——片子进了剪辑台才发现第 4 段主体变了，前面白拼。现在多了一层：画面都对、台词念错一个字，整段还是废的，因为字幕没法对。
台词这层最容易被跳过，因为它需要安静地戴耳机听，而不是扫一眼。
六、台账：写在 04-素材/00-生成台账.md
一段一行，记六项：请求指纹、模式、taskId、状态、输出文件、失败原因。
台账的作用不是留档，是防重复提交。同一条片子隔一天回来接着做，读台账就知道哪段已完成、哪段提交过没下载、哪段失败过。
规则见 references/task-ledger.md，四条摘要：
- 状态是「质量通过」且文件在 → 跳过
- 有 taskId 且状态是「等待中 / 生成中」→ 只查询，不新建
- 状态是「生成成功，待下载」→ 只下载；URL 过期就查同一 taskId 换新 URL
- 状态是「失败」→ 不自动重提，等用户明确说重做
七、失败怎么处理
先定位是哪一层坏的，再决定改什么。 别一上来就改提示词。
| 现象 | 病根 | 改哪里 |
|---|---|---|
| 主体变形、产品变样 | 没有首帧，或首帧本身就不对 | 补首帧 / 换首帧 |
| 画面抖、闪烁 | 动作写得太多 | 删到只剩一个动作 |
| 文字错乱、多出手指 | 要求模型写文字/复杂手部动作 | 文字交后期，手部动作简化 |
| 比例不对、带黑边 | 参数与返回不符 | 判失败，重出，不裁黑边 |
| 段与段接不上 | 末帧与下一段首帧不一致 | 用首尾帧模式，或补交接帧 |
| 漏念、只念半句 | 该段台词字数超出镜长 | 砍台词，或把这一段拆两段 |
| 念错字、念成别的词 | 生僻字、多音字、品牌名夹在长句里 | 换成常用说法；品牌名单独成句 |
| 台词被配乐盖住 | 提示词没写"无配乐"或不盖人声 | 补一句声音约束，重出 |
| 完全没声音 | 误用了 --no-audio，或音频没开 | 检查提交参数，重出 |
| 提交就报错 / 429 | 并发放太高被限流 | --concurrency 2 重跑，别改提示词 |
| 同一段反复失败 | 有多个变量同时变 | 一次只改一个变量 |
台词类问题占了一半以上。 这类问题的共同点是：画面看着挺好，只有听才发现。所以每段必须听完再定通过。
返修时一次只改一个变量。同时改提示词、时长和首帧，即使成功了也不知道是哪个起了作用，下次同样的问题还会再犯。
详细诊断见 references/clip-review.md。
八、边界
- 不重新设计视觉：主体、场景、色板、光线在 S2 已锁定，这里只让它们动起来
- 不改台词文本：原稿怎么写就怎么念。要改词，回 S1/S2 改，不在这里临时调整
- 不做字幕：文字一律后期叠。模型可以"念"中文，但不能"写"中文
- 不修音频：念错的段落只能重出，或改字幕去贴合。这里不混音、不补录
- 不做剪辑：不拼段、不卡点、不调色，那是 S4
- 不判断"好不好看"：只判断"能不能用"。观感是审片环节的事
- 不承诺一次就过：生成是概率事件，2–4 个候选是常态，不是失败
九、参考资料
| 文件 | 什么时候读 |
|---|---|
references/api-and-modes.md | 查接口、参数、三模式字段、错误响应时 |
references/video-prompt.md | 写视频提示词、改提示词时 |
references/task-ledger.md | 建台账、续做、判断该不该重提时 |
references/clip-review.md | 抽帧质检、判失败、决定返修方向时 |
| references/assembly-ops.md | S4 拼接、字幕与混音的 FFmpeg 实施细节 |
assets/gen-ledger-template.md | 建台账时 |
| assets/dialogue-final-template.json | 记录定版台词、转写辅助和人工终审时 |
assets/batch-tasks-example.json | 批量跑清单时 |
脚本：
| 脚本 | 用途 |
|---|---|
scripts/kie_seedance.py | 提交 / 批量 / 查询 / 等待下载 / 上传参考帧 |
scripts/inspect_clip.py | 媒体体检（需要 ffprobe） |