Knowledge & tools

Compose Media tool

The Compose Media tool (compose_media) assembles finished media from parts the agent already has - it stitches clips into platform-ready MP4s, renders text cards, builds carousel slide sets, and grabs frames. It never generates content with AI: feed it URLs from the stock tools or the generate actions, get back public /media/... URLs ready to hand to a publishing tool.

The distinction matters for cost: generation (an AI model making an image, video or voiceover) is billed per model, while composition is local assembly and costs only the standard flat tool fee - stitching ten clips into a Reel costs the same as one tool call.

No setup. There's no API key and no config form - just assign the tool to an agent on its Tools tab and it's ready. It isn't in the default toolset, so it does need assigning.

The Reels pipeline

The typical flow is three tool calls in one run:

Find footage - Pexels or Pixabay video search returns direct MP4 links (or the generate actions produce clips/images/voiceover).
Compose - compose_video stitches the clips, adds captions and music, and returns one /media/{id}.mp4 URL.
Publish - a publishing tool (Instagram, Facebook, etc.) takes that URL.

The same pattern works for image content: compose_image for a single quote/announcement card, compose_slides for a carousel.

Actions (4)

Action	Purpose	Key inputs	Returns
`compose_video`	Stitch clips into a platform-ready MP4	`clips[]` (video/image URLs + trim), `output` (reel/square/portrait/landscape), `fill_mode` (blur/pad/crop), `transition` (none/fade), `overlays[]`, `captions[]` (static/karaoke), `voiceover_url`, `music_url`	one `/media/{id}.mp4` URL + duration/dimensions/size
`compose_image`	One text card	`heading`/`body`/`footer`, background color/gradient/image, `text_color`, `image_format`	`/media/{id}.png` (or `.jpg`)
`compose_slides`	2–12 cards in one call	`slides[]` of card specs	ordered list of URLs (carousel-ready)
`extract_frame`	Frame grab from a video	`url`, `at` seconds	`/media/{id}.jpg`

All parameters are chosen by the agent per call - there's nothing to configure ahead of time.

Canvas & formats

Video output - H.264/AAC with faststart, encoded to Meta's Reels spec. output picks the canvas: reel (1080×1920, the default), square, portrait, landscape.
fill_mode - what happens when a clip doesn't match the canvas: blur (blurred copy fills the gaps - the familiar Reels look), pad, or crop.
Images as clips - a still image in clips[] becomes a 4-second segment with a gentle Ken Burns move, so photo-only Reels work fine.
Cards - compose_image/compose_slides default to 1080×1350 (the portrait feed size); image_format adjusts it.

Captions & overlays

Text overlays and captions are placed inside Meta's official 9:16 safe zone automatically, so nothing lands under the UI chrome. Captions come in two styles:

static - a line shown for a time window.
karaoke - words light up one by one across each line's time window. There's no transcript upload; the agent supplies the line timings (it knows them from the voiceover script it wrote).

Audio

Pass voiceover_url and/or music_url and the mix is handled: music loops or trims to fit the video length, ducks under the voiceover automatically, and the final mix is normalized to −14 LUFS (the loudness social platforms expect).

Limits

Output duration 3–120 seconds; up to 10 clips per video; 2–12 slides per carousel.
Inputs must be public URLs (private/internal addresses are refused), up to 300 MB each.

One render at a time. Video composition runs one render per workspace at a time - a second concurrent request gets a clean "another video is currently rendering" message and the agent simply retries. Expect this if two agents produce video simultaneously.

Errors

Validation problems (a bad hex color, too many clips, duration out of range, a clip too short for its fade, "cannot render in the remaining time") come back as plain messages the agent corrects and retries on its own - they're not operator-facing failures. A genuine render failure surfaces as rendering failed: ... with the specific technical reason, which is the thing to look at if a run's tool card shows an error.

Classification & lifecycle

Composition is non-destructive and sends nothing to external services, so the safety classification flags ship unset. It's post-call-hook eligible, so a post-call flow can assemble media too.