/video-compose

name: video-compose
description: Generates and prompts video clips on the filmmaking canvas. Use when the user asks to generate, render, animate, continue, restyle, edit, shoot, or compose a video clip; render script or shot notes as video; animate a storyboard, starting frame, image, character, location, or reference; use image, video, audio, storyboard, starting-frame, or voice refs; compose an ad, brand film, product promo, music-video shot, or video sequence; or before calling generate_video.js. Owns video CLI flags, refs, prompt construction, audio-ref handling, and video-specific failure hints.

Intent dispatcher. Patterns name trigger, call, edges, and prompt reference.

Hard defaults

• Stage by default per `PROJECT_AGENT.md`.
• Audio on by default; pass `--no-audio` only for explicit silent/no-audio requests. Trailer/portrait/cinematic framing is NOT a trigger; audio is the baseline, not optional polish.
• Reference-to-clip default: use available character/variant/location/voice refs directly. Storyboard only if requested, hard to control, or needed for diagnosis.
• Preserve scripted dialogue/VO exactly unless the user asks for rewrite.

First-use video mode

For the ask-once flow and per-mode prices, see the project `PROJECT_AGENT.md` § "First-use generation choices". Pass `--resolution` only for `480p Draft` or `1080p Final`.

CLI shape

node "$PAI_REPO_ROOT/server/cli/generate_video.js" --prompt "..." [--version <2.0|2.5>] [--duration <seconds>]
  [--aspect-ratio 16:9] [--resolution <480p|720p|1080p>] [--no-audio]
  [--label "..."] [--ref-source-id <id> ...] [--ref-audio-source-id <audio_id> ...]
  [--source-node-id <id>] [--shot-id <N>]

Calls go via `--stage` — see the project `PROJECT_AGENT.md` § "Draft gate".

`--label` defaults to truncated prompt. Use `--ref-source-id` for image/video refs, `--ref-audio-source-id` for audio refs, and `--source-node-id` for the authoring note. Mirror external URLs first. Do not set `--shot-id` during speculative/partial generation unless user asks for a reel position; story sequences assign Timeline order after planned clips land.

Match stated single-clip duration with `--duration`; omit for 15s default. Split or chain >15s totals.

Each clip costs real money even after staging — only stage after the user has explicitly asked for a video.

Model version (`--version`)

Omit it for `2.0` (today's model): output 4-15s, priced per output second by resolution.

`--version 2.5` renders PAI Video 2.5. Differences that change how you call it:

• `--duration` is 5-30 (not 4-15). `-1` (follow-the-input edit mode) is rejected.
• `--resolution` must be `480p`, `720p`, or `1080p`; `--aspect-ratio` must be one of

`16:9 | 9:16 | 4:3 | 3:4 | 1:1 | 21:9 | adaptive`.

• One flat price per **billed-duration tier**, where billed = output seconds + every

reference-video second (each clip measured locally with ffprobe and rounded up). Hard cap 60 billed seconds; over that the CLI refuses before staging and names both halves. Tier prices are in the project `PROJECT_AGENT.md` § "Media CLIs (`server/cli/`)" — quote them from there, never from memory.

• Refused inside an Auto run (the run's budget estimate is computed from 2.0 rates).

Stage 2.5 clips outside Auto.

• A 2.5 job carrying video references needs `ffprobe` on the host; without it the CLI

fails with `infra` rather than guessing a price.

On failure the `limits` blob is model-scoped: read `min_output_sec` / `max_output_sec` and `max_billed_sec` off the returned JSON rather than assuming 2.0's numbers.

Reference caps

**2.0 (`video-generation`)** — ≤9 image refs, ≤3 audio refs, ≤3 video refs; video refs cap at **15s aggregate**.

**2.5** — ≤30 image refs, ≤10 audio refs, ≤10 video refs; reference video caps at **30s aggregate**, and every reference second also counts toward the 60s billed-duration cap.

Both: audio/video refs must be **1.8s-15.2s each** (the shared reference-upload step's window), and audio refs need an image or video anchor — on 2.5 that one is checked only after credits are frozen, so the CLI refuses it locally. Read durations from `workflow.json`; on failure use the returned `limits` + `sent`, which are model-scoped.

Reference roles — vocabulary

Prompt wording binds each ref role:

| Role | Flag | Wording in prompt | |---|---|---| | Character identity | `--ref-source-id` (image) | "the character in @Image1" | | Location / setting | `--ref-source-id` (image) | "the location shown in @Image1" | | Opening frame | `--ref-source-id` (image) | "opening frame @Image1, …" | | Closing frame | `--ref-source-id` (image) | "closing on the frame from @Image1" | | Source clip — continue (next clip in a chain) | `--ref-source-id` (video) | **Default = hard cut:** "Hard cut from @Video1: open on a NEW camera angle; do not match its final frame." Same-shot ("Continue from @Video1 … maintain camera position") only for an authored held beat / oner / explicit user request — see [`references/video-extension.md`](references/video-extension.md) | | Source clip — transform | `--ref-source-id` (video) | "Re-render @Video1 in …" | | Camera-move source | `--ref-source-id` (video) | "camera moves match @Video1" | | Action source | `--ref-source-id` (video) | "action choreography matches @Video1" | | VFX template | `--ref-source-id` (video) | "use the visual-effects template from @Video1" | | Voice / timbre anchor | `--ref-audio-source-id` | "Use @Audio1 as voice/timbre reference. Speak once, no echo." |

Prompt-language conventions

• Ref syntax: `@Image1` / `@Video1` / `@Audio1`, positional by flag order. Every `@ImageN`/`@VideoN`/`@AudioN` MUST have a matching `--ref-source-id`/`--ref-audio-source-id` flag — the CLI rejects a mismatch (`bad_args`) before generating. Mentioning the same ref many times is fine; only the highest index per kind needs a flag.
• Spoken text: include script/shot/user dialogue/VO verbatim; do not summarize, translate, shorten, polis