MCP tool reference: all 82 tools and their parameters

create_video Create video from web page

[40 credits] [paid plans: + 40 per AI still unless ai_mode none; dry_run quotes] Turns a public web page into a narrated, captioned video. Spends credits unless draft:true: draft first and ask before a paid render; to only check a page, use inspect_page. PageToVid posts nowhere: the user gets an MP4, captions and a share page to publish themselves. Asynchronous (minutes, sometimes past fifteen): returns a receipt with the video_id at once; get_video for the full status. A page behind a login is filmed only with a capture session from the VS Code or browser extension (Scale plan and up).

destructive · openWorld

create_animation Create an animated video from your own content

[40 credits] From content you hold (figures, notes, story), no URL. You write scenes; each drawn, voiced, captioned (list_motions: 25 visuals, some with kinds; visual "rushie" = 964 designed cards, e.g. data {rushie:{template:"end-card",props:{headline,mark,url,cta}}}). AI clips (paid plans) only if asked: data.generate (+data.clip) per scene, or ai_mode rich (assist: stills), the server picks scenes, writes prompts; dry_run shows ai_plan.added. Returns a receipt; get_video for the full status.

destructive

cancel_video Stop a render and get the credits back

[Free] Stops a running render and refunds its render credit and any AI visual still in flight; AI visuals already made stay (reused free). Use it when get_storyboard shows a plan you do not want. A finished render cannot be cancelled. The video is marked cancelled at once; the worker stops at its next step.

destructive · idempotent

get_video Get video status and links

[Free] Reads this account. The full status of a render: phase and progress while it runs (with poll_after_seconds), then the files, length, credits, warnings and quality; on a free film, `upgrade` to relay once. `status` is one of, in pipeline order: draft, queued, analyzing, scripting, recording, voicing, rendering, held, done, error. In flight, so poll again after poll_after_seconds: queued, analyzing, scripting, recording, voicing, rendering. Terminal, so stop polling: held, done, error — a cancelled render ends as error with the reason in `error`, and a film can be done and still carry warnings. held: finished but unpublished by quality_gate. draft has not been queued.

readOnly · idempotent

release_video Publish a held video

[Free] Publishes a video its quality_gate held (status "held") as it is: status becomes done. Nothing is re-rendered.

destructive · idempotent

get_video_embed Get embed and SEO tags for a video

[Free] Returns ready-to-paste markup for a finished PageToVid video: an HTML video element, Open Graph and Twitter player meta tags so the page unfurls as a playable video, and a schema.org VideoObject JSON-LD block.

readOnly · idempotent

list_models List generation models and prices

[Free] Every model this account can generate clips and stills with — capabilities, limits and the exact credit price — before spending anything. Omit model in a scene for the house clip; name one (data.model, or set_inset model) to choose it and pay its price. quote_cost prices a specific request.

readOnly · idempotent

quote_cost Quote a cost before spending

[Free] What something will cost, spending nothing: one generation (kind clip or image, optional model, duration_s, resolution, role, count), or a video_id's next rerender_video (render plus every AI visual not yet made). A length between two a model makes is rounded UP, with a warning; one it cannot make is refused with what it can. plan_note says when this plan has no AI generation.

readOnly · idempotent

list_video_options List available video options

[Free] Lists what create_video accepts: goals, aspect ratios, languages, voices, background music beds (9, each with a family: calm, energetic, serious, playful) and the allowed length range. Static reference data — no account access.

readOnly · idempotent

list_motions List animation styles

[Free] How a scene can look: 26 visuals, 1129 animations, motions, transitions, fx. Check pairs before writing scenes. New: get_motion_grammar.

readOnly · idempotent

list_themes List theme presets and the rules a theme must satisfy

[Free] Lists what the theme parameter accepts: the built-in presets, the modes, the type faces the renderer can load, and the contrast and palette rules enforced before a credit moves. Static reference data.

readOnly · idempotent

inspect_page See what is on a page worth filming

[Free] Use this, not web browsing, to check a page: it sees what the recorder will. Creates nothing; then ask. Opens a public page in a real browser and ranks what a video could film — calls to action, images, cards, search boxes, headings — each with a CSS selector, kind, size and a ranking score. Says when a robot check, sign-in or missing page stood in front of it (blocked, block_kind), and which fields will never be typed into.

readOnly · idempotent · openWorld

detect_brand Read a site's colours and typography

[Free] Reads a public page's design tokens from its live CSS: accent colours, heading typeface, light or dark ground, corner style. Returns a theme ready for create_video, create_animation or rerender_video, plus any site colour the film cannot paint with and why.

readOnly · idempotent · openWorld

get_account Get plan and credit balance

[Free] Reads this account. CALL THIS FIRST: plan, credits, whether AI visuals are available and charged, watermark, revisions, film passes, add-on clips, renders running, limits. Then: inspect_page (in the aspect you will film), create_video or create_animation, get_storyboard (the chosen shots), update_storyboard, rerender_video.

readOnly · idempotent

list_videos List videos on this account

[Free] Reads this account. Lists videos newest first with their status and, when finished, their links. Filter by status or by a word in the page URL or title. Returns a cursor when more remain.

readOnly · idempotent

get_storyboard Get the scenes of a video

[Free] Reads this account. Returns the scene-by-scene plan of a video: what each scene narrates, its on-screen caption, how long it holds, and whether it is real footage of the page or a motion graphic (and which motion).

readOnly · idempotent

update_storyboard Edit the scenes of a video

[Free] Edits a video's storyboard in 24 operations, each described on its branch: words, captions, visuals (incl. "rushie" designed cards: data.rushie {template, props}), data, shots, scenes, transitions, fx, presenter, voice, music, look. Does not re-render — rerender_video makes the new film. Every call is snapshotted, so an edit can be undone (list_revisions).

rerender_video Re-render a video from its storyboard

[40 credits] [free: captions_only once per paid render, then 10 credits; a missed length target once] A new film from the video's current storyboard, without re-planning, plus any AI visual not yet made (quote_cost prices it). Free once per video when the film missed its length target (length_within_tolerance: false). The file is replaced when the new render finishes. Returns a start receipt; call get_video for the full status.

destructive · openWorld

translate_video Translate a video into other languages

[40 credits] per language: a NEW video from an existing one — same storyboard and pictures, narration translated, re-voiced and re-captioned, card text (rushie cards too) translated. Filmed scenes are re-recorded on the site's page in that language when it has one (hreflang), else the footage is reused and `scenes` says so. Charged and refunded like any render; AI visuals already made are reused free.

destructive · openWorld

get_site_plan Get the video plan for a whole site

[Free] Up to 5 ranked videos a site should have, one per subject: goal, pitch, the real page it films (checked), the video made; detail full adds the brief, sources and shots. First call generates it (~10-20 s, no credit), then banks the site's images, videos and page clips in the background (media counts them). generate_site_videos works from it.

idempotent · openWorld

generate_site_videos Make the videos a site's plan asks for

[40 credits] Per video started. One filmed video per get_site_plan idea without one (or the idea_ids given), of its verified page with its sourced brief as focus. Without confirm it lists what it would make and the cost, capped at the balance (the rest under needs_credits), creating nothing; confirm=true starts those. get_video reports each. A retry never starts an idea twice.

openWorld

create_show Create a show: a recurring video from a feed

[Free] A show makes a video from each new item in a feed: a weekly release video from a changelog, a daily listing video from an RSS feed, a clip per new post. Episodes are ordinary videos made by run_show or, once confirmed, by the scheduler at the show's cadence. A new show is HELD: nothing renders until its owner has called run_show once with confirm=true, and it never spends more than max_credits_per_day.

openWorld

list_shows List shows

[Free] Reads this account. Lists the shows on this account — or one site's — with their cadence, caps, whether each is confirmed or still held, what it spent today, and its five most recent episodes with the video each became.

readOnly · idempotent

run_show Run a show now

[40 credits] Per episode started. Reads the show's feed (or the items given), skips items already made, and — within max_episodes_per_run and max_credits_per_day — starts one video per new item. Without confirm: the list, nothing spent. On a held show, confirm=true is the owner's one-time approval: it makes the episodes and lets the scheduler run the show from then on.

openWorld

update_show Pause, resume or retune a show

[Free] Changes a show's switch, cadence, caps or name, or moves it to another format or format version. The template itself is edited with update_format, which writes a new version and leaves every episode already made where it is. Nothing is rendered.

idempotent

create_format Create a format: the reusable shape of a programme

[Free] A format is how an episode is made — aspect, language, voice, music, tone, goal, length, cards, brand, theme, the brief or the scene templates — and knows nothing about any subject. It is versioned: update_format writes a new version, shows pin one or follow latest, and every episode records the version that made it. Validated now against a sample item; nothing is rendered.

update_format Revise a format: writes a new version

[Free] Changes any of a format's template fields. The result is a NEW version — the previous ones stay exactly as they were, and every episode already made keeps the version that made it. Shows following latest use the new version from their next run; pinned shows do not move until update_show moves them. Validated whole before anything is written.

destructive

get_format Read a format and its versions

[Free] The format's current template, its version history and the shows that run it, with each show's pin.

readOnly · idempotent

list_formats List formats

[Free] The account's formats, newest change first, with versions and the shows running each.

readOnly · idempotent

fork_format Copy a format

[Free] A new format whose version 1 is the original's latest version, unpinned from its parent. Edit the copy without touching the original.

validate_format Validate a format against a sample item

[Free] Compiles the template against a sample item, touching no database or feed: the catalogue checks (voice, music, language, theme…), the scene templates filled and checked as an animation, and what the first episode's title, brief and scene count would be. Returns problems by field; nothing is created, rendered or charged.

readOnly · idempotent

preview_episode Preview one episode of a format, for free

[Free] Runs the format's resolvers against the item (real calls, cached) and compiles the storyboard: every beat's final text, the beats dropped and why, the integrity report and where every bound value came from. Nothing is rendered. Read it before run_show confirm=true.

readOnly · idempotent · openWorld

verify_episode Verify what a video says against its record

[Free] The proof behind a film: the format version that made it (template SHA-256), every resolver source and what it fetched, the integrity report, the claim ledger (which figures trace to the page, the brief or nothing), the Content Credentials (C2PA), and a check recompiling the stored data against the narration word for word.

readOnly · idempotent

register_mcp_connection Name an upstream server for resolvers

[Free] Stores a connection under an alias — the URL and, optionally, a credential kept encrypted on this account — and REPLACES the alias if it already exists, which changes what every format naming it will call on its next run. This tool itself calls nothing: a format's resolvers use the connection only when preview_episode or run_show runs it. Formats refer to the alias only, so a format never carries a secret and is safe to publish or fork. Nothing is called now.

destructive · idempotent

create_character Create a reusable character for consistent clips

[Free or 40 credits] Names a character so generated clips that name it keep one identity. refs (1 to 3 image URLs on this account) is free; a generate prompt DRAWS the reference (paid plans, refunded on failure). Then an image scene's data.clip=true and data.character="<name>". From one of your films take raw_frame_url, never thumbnail_url: its burnt-in text teaches the generator to draw text.

idempotent

list_characters List the account's characters

[Free] The reusable characters on this account, each with its reference images and description.

readOnly · idempotent

list_commons_assets Browse the asset commons

[Free] Media people shared from their banks for anyone's films — logos, product shots, illustrations, recorded flows — with tags, a licence and the site to credit. An image scene takes an asset's id as data.asset_id (or its url as imageUrl); a gallery takes urls. Only assets their owners switched to shared.

readOnly · idempotent

generate_asset Generate one image or clip, without making a video

[40 or 311 credits] One AI still (40 credits each) or clip (house 311, a named model its list_models price) straight into your bank — no render. A still takes model, aspect_ratio, count, negative_prompt, no_faces, character, objects; the rest are clip controls. 6 calls a minute. Clip controls are refused, with the allowed values, when the model is not sent them; model auto picks one and says why. best_of makes N and keeps the best graded (all N charged). Charged before, refunded on failure; dry_run quotes it free. Paid plans. A clip takes 1-3 min: the call answers generating within 45 s; call again with the SAME idempotency_key (or arguments) to collect it, never charged twice.

destructive

list_assets List the account's own media bank

[Free] Your PRIVATE bank: every image, clip and audio file, by origin and subject, with id, URL, brief, tags and facets. Reuse a picture by putting its id in an image scene as data.asset_id (a clip resolves to clipUrl by itself; a recorded flow's steps are clips of their own, tagged rush-step, each exactly one step of the rush); an audio asset is a film's music as "asset:<id>". Reusing costs no credit.

readOnly · idempotent

list_connections List the account's upstream connections

[Free] Every registered connection with its alias, kind and URL. Credentials are never returned.

readOnly · idempotent

create_object Create a reusable object

[Free] Names a product, logo, packaging, place, vehicle or UI screen from reference images so films keep it identical. Generated pictures take it in data.objects (clips, stills, insets, generate_asset) next to a character; image, gallery, pricing and compare cards draw it from data.object with its name and price.

idempotent

list_objects List the account's objects

[Free] The reusable objects on this account, with reference images, kind and metadata (price, brand, sku).

readOnly · idempotent

update_object Change an object

[Free] Changes only the fields sent. Media already generated with it is kept until a scene's description changes.

destructive · idempotent

delete_object Delete an object

[Free] Deletes an object by name. Its images stay in your bank and media made with it stays in its films.

destructive · idempotent

import_objects Import a catalogue as objects

[Free] Creates or replaces up to 50 objects from a product feed. Each image is downloaded (public addresses only) and banked as a reference. Failed rows are listed with the reason.

destructive · idempotent · openWorld

save_scene Save a scene to the library

[Free] Saves a scene for reuse: narration, visual, data, style AND its footage and generated media (a copy). Reusing it — update_storyboard add_scene_from_library, create_animation from_library — films and generates nothing, so no AI credit. Write {{placeholders}} in its narration or data first to fill them per use.

destructive · idempotent

list_scenes List the scene library

[Free] Saved scenes, newest first: name, id, visual, aspect, whether footage is kept, the {{placeholders}} each needs as params, and tags.

readOnly · idempotent

copy_scene Copy a scene into another video

[Free] Copies a scene into another of your videos with its footage and generated media, so nothing is filmed or generated again. A recording cannot change aspect, nor go into a film made from data. Does not re-render.

create_motion Design a motion graphic

[Paid plans] Designs a custom motion graphic from a brief (one text-model call; AI plans or a film pass; no credits charged), checks layout, legibility, contrast and timing, and saves it as a private template with params. Use it in a scene: visual "motion", data {motion:{specId, params}}.

destructive

list_motion_templates List motion templates

[Free] Your saved motion graphics (visual "motion") and the commons, with their params. Rushie designed cards: list_motions {rushie}.

readOnly · idempotent

get_motion_template Read a motion template

[Free] One template with its full spec (layers, motion tokens, declared params).

readOnly · idempotent

update_motion_template Change a motion template

[Free] Renames, retags, sets param defaults or visibility, or replaces the spec of a template you wrote. Films already using it keep their picture.

destructive · idempotent

get_motion_grammar Motion spec grammar

[Free] The grammar for writing your own animation as a motion spec: no topic → a short index and the authoring loop; topic → one rule file (layers, params, timing, motion, colour, layout, doctrine, examples, brief). Generated from the DSL itself.

readOnly · idempotent

validate_motion_spec Check a motion spec

[Free] Dry-run a spec: deterministic repairs, schema, params, layout/legibility/contrast/timing on four frames and the motion doctrine. Returns ok, every problem with its path and fix, the repaired spec and the params schema. Nothing is saved.

readOnly · idempotent

preview_motion Preview a motion spec

[Free] Frames back without a render: per aspect (16:9, 9:16, 1:1) a PNG sheet of four beats (entering, landed, hold, exit) — a deterministic LAYOUT wireframe from the DSL's geometry (exact boxes, wrapping, sizes, colours, timing; system font, no blur or shadow) — plus the problems measured on that frame.

readOnly · idempotent

save_motion_spec Save a motion spec

[Free] Saves a spec you wrote as a private template once it passes validate_motion_spec (repairs applied). Returns its id, params schema and the scene JSON that uses it: visual "motion", data {motion:{specId, params}}.

destructive

upload_asset Upload your own image, footage, music or slide deck

[Free] Puts a file in your bank from a public https url. A file you hold: use create_upload (curl -T, no base64 in your context) — data_base64 only for a file of a few KB, since a 100 KB picture is ~135,000 characters of tool input. Picture or clip → data.asset_id in an image scene; audio → music "asset:<id>"; deck (PDF/PPTX) → every slide's text and pictures, to write the storyboard from. Identical bytes return the existing asset.

idempotent · openWorld

create_upload Get an address to send a file to

[Free] A one-hour address to send a file you hold (picture, clip, music, font, PDF/PPTX deck, ≤ 30 MB): curl -sS -T <file> "<upload_url>". The reply is the asset or the deck's slides.

list_voices List the narrator voices

[Free] The narrator voices with measured pitch (band and median Hz) and a short sample in the chosen language where one exists (else sample_url is null). Every voice speaks every language. Preset voices only: PageToVid never clones a voice and never narrates with an uploaded recording — say so plainly.

readOnly · idempotent

get_timeline Get a finished film's timeline

[Free] Each scene's start and end in the finished MP4 (seconds), what drew it (recording, page still, AI clip/still, footage, graphic, card, inset), its transition, its slice of the one voice track with word onsets, plus the music and caption style. timeline_source: stored by the render, or rebuilt from the scenes.

readOnly · idempotent

get_frames Get stills from a finished film

[Free] JPEG stills (≤ 1280 px wide) cut from the finished MP4 at 1–6 moments in seconds, as URLs. Cached per render.

readOnly · idempotent

set_brand_kit Set a site's brand kit

[Free] Partial update of a site's brand kit: logo, palette, face (named or an uploaded font), intro/outro templates, watermark and logo corner, default voice/music/captions/look/transition. null clears a field. Films of the site inherit it unless the call overrides.

destructive · idempotent · openWorld

get_brand_kit Get a site's brand kit

[Free] A site's brand kit, what a film paints from it (and what it cannot, with why), the effective watermark, and the account defaults beneath it.

readOnly · idempotent

set_account_defaults Set the account's option defaults

[Free] Partial update of the options every film starts from (below a site's brand kit). null clears a field.

destructive · idempotent

list_options List every option in one call

[Free] Every enum and range a film accepts (voices, languages, beds, looks, captions, motions, transitions, visuals, aspects, faces, brand kit), the models with a credit example, and the inheritance levels.

readOnly · idempotent

invite_member Invite a team member

[Free] Emails an invite to this workspace with a role, optional site limits and monthly credit cap. Members spend the owner's credits. Seats incl. owner: Free/Creator 1, Pro 3, Scale 5, Business 15, Agency unlimited.

openWorld

list_members List team members

[Free] Members with role, sites, cap and spend this month; seats; your workspaces (send one as the X-PageToVid-Workspace header to act in it).

readOnly · idempotent

update_member Change a member's role, sites or cap

[Free] Changes only the fields sent. Only the owner grants or changes admin and billing.

destructive · idempotent

remove_member Remove a member

[Free] Removes a member or cancels an invite, freeing the seat; your own member id leaves the workspace. Their work stays.

destructive · idempotent

create_review_link Share a video for review

[Free] A link to watch the film and, if allowed, comment with no account. Shown once; only its hash is stored.

request_approval Ask for approval

[Free] Opens an approval round for the named approvers; supersedes a pending one.

approve Approve a video

[Free] Approves the pending round, as one of its approvers.

request_changes Request changes on a video

[Free] Closes the pending round as changes requested.

list_comments Read a video's comments

[Free] Timestamped comments from members and review-link guests, oldest first, and the approval round.

readOnly · idempotent

add_comment Comment on a video

[Free] Adds a timestamped comment; open comments feed the editor's AI revision.

get_audit_log Read the workspace audit log

[Free] Who did what here, newest first: members, spending, review links, approvals, comments.

readOnly · idempotent

set_webhook Set the account's completion webhook

[Free] Sets (or with null clears) the account-wide URL that receives a signed JSON event whenever a render ends. The first time a secret is needed it is created and returned here, once.

destructive · idempotent

rotate_webhook_secret Rotate the webhook signing secret

[Free] Replaces the secret completion events are signed with and returns the new one, once. The old secret stops verifying at once, including for retries still in flight.

destructive

list_revisions List a storyboard's revisions

[Free] Every storyboard edit, newest first: what changed and a revision_id. restore_revision puts the storyboard back as it was before one.

readOnly · idempotent

restore_revision Undo storyboard edits

[Free] Puts the storyboard back as it was before a revision, undoing that edit and every later one. Itself a revision, so it can be undone. Nothing is re-rendered until rerender_video.

destructive

update_character Update a character

[Free] Changes a character's references, description or name; anything not given is kept. Clips already made keep the look they were made with.

destructive · idempotent

delete_character Delete a character

[Free] Deletes a character by name. Its reference images stay in your bank and clips made with it stay in their films.

destructive · idempotent