Write your own HTML

Let your agent write each scene as plain HTML and GSAP while Typecut supplies voice, timing, the music grid, checks and rendering.

In the studio profile, your agent writes every scene. Typecut does the parts an agent cannot do alone: voiceover with word timings, the music beat grid, generated media, validation, GPU rendering and share links.

A scene is one HTML document with a paused GSAP timeline. You time reveals to the words and beats Typecut gives you.

Pilot accounts only, for now

Landing scene HTML your agent wrote is limited to staff and pilot accounts while rendered scenes move to an isolated origin. Every account can run the same checks with dry_run: true. To join the pilot, ask Typecut to add your account.

Connect to the studio profile

Use the studio URL with the same sign-in as the main connector. See Connect your client.

https://app.typecut.ai/api/v1/mcp/studio

The server describes its own workflow to the agent, and a full guide is available as the resource typecut://studio/guide. Agents read it on demand, so it costs nothing until needed.

The call path

A short piece takes about a dozen calls.

get_account. Returns your plan, balance and workspaces. Pick a workspace. list_catalog lists valid voices, music and themes before a project exists.

create_project with your own plan. The plan lays out chapters, blocks and scenes exactly, in one call, with no planner and no generation. It is free. Each scene has one clock: narration (spoken), duration (fixed seconds) or music: {bars} (a span on the tempo). Want a draft first? suggest_plan runs Typecut's planner on a topic or script and returns a plan you can edit.

voice_project with dry_run: true, then for real. This voices only the narration and adds word timings. It does not compose anything. Poll get_status with wait_sec until it is done.

set_tempo and set_music if the film is scored. These fix the beat grid and put a bed on it. get_timeline then shows bars and beats on the film clock.

get_scene_context for up to 10 scenes at a time. It returns each scene's duration, canvas, element id, words on the scene clock, beats and theme CSS variables.

Write the HTML, one document per scene.

put_scenes, up to 20 per call. It runs the real validation gates and lands only the scenes that pass. A refused scene comes back with the reason and costs nothing to fix. dry_run: true checks without landing. Add check: true and the same call also looks at what landed: a frame sheet and a motion strip, with findings inline. Scenes that share a layout can be one template plus per-scene data.

Check what you landed, then fix and land again. See the loop below.

Hand over the editor link (https://app.typecut.ai/project/<project_id>) while you work. Call share only when the user asks for a public link, and render for the MP4 only when the piece is finished or the user asks. Poll get_status until the render completes; it takes a few minutes.

Need more than the list shows? Every Typecut tool answers by its name, such as set_cues or set_mix. tools finds one, and invoke_tool calls it for clients that only call listed tools.

What a scene looks like

The document needs one root element whose data-composition-id matches the element id from the context, a paused GSAP timeline, and that timeline registered on window.__timelines.

<!doctype html><html><head>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
</head><body>
<div id="comp" data-composition-id="comp" data-width="1920" data-height="1080">
  <style>[data-composition-id="comp"]{position:relative;width:1920px;height:1080px;overflow:hidden}</style>
  <h1 class="title">Every morning</h1>
  <script>(function(){
    var root = document.querySelector('[data-composition-id="comp"]');
    var tl = gsap.timeline({ paused: true });
    tl.fromTo(root.querySelector('.title'), {opacity:0}, {opacity:1, duration:.4}, 0.2);
    tl.to({}, { duration: 6 }, 0);   // span the whole scene
    window.__timelines = window.__timelines || {};
    window.__timelines["comp"] = tl;
  })();</script>
</div></body></html>

Replace 1920, 1080 and 6 with the canvas and duration from get_scene_context.

Rules the validation enforces

Paused and registered. The renderer seeks your timeline frame by frame. It never runs a frame loop, so requestAnimationFrame, setInterval and wall-clock time render frozen.
Canvas is fine if the timeline paints it and nothing carries between frames.
Scope to the root. Do not append nodes to document.body.
Select by class or data attribute, never by id. Ids are renamed when the scene mounts, so querySelector('#title') finds nothing.
Use theme variables for colour and type. get_scene_context names them. A hard-coded hex drifts from the theme.
Time to the numbers you are given. Put tweens at word start times and beat seconds from the context, not at values you calculated.
Audio in HTML is not mixed. An <audio> element is ignored in the render. For dialogue, give the scene a speech list on put_scenes.

The preview loop

Check what you landed, cheapest first. All of these are free.

put_scenes with check: true lands and looks in one call. Start here.
look over any window of the film (a scene, a chapter, or seconds across cuts) returns frames, a motion strip and sync findings. Use it after a batch, and before you call a chapter done.
preview_scenes returns a findings list without pictures: clipped text, off-frame elements, low contrast, text too small on a phone.
review_motion returns one filmstrip image with each motion fault outlined. Still frames can pass a scene that looks wrong in motion.

To fix one line, send edits: [{find, replace}] on put_scenes instead of the whole document. It patches your last landing and passes the same gates.

For long films, work in chunks of 10 to 20 scenes, one chapter at a time. You can voice one chapter (voice_project with chapter_id) and start writing before the rest is done.

What costs credits

Tools that spend credits say SPENDS CREDITS in their description. Price first with dry_run.

Free	Spends credits
`create_project` with your own plan	`voice_project` (narration)
`suggest_plan`	`speak` (a repeated line in the same voice is free)
`get_scene_context`, `get_timeline`	`put_scenes`, only for `speech` text lines
`put_scenes` with HTML only	`generate_image`, `generate_video`, `set_music` (a generated bed)
`look`, `preview_scenes`, `review_motion`, `analyze_video`	`decompose_image`, `transcribe_media`
`share`, `get_status`	`render`

render is listed as spending credits. Your plan may include exports at no charge. Use quote to see the price for your account. A render started by mistake can be stopped with cancel_generation; only scenes already rendered are charged.

Results report what work will cost, not what it did. get_account before and after is your receipt.

Send files, not pastes

A 30 KB scene pasted into a tool call is re-read on every later turn. If your agent has a shell, it should upload the file instead:

create_upload with a file_name returns an upload URL and a public URL.
Upload the file with the returned curl.
put_scenes with { scene_id, src_url: <public URL> }.

This also works for fonts, audio, images and video.

MCP connector for connecting and pricing.
Tool reference for every tool and parameter.
Render and share for what happens after the last scene lands.