Video tools

create_video_from_script

Create a narrated video from a script: synthesizes an AI voiceover, then runs the b-roll/captions/graphics pipeline to build the cut. Safe to call while the script is still generating — it waits for the text. Returns a job_id once synthesis is done (~10-60s); the cut keeps building in the background and is finished when its live state says PLANNED, at which point it plays in the chat and you can change it with edit_video. It does NOT render a downloadable file — only the user does that, with the Render button on the card. Settings omitted fall back to the user's saved defaults. Use this when the user wants the AI to narrate; use prepare_recording_handoff when they want to be on camera. Confirm with the user before calling.

Parameter	Type	Description
script_id required	string
aspect_ratios	string[]	Output aspect ratios, e.g. ["9:16"] for TikTok/Reels, ["16:9"] for YouTube/LinkedIn.
video_type	string	"long-form" for one video, "both" to also cut short clips. One of: long-form, both.
clips	object	Short-clip settings (only meaningful with video_type=both).
captions_enabled	boolean	Burn in captions (default true).
caption_preset	string	Name or id of one of the user's saved caption presets.
brand_kit	string	Name or id of one of the user's saved brand kits (logos + graphics theme).
broll_enabled	boolean	Layer stock b-roll under the narration.
broll_source	string	Stock footage source: pexels or pixabay.
broll_custom_files	object[]	The user's own footage/stills to cut away to, layered in alongside (or instead of) stock. Clips the user uploaded in this conversation are attached automatically — only pass this to override that set.
use_article_images	boolean	Whether to cut to the photos published with the source article. Defaults to true — they are attached automatically, so only pass false when the user asks for stock footage only.
video_context	string	Extra context for the editing agents (topic, vibe, audience).
music_enabled	boolean
graphics_enabled	boolean	Animated graphics overlays (quote cards, stats).
voice_id	string	ElevenLabs voice id for the narration (see list_voices).

This plans the video; it does not render it

The job stops at planned: the manifest exists and is watchable, but no MP4 has been encoded. That is deliberate — encoding before anyone has seen a frame buys nothing, and the first edit throws it away.

So status: "planned" is a success, not a stall. Rendering is a separate, explicit action taken in the web app. An agent that waits for a URL to appear will wait forever.

The usual sequence

1. generate_script → script_id

2. create_video_from_script → job_id

   You can call this while the script is still generating; it waits for the text rather than failing.

3. get_generation_status until the job reports planned

4. get_video_edit_state → the ids you need to change anything

5. edit_video → apply the changes

get_generation_status

Batch-check progress of script generations and/or video jobs. Videos report stage + progress while running and the final video URL when rendered.

Parameter	Type	Description
script_ids	string[]
job_ids	string[]

Takes both scripts and videos in one call, so a client tracking several things polls once rather than per item. Both lists are capped at 25.

list_recent

List the user's recent scripts or videos — for requests like "make a video from my last script".

Parameter	Type	Description
type required	string	One of: scripts, videos.
limit	number	Max rows (default 5, cap 20).

prepare_recording_handoff

When the user wants to appear on camera themselves (record & auto-edit), hand off to the recording flow: returns a link into the teleprompter/video wizard preloaded with their script. The recording itself happens in the app UI, not in chat.

Parameter	Type	Description
script_id	string	Script to load into the teleprompter (optional — omit for freestyle).

Returns a link into the teleprompter with the script already loaded. This is the route for “I’ll record this myself” — MCP can’t drive a camera, so the handoff is a URL you give the user.

suggest_video_templates

Show the user the fixed video formats (layout templates) a script can be turned into — each one is a shape the pipeline assembles the same way every time, with a live preview of the layout. Every template needs the user on camera: picking one opens its builder with the script already loaded, and they record from there. Use it when they ask what formats/layouts/looks are available, when they want to be on camera and a set shape would suit, or alongside the AI-voiceover offer once a script is written. Pass template_ids to show only the ones you're recommending. Purely a suggestion — the user picks by tapping a card, so never say you've chosen or started one.

Parameter	Type	Description
script_id	string	The script to load into the template builder. Omit only if there is no script yet.
template_ids	string[]	Narrow the card to specific templates. Omit to show the whole catalogue.

Shows the fixed-layout catalogue as a picker. Each entry carries a link that opens the template flow with the script attached.

Suggesting is not choosing

This tool offers layouts; it doesn’t select one. The link opens the flow and stops on its first step, which is also where the user says whether they’re recording or uploading — a decision the agent isn’t in a position to make.

See the layout template reference for what each shape does.