Comments and agents

On the main list

The tools a client sees when it connects.

comments

Review comments

Review comments. op: list (open ones), add, resolve (one you addressed). Free.

Callable by name

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

add_comment

Leave a review comment

Leave a comment on a project, anchored as narrowly as it deserves: scene_id for a scene, t_start (and t_end for a range; seconds from the scene start) for a moment, element_id for one element, composition_path for a node of the composition tree. To point at several places at once ("1 and 3 should hit together"), pass anchors instead. parent_id replies to an existing thread: the way to answer a comment you are not resolving, or to say what you changed. kind marks it a question or a blocker; to says who it is for (another agent, the director, or one run). Free.

check_comments

Anything new from a person?

A cheap, instant check for feedback: has a person left or answered a comment for an agent since your cursor? Returns {new, count, blockers, questions, first_id, cursor, retry_after_seconds}. It does not wait and returns no rows: when new is true, call list_comments {awaiting:"agent"} for them. The first call (no since) only returns a cursor; pass the cursor back as since each time. Call it between passes, not faster than retry_after_seconds (30): it is rate-limited, and the get_project_status / get_storyboard / apply_changes calls you already make carry the same hint for free. Free.

claim_comment

Say you are working on a review comment

Take an ADVISORY, time-limited claim on a review comment before you work it: the editor shows "<you> is on it" and other agents skip it in their list_comments {awaiting:"agent"} inbox, so two agents do not do the same note. Call again to renew; it lapses by itself after ttl_seconds (default 600). result "held" means another agent already has it: pick another. release:true lets go. assign_to:"run:<agent run id>" hands the note to a sub-agent (your claim drops, the note is addressed to that run, which claims it when it starts). Resolving the comment clears the claim. Never blocks a reply or resolve_comment. Free.

fork_agent_run

Fork an agent run from a step

A new run that starts from another run's conversation as it stood at step from_seq, optionally with a different model, skill or a first steer — replay a decision point, or A/B two models from the same place. Fork from before the parent's create_project and the fork makes its own project (a comparable arm); after it, both work on the same project. Like start_agent_run, the fork spends only through the tools it calls.

get_agent_run

Read an agent run

An agent run and its steps after a cursor: status, model, $ and credits spent, wall clock, project, share link and MP4 once they exist; each step is a model call (text, tokens, $, latency), a tool call (input, result — truncated; full:true for all of it, and frames it saw), a steer or an error. Poll with after_seq = the returned cursor. Without run_id: the account's recent runs. Free.

get_director_thread

Read the project's Director thread

The project's Director (in-editor agent) conversation as a DECISION TRACE: every message, and for each assistant turn its ordered steps — tool name, input, and the real outcome. Read this when the question is WHY the project looks the way it does (what was created, in what order, what failed, what a resolve actually started) rather than what it looks like now. Read-only; automated "[Background job update]" rows and editor ledger events are marked by kind.

list_comments

Review comments

The review comments people left on a project, the way notes are left on a cut: each is anchored to the project, a scene, a time range (t_start/t_end, seconds from the scene start when scene_id is set), an element id, or a composition node path. A grouped comment lists every place in anchors (numbered in order; a region is a shape drawn on the frame at t, a lane is a timeline lane such as hit.snare): the body refers to them together, so fix them together, often in one apply_changes. A spoken note carries voice: its transcript is what was said (and the body, when nothing was typed). Default: OPEN threads with their replies, in the order they were left: your work queue. To work one: read the anchor (get_scene; get_scene_context at t_start), make the change (edit_elements, edit_composition_unit, apply_changes, update_scene), then resolve_comment with the changeset_id or revision_id that answered it. A comment you cannot or should not act on: reply with add_comment parent_id instead of resolving it. Each comment has a kind (note | question | blocker: answer a question, do blockers first) and may be addressed_to someone (null = anyone, agent, director, run:<id>); comments sent together in one review pass share a pass_id. A comment from a person also steers any live agent run on the project, so you may already have been told about it. A scene comment carries routed_to (the agent that last wrote that scene, mine when it is you): your awaiting inbox lists yours first; one routed to another agent is theirs to take, so prefer to leave it unless it is blocking. Free.

resolve_comment

Resolve a review comment

Mark a comment resolved and LINK the change that answered it: changeset_id (from apply_changes / list_changes) and/or revision_id (from get_revisions, for element and composition edits). The link is what lets the person see which fix answered which note, so pass it whenever a change was made. note says what you did in a line. reopen:true reopens a resolved comment. Free.

start_agent_run

Start a cheap-model agent run

Start an unattended agent run: a gateway model makes a video from brief through the same Typecut tools you have (create_project, speak, generate_image, put_scene_composition, preview_composition, render_project …), server-side — it survives this conversation. Every model call and tool call is traced. Returns the run; watch it with get_agent_run, steer it with steer_agent_run, branch it with fork_agent_run. Without project_id or workspace_id it works in the account's "Development" workspace and creates its own project. Starting is free; the run spends credits through the tools it calls (each priced as usual), up to credit_cap. Called by an agent that is itself running (the editor chat, a seat, a run), it starts a HELPER: same project, your model unless you name one, a cap within yours; at most 3 at once and 6 in all, and a helper cannot start its own. Its final answer comes back to you as a message when it ends. Staff / authoring pilot.

steer_agent_run

Steer an agent run

Change a run while it runs, applied between steps: message is read by the model next as "[Operator] …" (on a finished run it reopens it); action pause / resume / stop; model or skill swaps for the rest of the run; force_tool_result replaces a tool result the model has seen (its tool_call_id, else the latest). Free.

talk_to_director

Talk to the project's Director

Send the project's Director (the in-editor agent) a message and get its whole turn back: the reply, the steps it took (tool, input, outcome) and its trace (how the turn was routed, what went into its window). It is the SAME turn the editor chat runs, and it lands in the same thread — whoever opens the project in the editor sees it, tool rows included. Attach library media by id (upload or import_asset first) exactly like dropping files on the composer. If the reply comes back with ask, the Director stopped on a question: answer it by calling this again with the same thread_id (an option label, or your own words). Background jobs it starts keep running after the turn: poll get_project_status, then tell it what happened. SPENDS CREDITS: each message is charged the editor chat's flat per-turn price (answering its question is free; a turn that fails is refunded), plus whatever the tools it runs spend — the same spend guard as the chat applies. Out of credits answers 402 insufficient_credits.

talking_head

Make a face speak

Lip-sync a FACE to a VOICE: a photo or a silent clip of a person (face_asset_id or face_url) plus a voice track (audio_asset_id — e.g. a speak result — or audio_url with audio_seconds) becomes a clip of that face saying those words. At most 60 s of voice per clip; cut longer speech into parts. SPENDS CREDITS, per second of voice (dry_run:true quotes). Not a scene element: the MP4 comes back as result {assetId, url, posterUrl, width, height…} to place in your own HyperFrames as a <video>. Takes a minute or more: this waits ~50 s, then answers status "generating" — poll get_generation (or get_status) with the generation_id.