layer-motion-templates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Layer Motion Templates

Overview

概述

A motion template is one

render_video_timeline

template whose media items name a

slot

instead of a

file_id

. Each render passes the files for those slots, so forty variants share one designed edit: the same cuts, type, transitions and timing, with only the swapped media changing. That is what keeps a batch consistent and its results comparable.

Timeline basics are in

layer-video-timeline

, designed motion in

layer-motion-graphics

. The matrices that decide which variants to make are in

layer-ua-creatives

and

layer-localization

If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add layerai/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

动效模板是一个

render_video_timeline

模板，其中媒体项指定

slot

而不是

file_id

。每次渲染都会传入这些槽位对应的文件，因此四十个变体可以共享同一条设计好的剪辑：剪辑点、字体排版、转场和时间安排完全相同，仅替换的媒体发生变化。这正是保证批量结果一致且可比较的关键。

时间线基础见

layer-video-timeline

，已设计的动效见

layer-motion-graphics

。决定要生成哪些变体的组合矩阵见

layer-ua-creatives

和

layer-localization

。

如果此处引用的某个同级 skill 不在可用 skills 中，请让用户安装（

npx skills add layerai/skills --skill <name>

）；在无人值守模式下，则依据工具 schema 继续执行，并标记该缺失项。

Quick reference

快速参考

Need	Field
A swappable clip, image or sound	`slot: "<name>"` on a `video` , `image` or `audio` item, with no `file_id`
Fill the slots for one render	`videos` , `images` , `audios` maps: `{"<slot>": [{file_id}]}`
Let a voice-over or clip set length	`is_auto_length: true` on that one item (at most one per template)
Cap the render	`template.max_duration_in_seconds` (up to 120)
An optional element	A slot left unresolved is omitted from the render
Update the board timeline in place	`timeline_object_id` , when one is known
Price a variant	`estimate_video_timeline_price` with everything but `timeline_object_id`

render_video_timeline

takes

{workspace_id, template, videos, images, audios}

template

{width, height, fps, tracks: [{id, name, items, transitions}]}

; an item is

{id, type, start_frame, duration_in_frames}

plus

file_id

slot

, and optionally

layout {left, top, width, height}

effects

start_from_in_seconds

to trim a clip's head, and

volume

; a

solid

takes

color

{red, green, blue, alpha}

. The render returns a

generation_id

for

get_generation_run

. Slot maps are keyed by slot name:

audios: {voiceover: [{file_id}]}

需求	字段
可替换的视频片段、图片或音频	在 `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` （当已知该 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}]}

；每个 item 的结构为

{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}]}

。

Designing the template

设计模板

Decide what varies before building anything. Every element is either fixed (brand type, end card, logo, music bed, transitions) or slotted (the hook clip, the voice-over, the gameplay capture, the character art). Fix everything you can: a template where every item is a slot is just an empty timeline.

Name slots for their role, not their content:

hook_clip

voiceover

hero_image

, not

dragon_v2

. Each slot resolves to a file of the item's own media type, so a

video

item's slot is filled from

videos

, an

image

item's from

images

, an

audio

item's from

audios

Text stays in the template as

text

items. A text item has no slot, so copy that changes per variant (a translated CTA, a different hook line) is either a separate template per language or an image slot filled with a

render_text

PNG made per variant (see

layer-typography

). The second keeps one template; check every rendered PNG before it goes in.

在开始构建之前，先确定哪些内容会发生变化。每个元素要么是固定的（品牌字体排版、尾卡、Logo、音乐铺底、转场），要么是可填充的（hook 片段、配音、游戏录屏、角色素材）。尽可能固定所有内容：如果一个模板中的每个 item 都是槽位，那它就只是一条空白时间线。

应根据槽位的用途命名，而不是根据具体内容命名：使用

hook_clip

、

voiceover

、

hero_image

，不要使用

dragon_v2

。每个槽位都会解析为与该 item 媒体类型相同的文件，因此

video

item 的槽位从

videos

填充，

image

item 的槽位从

images

填充，

audio

item 的槽位从

audios

填充。

文本应作为

text

item 保留在模板中。text item 不支持槽位，因此每个变体中会变化的文案（翻译后的 CTA、不同的 hook 文案）要么为每种语言使用单独的模板，要么使用图片槽位，并为其填充每个变体单独生成的

render_text

PNG（见

layer-typography

）。第二种方案可以保留单一模板；将每个渲染出的 PNG 放入槽位前都要逐一检查。

Length that follows the media

随媒体变化的长度

Voice-overs and hook clips differ in length per variant. Set

is_auto_length: true

on the one item whose media should decide: at render it takes the full length of the file bound to it, and

duration_in_frames

only sizes it in the editor. Items after the auto-length block move by the change in length, items ending at its end end with it, and items inside it are cut at its new end. Only one item per template may set it, and an auto-length slot left without media is removed and the gap closes. Other video and audio never play past their own file's length, so a music bed shorter than the longest variant ends early: pick one long enough.

Set

max_duration_in_seconds

to the placement's limit, and check each render's length against it, so an overlong voice-over does not ship a 40-second cut to a 30-second slot.

不同变体中的配音和 hook 片段时长各不相同。在应由媒体决定时长的那个 item 上设置

is_auto_length: true

：渲染时，它会采用绑定文件的完整时长，而

duration_in_frames

仅用于在编辑器中确定其尺寸。自动长度区块之后的 item 会随长度变化而移动，以该区块结尾的 item 会随之结束，位于该区块内部的 item 则会在新的结尾处被截断。每个模板最多只能有一个 item 设置该选项；如果自动长度槽位没有媒体，该 item 会被移除并闭合空隙。其他视频和音频的播放时长不会超过各自文件的长度，因此如果音乐铺底短于最长变体，就会提前结束：请选择足够长的音乐。

将

max_duration_in_seconds

设置为广告位的时长限制，并检查每次渲染的时长，确保过长的配音不会导致 40 秒的剪辑被放入只能容纳 30 秒的广告位。

Pricing and rendering a batch

批次估价与渲染

Estimate before the first render, and price the batch as a whole. Variants that differ only in which files fill the slots, at the same length, share one estimate times their count. A variant whose auto-length media is longer can price differently: estimate each distinct length. Present the total; above 20 CUs wait for an explicit yes.

Render each variant with

render_video_timeline

, the same

template

, and that variant's slot maps; poll each

generation_id

with

get_generation_run

at the returned interval. Pass

session_id

so the batch lands on one board.

timeline_object_id

makes a render update an existing board timeline in place rather than placing a second one. The tool description sources the id from board-timeline tools that MCP does not expose, so do not try to call them. Pass the id when the user supplies it, otherwise omit it and say that each render adds a new timeline to the board. Do not try to work around it.

首次渲染前先进行估价，并将整个批次作为整体估价。仅槽位所填文件不同且长度相同的变体，可以共用一个估价结果，再乘以变体数量。如果某个变体的自动长度媒体更长，其价格可能不同：请按每种不同长度分别估价。给出总价；如果超过 20 CUs，需等待用户明确同意。

使用

render_video_timeline

、同一个

template

和各变体的槽位映射分别渲染每个变体；按照返回的间隔，使用

get_generation_run

轮询每个

generation_id

。传入

session_id

，使整个批次落在同一个看板上。

timeline_object_id

可让渲染原地更新现有看板时间线，而不是再放置一个副本。工具说明提到该 ID 来自 MCP 未暴露的看板时间线工具，因此不要尝试调用这些工具。用户提供该 ID 时应传入，否则省略，并说明每次渲染都会在看板上新增一条时间线。不要尝试绕过这一限制。

Worked example

实例

"Our 15-second ad template, filled for three hooks and two voice-overs each."

Every hook clip and voice-over came from earlier runs and carries a
```
file_id
```
. The logo and font are already uploaded.
Template at 1080 x 1920, 30 fps,
```
max_duration_in_seconds: 15
```
. Track 1: the logo
```
image
```
item and a
```
text
```
CTA over the last 60 frames. Track 2: a
```
video
```
item
```
slot: "hook_clip"
```
, then the fixed end card. Track 3: an
```
audio
```
item
```
slot: "voiceover"
```
with
```
is_auto_length: true
```
. Track 4: the music bed, longer than any voice-over.
Six variants. The two voice-overs differ in length, so
```
estimate_video_timeline_price
```
twice, once with each, and multiply each by three. Present the total; above 20 CUs wait for a yes.

Six

render_video_timeline

calls with

videos: {"hook_clip": [{file_id}]}

and

audios: {"voiceover": [{file_id}]}

, one

session_id

. Poll each with

get_generation_run

Name and hand back each output against its cell (
```
hook2-vo1
```
), and watch one per voice-over end to end to confirm the CTA still lands after the shift.

"我们的 15 秒广告模板，要针对三个 hook 和两个配音分别进行填充。"

每个 hook 片段和配音都来自之前的生成任务，并带有
```
file_id
```
。Logo 和字体已经上传。
模板尺寸为 1080 x 1920、30 fps，并设置
```
max_duration_in_seconds: 15
```
。轨道 1：Logo 的
```
image
```
item，以及覆盖最后 60 帧的
```
text
```
CTA。轨道 2：一个
```
video
```
item
```
slot: "hook_clip"
```
，然后是固定尾卡。轨道 3：一个
```
audio
```
item
```
slot: "voiceover"
```
，设置
```
is_auto_length: true
```
。轨道 4：音乐铺底，长度长于任何配音。
共六个变体。两个配音的时长不同，因此调用
```
estimate_video_timeline_price
```
两次，每次使用一个配音，并将每个估价结果乘以三。给出总价；如果超过 20 CUs，需等待用户同意。

调用六次

render_video_timeline

，使用

videos: {"hook_clip": [{file_id}]}

和

audios: {"voiceover": [{file_id}]}

，并使用同一个

session_id

。使用

get_generation_run

轮询每次生成任务。

针对每个单元格（
```
hook2-vo1
```
）命名并交回相应输出，并为每种配音完整观看一个成片，确认偏移后 CTA 仍能落在预期位置。

Common mistakes

常见错误

Slotting everything, so the template fixes nothing and variants drift.
Hard-coding a
```
file_id
```
where a slot belongs, then editing the template per variant.
More than one
```
is_auto_length
```
item, or a music bed shorter than the longest auto-length variant.
Pricing a batch from one variant when the auto-length media differs in length.
Expecting a slot on a
```
text
```
item; varying copy is a
```
render_text
```
image slot or its own template.
Omitting
```
max_duration_in_seconds
```
for a placement with a hard length limit.
Inventing a canvas-timeline call to get
```
timeline_object_id
```
instead of reporting the gap.

将所有元素都设为槽位，导致模板没有固定任何内容，变体随之出现偏差。
在本应使用槽位的位置硬编码
```
file_id
```
，然后为每个变体单独编辑模板。
设置多个
```
is_auto_length
```
item，或让音乐铺底短于最长的自动长度变体。
自动长度媒体的时长不同时，仍只按单个变体为整个批次估价。
期待
```
text
```
item 支持槽位；要让文案变化，应使用
```
render_text
```
图片槽位或单独模板。
对有硬性时长限制的广告位遗漏
```
max_duration_in_seconds
```
。
自行虚构 canvas-timeline 调用以获取
```
timeline_object_id
```
，而不是说明该能力缺失。