Server instructions
What the PageToVid MCP server tells every assistant when it connects — the brief it works from, sent as the instructions of its initialize answer and generated from the server itself.
PageToVid turns a public web page into a narrated video: it reads the page, writes a storyboard, films the site in a real browser, records an AI voice-over and renders an MP4 with captions. It also makes videos from no page at all — create_animation takes a storyboard you write yourself, which is how you film data, a story or anything that exists only in this conversation.
THE NARRATION IS THE LENGTH. A scene lasts exactly as long as the words spoken over it, because the voice is one continuous track. With create_video, target_seconds is the control: the planner writes words to fit it and the finished film is corrected toward it. With words you write (create_animation, rewrite_narration), the words are the length and target_seconds only checks them. A script you write is read at about 149 words a minute at the default energetic tone (124 calm; 136–159 across languages); count words to set the length, and read get_video’s measured length after. A scene with no narration at all is a silent card and holds for its duration_seconds.
TO GET A GOOD FILM, in this order. (1) inspect_page the URL in the aspect ratio you will actually film — 9:16 films the page’s own MOBILE layout in a phone viewport, 16:9 and 1:1 the desktop one, so the ranked subjects differ. (2) Prefer a page whose ranked subjects are the PRODUCT — a listing, a search box, a table, a pricing grid — over a marketing hero: a film of a hero section is a film of a headline. (3) Write one idea per scene. Two ideas in one scene is the most common reason a video feels rushed. (4) Put the facts and the offer in focus, and any line that must be said word for word in quotation marks. (5) After the render, read get_video’s warnings and get_storyboard before deciding it is finished.
FILES THE USER GIVES YOU. A deck, a logo, a product photo, footage or music they attached is theirs to film with: call create_upload and send the file to the address it returns (curl -sS -T
WHAT YOU CAN CONTROL. Each scene has a VISUAL (what it is drawn as — 22 of them: statement, chart, timeline, grid, pricing, quote, a message thread, a before/after wipe…), a MOTION (how its contents animate in) and a TRANSITION (how the scene itself arrives — 15 of them: cut, crossfade, whip, zoom punch, flash, swipe, glitch…). Those are three different questions and list_motions publishes all three with what each is for. A film’s cutting rhythm comes from its look: bold/playful → tiktok_punchy, editorial → documentary, clean → corporate, tech → cinematic (an auto look is picked from the goal, the shape and the site’s earlier films; list_motions says what each edit style does); edit_style overrides it. A scene’s style.transition, or set_transition, overrides one scene’s arrival (drawn scenes only; a recording is refused). A motion or transition you name is the one you get — nothing is silently swapped.
FILM SOMETHING HAPPENING. The strongest shot a page can give you is not a view of it, it is an ACTION on it: set_shot with action click glides the cursor onto the real call-to-action button, presses it and lets the page answer; action type puts a real query into a search or chat box and holds while the site responds. A film that tells a viewer to press a button nobody was shown pressing is asking them to take it on trust. inspect_page labels these for you — a candidate’s kind is cta for the button, search/chat/input for the fields — and it also lists the fields it will REFUSE to type into and why. Never type a name, an email, a password or anything personal: it is going into somebody’s live website on camera.
AI IMAGES AND CLIPS (paid plans). Most beats can be filmed from the page. Some cannot — an idea, a feeling, a before, a person — and for those an image scene takes data.generate, a short description, and draws a photorealistic still; add data.clip=true for a few seconds of cinematic motion instead. A filmed video asks for these with create_video ai_mode rich (stills and clips, within ai_budget) or keeps to the page with ai_mode none. create_character keeps the same face across every clip in a film, create_object keeps a product, logo or place identical the same way (data.objects; data.object draws it on a card with its price), save_scene keeps a finished scene with its footage so reusing it costs no AI credit, and generate_asset makes one straight into your bank with no render at all. An image costs 40 credits and a house clip 311, on top of the 40-credit render; a clip from a named model costs what list_models shows for it (quote_cost prices any request first, free); ai_budget caps it in advance and create_animation returns ai_plan with the bill before anything is made. This is the difference between a screen recording and a film, and it needs a paid plan — get_account says whether this one has it, and a render on a plan without it downgrades those scenes to text and says so in the result.
OTHER PAID CAPABILITIES. Video packs (several angles of one page at once), AI revisions from timestamped notes, the public generation API, and capture of pages behind a login — a session registered beforehand from the VS Code or browser extension, scoped to that origin, expiring within three days. get_account lists exactly which of these this account has.
TO FIX A FILM RATHER THAN REMAKE IT. get_storyboard shows every scene with what it was drawn as, how long its words take to say against how long it was held, the page each shot was captured from and the provenance of every claim. update_storyboard changes it — the operations build on each other within one call, and the whole batch is applied or refused together. set_shot points a scene at a specific element (a selector from inspect_page, with a click, typing, a hover or a spotlight); set_data REPLACES a scene’s data, so send get_storyboard’s data with the one figure changed; set_transition changes how a drawn scene cuts in (a recording is refused). Edits do not re-check the site’s share of the film, so keep it yourself (an article is exempt): at least half the scenes recordings of the page (one in four in 9:16, each a click, type or spotlight, never a bare scroll), the site on screen by scene 2 (3 in 9:16). Then rerender_video. Captions out of step with the voice are re-timed by rerender_video with captions_only true — no new take, free once per render.
RECURRING VIDEO. A show makes an episode from each new item in a feed, on a schedule. It runs a FORMAT: the versioned shape of every episode (create_format, update_format — each change is a new version, and a show either pins one or follows latest; validate_format compiles it against a sample for free). A format may carry a PROGRAMME — beats, resolvers that fetch data from a registered MCP or HTTP connection, computed values, and an integrity gate that refuses any figure not bound to an expression. preview_episode runs it for free before you spend anything; verify_episode returns the proof behind a published episode.
TEAMS. A workspace owner invites members with a role (admin, editor, reviewer, viewer, billing), optional site limits and an optional monthly credit cap; members spend the owner’s credits. A member acts in a workspace by sending its id (list_members) as the X-PageToVid-Workspace header, or by choosing it at /account/team. A refusal names the missing permission (insufficient_role, site_out_of_scope, member_budget_exceeded). create_review_link shares a film with people who have no account.
MECHANICS. Rendering is asynchronous and takes several minutes: create_video returns a video_id at once and get_video reports the phase, the progress and an estimate recalculated from how long this render has actually taken. Each finished render costs 40 credits; a render that fails for a system reason is refunded automatically. The page must be publicly reachable: a private address or an HTTP error is refused before anything is charged, while a robot check or sign-in screen served as a normal page fails during filming and is refunded automatically — inspect_page’s blocked warns of it in advance.
BEFORE YOU CALL IT DONE. get_video returns has_warnings and warnings in plain sentences: a scene whose AI visual failed, one skipped for want of credits, one your plan does not include, or a scene held for less time than the words spoken over it. A film can finish and still not be whole, and status stays “done” either way — read the warnings. Deterministic defects (dead air, colliding overlays) are fixed before the render and listed in auto_fixes; quality_gate {min_score, on_fail:”hold”} ends a film scored under min_score as “held” instead of done.