layer-motion-templates

图层动态模板

概述

动态模板是一个 render_video_timeline 模板，其中的媒体项使用 slot 而不是 file_id 来指定媒体。每次渲染时，为这些槽位传入相应文件，这样 40 个变体就能共用同一套设计好的剪辑：剪辑点、文字、转场和时长都相同，只替换媒体。这样才能让批量内容保持一致，并便于比较结果。

时间轴基础知识见 layer-video-timeline，动态设计见 layer-motion-graphics。决定要制作哪些变体的矩阵见 layer-ua-creatives 和 layer-localization。

如果你可用的技能中缺少此处提到的某个同级技能，请让用户安装它（npx skills add layerai/skills --skill <name>）；如果无法等待，请依据工具架构继续操作，并指出这一缺口。

快速参考

需求	字段
可替换的片段、图像或音频	在 video、image 或 audio 项上设置 slot: "<name>"，且不设置 file_id
为一次渲染填充槽位	videos、images、audios 映射：{"<slot>": [{file_id}]}
让旁白或片段决定时长	在对应项上设置 is_auto_length: true（每个模板最多一个）
限制渲染时长	template.max_duration_in_seconds（最长 120 秒）
可选元素	未解析的槽位会在渲染中省略
原位更新画板时间轴	已知时使用 timeline_object_id
估算变体价格	调用 estimate_video_timeline_price，不传 timeline_object_id 之外的所有参数

render_video_timeline 接受 {workspace_id, template, videos, images, audios}。template 的结构为 {width, height, fps, tracks: [{id, name, items, transitions}]}；项的结构为 {id, type, start_frame, duration_in_frames}，并带有 file_id 或 slot，还可选带有 layout {left, top, width, height}、effects、用于裁剪片段开头的 start_from_in_seconds 和 volume；solid 项接受 color {red, green, blue, alpha}。渲染会返回供 get_generation_run 使用的 generation_id。槽位映射以槽位名称为键：audios: {voiceover: [{file_id}]}。

设计模板

开始构建之前，先确定哪些内容会变化。每个元素要么是固定的（品牌字体、片尾卡片、徽标、背景音乐、转场），要么是槽位内容（钩子片段、旁白、游戏录屏、角色插画）。尽可能固定所有内容：如果模板中的每一项都是槽位，那它就只是一条空时间轴。

槽位名称应体现用途，而不是内容：使用 hook_clip、voiceover、hero_image，而不是 dragon_v2。每个槽位只能填入与该项媒体类型相同的文件，因此 video 项的槽位从 videos 填入，image 项从 images 填入，audio 项从 audios 填入。

文本应以 text 项保留在模板中。文本项没有槽位，因此每个变体中有所变化的文案（例如翻译后的 CTA 或不同的钩子文案）要么使用每种语言各自的模板，要么使用以每个变体为单位通过 render_text 生成的 PNG 作为图像槽位填入（参见 layer-typography）。第二种方式可以保留一个模板；使用前请检查生成的每张 PNG。

随媒体变化的时长

旁白和钩子片段在不同变体中的时长各不相同。在唯一一个应由媒体决定时长的项目上设置 is_auto_length: true：渲染时，该项目会采用与其绑定的文件的完整时长，而 duration_in_frames 仅用于在编辑器中确定其大小。自动时长区块之后的项目会根据时长变化相应移动；在区块末尾结束的项目会与它同时结束；区块内部的项目则会在新的区块末尾被截断。每个模板只能有一个项目设置此选项；如果自动时长槽位没有媒体，该项目会被移除，空隙也会闭合。其他视频和音频都不会超出各自文件的时长，因此比最长变体更短的音乐底轨会提前结束：请选用足够长的音乐。

将 max_duration_in_seconds 设为该投放位的时长上限，并检查每次渲染的时长是否超限，以免过长的旁白让 40 秒的剪辑进入 30 秒的投放位。

批量定价与渲染

首次渲染前先估算价格，并按整批定价。仅填入的文件不同、时长相同的变体，可共用一次估价，再乘以变体数量。自动时长媒体更长的变体，价格可能不同：请为每种不同的时长分别估价。报出总价；超过 20 CU 时，先等待用户明确同意。

使用 render_video_timeline 渲染每个变体，传入相同的 template 和该变体的槽位映射；按返回的间隔轮询每个 generation_id，调用 get_generation_run。传入 session_id，让整批内容都进入同一个画板。

timeline_object_id 可让渲染结果原位更新画板上的现有时间线，而不是再放置一条时间线。该工具的描述提到了 MCP 未提供的画板时间线工具会返回此 ID，因此不要尝试调用这些工具。用户提供 ID 时传入；否则省略该参数，并说明每次渲染都会在画板上新增一条时间线。不要尝试绕过此限制。

示例

“我们的 15 秒广告模板，填入三个钩子片段，每个搭配两段旁白。”

1. 每个钩子片段和旁白都来自之前的运行，并带有 file_id。徽标和字体已上传。
2. 模板为 1080 x 1920、30 fps，设置 max_duration_in_seconds: 15。轨道 1：image 徽标项目，以及覆盖最后 60 帧的 text CTA。轨道 2：一个 video 项目，设置 slot: "hook_clip"，后接固定的片尾卡。轨道 3：一个 audio 项目，设置 slot: "voiceover" 和 is_auto_length: true。轨道 4：音乐底轨，时长超过所有旁白。
3. 六个变体。两段旁白的时长不同，因此调用两次 estimate_video_timeline_price，每段旁白估价一次，再分别乘以三。报出总价；超过 20 CU 时，先等待用户同意。
4. 调用六次 render_video_timeline，传入 videos: {"hook_clip": [{file_id}]} 和 audios: {"voiceover": [{file_id}]}，并使用一个 session_id。对每个渲染结果调用 get_generation_run 轮询。
5. 按对应单元格（hook2-vo1）命名并交付每个输出；每种旁白各完整检查一个，确认 CTA 在时长变化后仍位于正确位置。

常见错误

• 所有内容都使用槽位，导致模板没有固定任何内容，变体彼此错位。
• 应使用槽位的地方硬编码 file_id，之后还要为每个变体编辑模板。
• 设置多个 is_auto_length 项目，或音乐底轨短于最长的自动时长变体。
• 自动时长媒体的时长不同时，只按一个变体估算整批价格。
• 期待 text 项目支持槽位；可变文案应使用 render_text 图片槽位，或单独使用一个模板。
• 对有严格时长限制的投放位，未设置 max_duration_in_seconds。
• 为获取 timeline_object_id 而编造画布时间线调用，而不是说明该功能缺失。