Render, share and wait

On the main list

The tools a client sees when it connects.

share

Share link

Public link to the project or a scene, only when the user asks to share or publish. Free.

render

Render

MP4 of the project or one scene. SPENDS CREDITS. Finished piece or on request only; check with preview_frames. Async: get_status. Other formats: export_scene / export_project.

get_status

Poll jobs

One poll for all async work (generation, project, track, analysis, clone ids); wait_sec ≤50 holds for all_done. Free.

jobs

Read a job

The result of a tool you called with async: true — the same answer the direct call returns, once it is done. Until then {status: "queued" | "running"}; on failure the error. wait_sec holds up to 55 s for it to finish, so one call usually covers it. Reading also keeps a stalled job moving. Free.

run_chain

Run a chain of tool calls

Run several tool calls as ONE call, server-side: each step's result feeds the next, so a pipeline (generate → cutout → upscale → video) costs you one round trip instead of one per op and per poll. steps: [{id, op, args, each?, strict?}] — op is a tool name (generate_image, generate_grid, upscale_image, cutout, segment_image, decompose_image, depth_map, plate, generate_video, speak, import_asset, find_media, apply_changes, create_chapter, create_scene, update_scene, put_scene_composition(s), put_module, repin_modules, scene_takes, compare_takes, look, preview_composition, review_motion, frame_report, add_comment, resolve_comment, claim_scene, release_scene, share_scene, share_project, get_scene_context), args are that tool's own. REFS: a string arg that is exactly "$<id>" or "$<id>.path" (".key", "[0]") becomes that step's RESULT — generations are awaited, so "$img.url" is the finished picture (every result has top-level url / asset_id when it made one). EACH: "each": "$grid.cells" runs the step once per element (3 at a time, in order), with "$item" / "$item.url" / "$index"; its result is the list ("$up" feeds a later each). A failed element is null and the rest go on, unless strict:true. Steps that refer to no unfinished step run side by side (3 at a time; scene/project ops keep their order; "after": ["id"] forces one). SPEND: credit_cap is REQUIRED when any step spends; every spending step is priced with dry_run first (an each step once its count is known) and refused if the total would pass the cap. Stops at the first failed step and says which and why. dry_run:true runs NOTHING: the plan (waves of steps that run side by side), each spending step priced, the total, and a quote_id; then run_chain {the same steps, quote_id} runs exactly that plan, capped at the quote. recipe + inputs runs a saved recipe (list_recipes): inputs fill the args its tools take ("prompt", "project_id"; "s2": {…} for step 2 only). Waits up to wait_sec (default 50) and returns the finished chain, else {id, status:"running"} — follow with get_chain. SPENDS CREDITS (what its steps spend, ≤ credit_cap).

Callable by name

Not listed on connect, to keep the list short. Call them directly by name, or find them with tools.

cancel_generation

Cancel a running job

Stop a running render_project by its generation_id (from render_project / get_project_status). Queued scenes are dropped, in-flight GPU scene jobs are aborted and the film stitch is skipped: no video is produced. Only scenes already rendered are charged (cached scenes are free); the rest of the credits are refunded once. Safe to repeat, and on a render that already finished it changes nothing and returns the final state. Only the account that owns the job can cancel it. Returns {status, cancelled, settled, charged_credits, credits_refunded, scenes_rendered, scenes_total}; settled:false means the worker is still stopping, so poll get_generation until status is "cancelled". render_project is the only job type that can be cancelled today (others answer 422). Free.

get_chain

Read a chain

A chain from run_chain: status, per-step status, compact result (urls, ids, counts, checks), credits (quoted, charged from the ledger, cap) and the calls it made for you; failed_step + error when it stopped. wait_sec holds until it finishes. Polling also keeps a stalled chain moving. Free.

get_generation

Poll one generation

Status of ONE credit-spending job by its generation_id (from generate_image, segment_image, depth_map, plate, cutout, add_element, generate_scene): pending / processing / completed / failed / cancelled, the error if any, the finished asset for an image, and result for an image tool. A failed job carries failure {class, retryable, hint}: retryable:false (asset_unreachable, bad_prompt, credits) means change the input before trying again; staff also get raw, the worker's own error. credits is what the job ACTUALLY charged, net of refunds, read from the credit ledger (credits_source:"ledger"); credits_source:"estimate" means no ledger row is keyed to this job and credits is the quoted price. charged_credits is the linked ledger figure only; complete:false means the job's charge is booked elsewhere and unattributed says where (voiceover: per-batch, unkeyed; composer-upfront: on the project, see get_project; character; unlinked). get_account before/after is the receipt for the unattributed part. A video render (type render-project) also carries render_seconds (job wallclock) and gpu_seconds (GPU time summed across the scenes it actually rendered; cached scenes cost none) and scenes_rendered / scenes_total / scenes_cached. A render stopped with cancel_generation shows status "cancelled", no output_url, and charged_credits for only the scenes it had rendered. gpu_seconds can exceed render_seconds because scene renders run in parallel. A multi-chapter film also carries film_join {mode: copy|reencode, reason, seconds, seams, encoded_seconds, conformed}: how the chapters were stitched (null for one chapter). Free. get_project_status answers for a whole project; this is the per-job receipt. Poll every few seconds, not in a tight loop.

get_project_status

Check generation status

The polling tool. Reports how much of the project is resolved (scenes generated, voiceover present), what it would cost to finish, and whether it is ready to render. voiceover.timing gives voiced vs target seconds and a warning past 10% drift. Generation is asynchronous — after resolve_project or render_project, poll this rather than assuming the work is done. Includes an editor_url worth handing back to the user. This work takes MINUTES: pass wait_sec (up to 50) and the server holds the call until nothing is generating and every chapter is voiced, or the wait runs out — one call per wait, not a polling loop. If the user does not need to sit and watch, hand them the editor_url and stop.

render_project

Render the video

Render the finished project to an MP4. SPENDS CREDITS. Only when the piece is finished or the user asked for the file: to check work in progress use frame_report, preview_composition (quick:true) and review_motion, which are free and faster, and share_project to watch it. Everything must be resolved first — check get_project_status.ready. Asynchronous: poll get_project_status, then share_project for a link the user can actually watch. Started by mistake? cancel_generation with the generation_id stops it.

scene_renders

Which scenes have takes and a rendered video, and is it up to date

Every scene of a project (or the scene_ids given) with how many takes it has and the state of its rendered video: "none", "rendering", "current" (a video of the scene as it is now), "outdated" (the scene was edited after its video was made) or "unknown" (rendered before versions were recorded; may be out of date). Gives the video's clip_url and length when there is one, and render_credits, the price of making one scene's video. The studio's scene menus show the same thing. To make (or remake) a scene's video: render {scene_id} (SPENDS CREDITS; only when asked or the scene is finished; check work with look/preview_frames). Takes: scene_takes. Free.

share_project

Get a share link

Create (or fetch) a public share link for the project — a viewable page, not a raw file. Use it when the user asks to share, publish or send the video to someone; while they are editing, hand back the editor_url (create_project, list_projects) that opens it in the app.

The whole video PLAYS in the conversation where the host renders MCP Apps views: every chapter in order on one timeline, mounted live rather than as a rendered file, so it is watchable before the last scenes finish: a link can be minted mid-build, scenes still resolving show as placeholders, and ready / pending in the result say what is left. Hand over the link as well — it is what survives the conversation — but do not recap the video as though the user cannot see it. For ONE scene, reach for share_scene instead.

share_scene

Get a link to one scene

Mint a public, login-free link to ONE scene — the page a person opens to see what you made, captions included. Free. Use it when the user asks to share, publish or send the scene; while they are editing, hand back the editor_url instead. Idempotent — a scene that already has a live link gives back the same one, so it is safe to call again after an edit (the page renders the scene as it is NOW, not as it was when the link was minted). Unlike share_project there is no readiness gate: a scene still generating is shareable, and the page reports its own status. Scene ids come from get_storyboard.

The result PLAYS in the conversation where the host renders MCP Apps views: the scene player mounts the live composition, not a thumbnail. Hand over the link as well — it is what survives the conversation — but do not describe the scene in prose as though the user cannot see it.

wait_for

Wait for a job, then continue

For an agent running inside Typecut (the editor chat, a seat, a helper): instead of promising to "check back later" (nothing would wake you), say what you wait for — the ids a slow tool returned (analyze_video, render, generate_*, music, a voice clone, a job from async: true) — or a number of minutes. Then end your turn with one short line to the person. You get a message starting "[Wake]" when everything listed is done, or when minutes run out, and continue from there; the chat shows "Waiting for <label>" meanwhile. A message from the person still reaches you while you wait. Free.

wait_for_generation

Wait for one generation to finish

Wait (server-side, up to timeout_s, default 60, max 120) until ONE job from generate_image, cutout, segment_image, generate_video, render_project … is completed, failed or cancelled, then return exactly what get_generation returns. One call instead of polling get_generation: if status is still pending or processing when it returns, the wait ran out — call it again. Free.