视频配乐生成和单首音乐生成看起来相似，工程上却多了一层时间轴约束。系统不能只返回一个音频地址，还要知道镜头长度、动作点、旁白区间、响度目标和最终导出用途。
双十一期间普通生成活动价 0.4 元一次、固定两首，低成本适合批量试验，但批量流程必须把时间轴信息记录成结构化数据，否则候选越多，人工对齐越困难。
一、视频配乐请求需要哪些字段
{
"video_id": "promo-20261106",
"duration_sec": 18.5,
"purpose": "product_demo",
"cuts_sec": [3.8, 8.1, 13.4],
"voice_ranges_sec": [[1.0, 7.5], [10.0, 16.0]],
"energy_curve": "low-high-hold-soft",
"ending": "clean_short",
"delivery_formats": ["mp3", "wav"]
}这些字段描述的是视频，不是音乐风格。曲风、音色和配器可以在另一层模板中管理。两边分开后，同一个项目更换曲风时不必重新描述全部镜头信息。
二、镜头时间轴与音乐结构解耦
建议把剪辑时间轴保存为独立实体。剪切点、关键动作、旁白区间和需要留白的位置都属于视频元数据，音乐版本只是引用这条时间轴生成的结果。
这样做后，同一视频可以生成轻快版、安静版和电影版，每个版本都针对同一组剪切点，不必复制一份视频配置。
时间戳应统一使用毫秒或秒的浮点值，不要让前端、后端和上游任务各自使用不同单位。时间轴误差在三十秒视频里可能不明显，但在快切视频里会直接造成卡点错位。
{
"project_id": "promo-20261106",
"timeline_version": 4,
"music_template_version": 2,
"operation_type": "video_score",
"requests": [
{"energy": "restrained", "voice_ducking": true},
{"energy": "rhythmic", "voice_ducking": true}
]
}批量提交时，每个候选仍是独立业务结果，不要只保存一个"生成成功"的总状态。某一条候选可能适合口播版、另一条适合纯画面版，它们的试听与采用状态必须分开记录。
三、音乐版本资产如何记录
每个音乐版本至少保存 song_id、来源生成请求、模板版本、音频地址、时长、峰值、响度、格式和检查结果。用于视频时还要保存入点、出点、淡入淡出和人工调整。
不要把"视频项目版本"和"音乐生成版本"混成一个字段。一个视频项目可能测试八首音乐，每首音乐又可能有完整版和剪辑版，关系必须是多对多。
前端展示时也应区分原始候选与已采用版本。用户删除项目时，原始候选可以进入异步清理，已交付资产则按保留策略处理，不能因为删除一条草稿就误删仍在其他项目中引用的音轨。
四、响度与旁白让位
统一响度不等于所有项目都用同一个音量。口播视频需要给人声保留清楚的中频空间，纯画面视频则可以接受更完整、更宽的音乐动态。
系统可以在导出前自动测量整体响度和峰值，但机器指标只能过滤明显问题。是否盖住旁白、动作与鼓点是否对应，仍需要人工试听。
可以记录旁白区间内的音乐电平变化，帮助排查"单独听正常、加口播就听不清"的情况。自动侧链压缩不是必选项，但结果需要可解释。
如果使用自动侧链，应同时保存压缩触发区间、增益变化和最终响度。否则人工听到问题却无法判断是生成素材本身太满，还是自动处理引入了新的起伏。
五、候选筛选与自动检查
候选进入视频后，至少检查文件能否解码、时长是否覆盖项目、是否出现静音、峰值是否超限、入点和出点是否会切断明显音节。
自动检查通过后再进入人工评审。人工只看结构、节奏和情绪关系，不必反复处理零字节文件、错误格式或无法解码这类工程问题。
每次淘汰也应保存原因：太满、节奏冲突、结尾拖尾、旁白被盖住。积累之后，团队可以优化模板，而不是重复踩同一种坑。
可以把淘汰原因做成有限枚举，再保留文本备注。有限枚举适合统计，文本备注用于解释边界情况。两者结合，后续才能形成真正可查询的经验。
六、多版本导出接口
一个母版可以导出完整音频、短视频剪辑版、无旁白音乐版和平台发布版。每次导出记录源资产和参数，避免用户拿到无法追溯的临时文件。
对外接口使用稳定 asset_id，不要直接暴露上游临时链接。下载前检查账号权限和资产状态，再按需生成可访问地址。
导出任务应有独立状态和回调。视频剪辑版转码失败时，不影响完整母版；平台发布版下载过期时，也不要求重新生成音乐。资产与派生文件之间的父子关系必须明确。
七、失败恢复与幂等
使用项目 ID、时间轴版本、模板版本和导出用途组成幂等键。网络超时后先查询已有任务，确认是否已经受理，避免同一视频重复创建多个生成请求。
生成任务和导出任务要分开。生成成功但转码失败时，不应重新生成音乐；视频时间轴修改时，也不应自动覆盖旧音乐资产。
请求日志至少记录业务幂等键、上游任务 ID、模板版本、时间轴版本、候选序号和当前阶段。故障恢复时按业务键查询，而不是依赖用户重复点击。
八、最小落地顺序
第一步保存视频时间轴和旁白区间，第二步把曲风模板独立成配置，第三步记录一次生成的两首候选，第四步增加响度与格式检查，最后再接自动剪辑和多平台导出。
当这条链路能稳定跑通，配乐生成才真正进入内容生产系统。它不再是一个孤立的文本转音频接口，而是视频项目中可回滚、可比较、可持续交付的一环。
活动持续到 11 月 12 日 0 点，普通生成活动价 0.4 元一次、每次两首，翻唱和编辑能力以页面实时价格为准。低价窗口适合验证流程，不适合省略时间轴和版本记录。
真正可复用的视频配乐系统，不只是把音乐生成接进接口，而是让每个音轨都能说明它为什么出现在这一段画面里。