layer-motion-templates

モーションテンプレート

概要

モーションテンプレートとは、メディアアイテムで file_id の代わりに slot を指定する、1 つの render_video_timeline テンプレートです。レンダリングごとに各スロットのファイルを渡すため、40 種類のバリエーションで、同じカット、文字、トランジション、タイミングを使った 1 つのデザイン済み編集を共有でき、差し替えたメディアだけが変わります。これにより、バッチの一貫性が保たれ、結果を比較しやすくなります。

タイムラインの基本については 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 は指定しない
1 回のレンダリングでスロットを埋める	videos、images、audios マップ：{"<slot>": [{file_id}]}
ナレーションまたはクリップに長さを合わせる	そのアイテムに is_auto_length: true を指定（テンプレートあたり最大 1 つ）
レンダリングの上限を設定する	template.max_duration_in_seconds（最大 120 秒）
オプション要素	未解決のままのスロットはレンダリングから省略される
ボードのタイムラインをその場で更新する	判明している場合は timeline_object_id を指定
バリエーションの料金を見積もる	timeline_object_id 以外のすべてを指定して estimate_video_timeline_price を実行

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

テンプレートの設計

何かを作る前に、何を変えるかを決めてください。各要素は 固定（ブランドの文字、エンドカード、ロゴ、BGM、トランジション）または スロット化（フックのクリップ、ナレーション、ゲームプレイのキャプチャ、キャラクターアート）のいずれかです。可能な限りすべてを固定してください。すべてのアイテムがスロットのテンプレートは、空のタイムラインにすぎません。

スロットには内容ではなく役割に基づいた名前を付けてください：dragon_v2 ではなく hook_clip、voiceover、hero_image のようにします。各スロットには、そのアイテムと同じメディアタイプのファイルを割り当てます。つまり、video アイテムのスロットには videos、image アイテムのスロットには images、audio アイテムのスロットには audios からファイルを割り当てます。

テキストは text アイテムとしてテンプレートに残します。テキストアイテムにはスロットがないため、バリエーションごとに異なるコピー（翻訳された CTA、異なるフック文など）は、言語ごとに別のテンプレートを用意するか、バリエーションごとに render_text で作成した PNG を画像スロットに割り当てます（layer-typography を参照）。後者ならテンプレートを 1 つにできます。使用する前に、レンダリングされた各 PNG を確認してください。

メディアに合わせた長さ

ボイスオーバーとフッククリップは、バリアントごとに長さが異なります。メディアの長さを基準にするアイテムに is_auto_length: true を設定します。レンダリング時には、そのアイテムに割り当てられたファイルの全長が使われ、duration_in_frames はエディター内でのサイズのみを指定します。自動長さブロックより後のアイテムは長さの変更分だけ移動し、その末尾と同時に終わるアイテムも同時に終了します。ブロック内にあるアイテムは、新しい末尾でカットされます。テンプレートごとに設定できるアイテムは1つだけです。また、自動長さスロットにメディアがない場合、そのアイテムは削除され、空きは詰められます。ほかの動画や音声がそれぞれのファイルの長さを超えて再生されることはないため、最長のバリアントより短い音楽ベッドは途中で終わります。十分に長いものを選んでください。

max_duration_in_seconds に配置先の上限時間を設定し、各レンダリングの長さがその範囲内か確認してください。そうすれば、長すぎるボイスオーバーによって、30秒枠に40秒の動画を納品してしまう事態を防げます。

バッチの料金とレンダリング

最初のレンダリング前に見積もりを行い、バッチ全体の料金を算出します。同じ長さで、スロットに割り当てるファイルだけが異なるバリアントは、1件分の見積もりに件数を掛けて計算します。自動長さメディアがより長いバリアントは、料金が異なることがあります。その場合は、長さごとに見積もりを行ってください。合計金額を提示し、20 CU を超える場合は明示的な承諾を待ってください。

各バリアントを、そのバリアントのスロットマップと同じ template を使って render_video_timeline でレンダリングし、返された間隔で各 generation_id を get_generation_run に渡してポーリングします。バッチが1つのボードにまとまるよう、session_id を渡してください。

timeline_object_id を指定すると、レンダリングによって別のタイムラインを追加する代わりに、ボード上の既存のタイムラインがその場で更新されます。ツールの説明では、MCP が公開していないボードタイムラインツールからこの ID を取得するよう案内されています。そのため、それらのツールを呼び出そうとしないでください。ユーザーから ID が提供された場合は渡し、そうでなければ各レンダリングでボードに新しいタイムラインが追加されることを伝えてください。回避策を試みないでください。

実例

「15秒の広告テンプレートに、3つのフックとそれぞれ2つのボイスオーバーを割り当てます。」

1. すべてのフッククリップとボイスオーバーは以前の実行で作成されており、file_id が付いています。ロゴとフォントはすでにアップロード済みです。
2. テンプレートは1080 x 1920、30 fps、max_duration_in_seconds: 15 です。トラック1にはロゴの image アイテムと、最後の60フレームに表示する text CTA があります。トラック2には slot: "hook_clip" の video アイテムと、その後に固定のエンドカードがあります。トラック3には is_auto_length: true の slot: "voiceover" を持つ audio アイテムがあります。トラック4は音楽ベッドで、どのボイスオーバーよりも長くします。
3. バリアントは6つです。2つのボイスオーバーは長さが異なるため、estimate_video_timeline_price でそれぞれ見積もりを行い、各金額に3を掛けます。合計金額を提示し、20 CU を超える場合は承諾を待ってください。
4. videos: {"hook_clip": [{file_id}]} と audios: {"voiceover": [{file_id}]} を指定して render_video_timeline を6回呼び出し、すべてに同じ session_id を渡します。それぞれを get_generation_run でポーリングします。
5. 各出力に対応するセル（hook2-vo1）を付けて名前を記載し、各ボイスオーバーから1つずつ最初から最後まで確認して、長さのずれの後も CTA が適切な位置に残っていることを確かめます。

よくある間違い

• すべてをスロットにしてしまい、テンプレートで何も固定されず、バリアントごとに構成が変わってしまう。
• スロットを使うべきところで file_id を直接固定し、バリアントごとにテンプレートを編集する。
• is_auto_length を複数のアイテムに設定する、または最長の自動長さバリアントより短い音楽ベッドを使う。
• 自動長さメディアの長さが異なるのに、1つのバリアントだけでバッチの料金を見積もる。
• text アイテムにスロットを設定できると思い込む。コピーを変えるには、render_text の画像スロットを使うか、独自のテンプレートを作成します。
• 長さの上限が厳密な配置先なのに、max_duration_in_seconds を省略する。
• timeline_object_id を取得するために存在しないキャンバスタイムライン呼び出しを考案するのではなく、その機能が利用できないことを伝える。