invideo

invideo's guide to working with these tools: projects and URLs, the notebook, timelines, media, exports. Read it before your first edit, and when a result surprises you. Give a topic for one section.

get_help

A model's description, capabilities, price by its inputs, and inputs, as a JSON Schema. Media inputs take the URLs of sequences in this project, from read; add_media brings image, video and audio files in first.

get_model

Read the timeline the URL names: its timelines, tracks, clips and media, with their ids, its revision and the state_token edit_timeline needs. Ranges include their start and exclude their end.

get_timeline

The messages other agents in this project sent to the name you pass as `as`, oldest first: the unread ones, which this hands over, or with before, the ones before that message id, read or not. Every answer says when you have unread messages. Each says who sent it as from: their name, their handle (their @ in this project) and their url. Answer one with message and its from.url.

inbox

Read objects by id, with every property edit_timeline can change. Ids come from get_timeline.

inspect_objects

Take your cursor off this timeline, when the user asks or your work on it is done. Any later call on its URL brings you back.

leave_timeline

List the projects in a workspace, newest first, each with its URL, 50 at a time. Pass the workspace's URL from list_workspaces as `url`, and `query` to find projects by title.

list_projects

Lists the user's projects on the project panel. For the panel, not the model.

panel_projects

The workspaces this connection can use, each with its URL. Pass a workspace's URL as `url` to list_projects or new_project to work there.

list_workspaces

Approve or reject the sequence the URL names, as the user's approve and reject buttons in invideo do; read shows the mark as judgement. To take back an approval, reject it and vice versa. Mark only when the user asks you to or after they agree.

mark_sequence

Work on one media file without a timeline; op picks what. The file is a sequence or project file (its URL), a media bin asset (the timeline's URL and asset_id) or, for a read, a stock result (the project's URL and stock). Reads answer at once and are free: metadata, video.frames and the audio ops of a file's sound. audio.transcript and describe are kept on the file: the first call starts one and answers its status with retry_after_s; call again for the words, or for describe's summary, chapters and captions of what is seen and heard, from invideo's media understanding (a video, read once and shared, up to 5 hours; its times are rough, an outline to find stretches by). Both spend credits. ask answers a question about up to 60 seconds of a video (start_seconds to end_seconds) with invideo's media understanding, which takes in what is seen and heard there, citing moments at times in the file; it spends credits and answers within the call. For a long video, describe first, then ask about the stretches it points to, widened by a minute on each side, for exact times. Every other op makes a new file, a new sequence followed with status and read. A model op (audio.separate, audio.clean, video.upscale, image.upscale, video.removeBackground, image.removeBackground) runs its default model, or model, and is charged. document.pages, on a PDF or office document of the project's files, makes an image sequence of each page on a new thread (on to, a page or thread, else the first page), free. Every mode of the video_tools, audio_tools and image_tools models is a free op named <kind>.<mode> in camelCase (video.trim, video.extractFrameAtTime), its options as fields under their own names. Ops that spend credits take dry_run (the price; nothing starts) and max_credits (the most it may cost); ops that make a file also take idempotency_key.

media

Send a message to another agent in this project: an invideo agent or another remote agent, by its URL from read of the project's …/agents. An invideo agent reads it and answers with a message of its own; a remote agent gets it from its inbox. It is sent from the name you pass as `as`, and answers come to that name. Messaging an invideo agent runs it on the user's credits: do it only when the user asks, or to answer a message in your inbox. Messaging a remote agent costs nothing. Its answer comes to your inbox.

message

Make a brief in the project and return its URL: the plan for one thing to make, which the project's agents work from. Name and describe it here; write or edit with its URL adds its notes.

new_brief

Add a page to the end of the project's notebook, titled, and return its URL. Pages group threads; new_timeline and add_media take a page URL to put things on it.

new_page

Start a new project in a workspace and return its URL. Pass the workspace's URL from list_workspaces as `url`. Give the project's URL to the user: it opens the project.

new_project

Make a new, empty timeline in a thread of its own on the page the URL names (a project's URL means its first page), and return the timeline's URL. Give the URL to the user: it opens the timeline. get_timeline with it reads it.

new_timeline

Show the user something on the timeline: point your cursor at clips or at one time, with a few words beside it, like "This is the intro". Your reads and edits already move your cursor, so you don't need this to work; use it when the user asks where something is or you want them to look. It stays until you read, edit, point elsewhere or leave.

point_at

Read what a URL names. A project: its notebook pages, their threads newest first, and what each thread made, then its context (what the project is, the user's rules, and a line per other entry), its briefs and its newest files. A context entry or brief: its markdown and revision, for edit and write. The files (…/assets, or a folder like …/assets/downloads): each by its URL, newest first. A file (…/assets/<its path>): its media. A page, a thread (…/notebook/page-2#thread-9), a sequence (the files it was made from, its media, with a fresh download URL and, once completed, a picture of it: an image as itself, a video as a 3x3 sheet of frames across it), or a timeline (its branches). Every item carries its URL, status and who made it, and a sequence its judgement: approved or rejected, by the user or an agent, with the reason when one was given; none when unmarked. Give the URLs to the user. To check on a job, read it again after its retry_after_s, or status for several at once; never start it again to check it.

read

Give yourself a name in this project, so your work and your cursor are yours and not shared with every other agent of this user and client. Then pass it as `as` on every call here. Answers the agents already in the project. A name already in use here, an agent's or any other @ in the project, is refused, so pick another.

register

Rename the page, thread or sequence the URL names, as the user can in invideo: a page's title, a thread's heading, a sequence's name. Answers with read of it. A timeline is renamed with edit_timeline's set_name, a brief with write or edit. With your own URL (…/remote-agents/<your name>), renames you: your work and messages stay yours under the new name, which you pass as `as` from then on.

rename

Tell the invideo team when these tools get in your way: a call fails or is refused for a reason you can't see, a result contradicts the guide or a tool's description, or a description left you guessing; for something missing, use request_feature. Include the tool, the arguments you sent and the full answer. You may file reports about the tools yourself and tell the user in a line; ask the user before including anything from their project beyond its URL.

report_bug

Ask the invideo team for something these tools can't do yet: an op, effect, setting, tool or way of working the user asked for or you needed. Say what you were trying to make and what you did instead. Offer it to the user; you may also file it for gaps you hit yourself.

request_feature

Search a library. A model's voices (`<model>_voices`, as the model's voice input names them): pass the chosen voice's id as that model's voice input. Stock footage, images and music (stock_video, stock_image, stock_music): each result is an id in this project; add_media with stock set to it places it, and the media tools look at it first. Stock and voices come with a preview for the user. You only see stock's watermarked preview; exports use the clean file.

search_library

Set who may see the export page the URL names and what they may do there: visibility (public: anyone with its URL; shared: the workspace; private: only the user), each visibility's comment and download permissions (the page's current ones unless given), and what the workspace may do with the page itself. Ask the user before making a page public.

share_export_page

Move the project panel already open beside the chat to what the URL names: a page, the context or a brief, a sequence, a timeline's editor. It needs that panel open, from open_project_panel; with none open nothing changes, so open one with open_project_panel instead.

show_in_project_panel

Start an upload for a file you hold locally. The answer is an upload_id and an upload_url that takes the raw bytes with one HTTP PUT (for example `curl -X PUT -H 'content-type: video/mp4' --data-binary @file.mp4 '<upload_url>'`). Then call add_media with that upload_id.

start_upload

Where each job stands, for sequence, timeline and thread URLs of the project `url` names, in one call: each URL's status (queued, running, completed, failed, held, needs_confirmation), and while it moves, retry_after_s, when to check again; a thread's is over everything it made and runs. The cheap way to follow work: call it again after the least retry_after_s, and read a URL once it is over for what it made or why it failed.

status

Frames a generation's card. For the card, not the model.

card_embed

Signs the project panel in. For the panel, not the model.

panel_token

Read-only reference for editing timelines: every type of change edit_timeline accepts and the exact settings each takes, the available effects and transitions with their parameters, and editing guides. With no arguments it lists every change type, effect and transition with a line on what it does; name some in ops, effects or transitions for their full settings, or in guides to read a guide. The custom_shader guide explains the custom effect and transition ops.

timeline_catalog

The timeline's version history. action picks one: list (read-only) shows its branches and checkpoints; checkpoint saves the current state; restore returns a branch to a checkpoint; create_branch and create_tag start one from a checkpoint; rename, set_default and declare_final change a branch. Every action but list changes the history and needs expected_state_token from your latest get_timeline. After a timeout, retry with the same token and fields; if the token is then refused as stale, the first call landed, so read again.

timeline_history

Replace a context entry or a brief with markdown, as read shows it, or make a context entry at a new URL under …/context/world/, …/context/brands/ or …/context/knowledge/ (ending in .md). A brief is one document: `# <name>`, its description as `> ` lines, `> status: <status>`, then each note under `## <note-slug>` (lowercase, digits, - and _), in order; notes left out are deleted, a description or status left out stays. Link a sequence, page, brief, entry or asset by its URL from read. Empty markdown deletes the entry or archives the brief. Over one that exists, pass the revision your read gave: a change made since is refused rather than overwritten. To change a part, edit is safer. The project's agents work from these, so write what the user asked for; …/context/invideo_rules.md holds the user's own rules.

write

Start Agent Two on the user's brief in a video project, and open its live view. Returns an agent_id — the handle for send_follow_up_message, list_generations and get_conversation_history. Pass the project_id from create_project or list_projects. Relay any question Agent Two asks back to your user. If this fails, do not call it again — check list_agents first.

Create a new video project on invideo. This is the first step whenever the user wants a video: create the project, then start Agent Two on the user's brief with create_agent (using the project_id this returns). Create one project per distinct piece of work.

Catch up on an agent's conversation in one call — what the user asked, Agent Two's replies, the videos and images produced, and any question waiting on the user. Pass the agent_id from create_agent or a list_agents row. Relay any pending question to your user. Also use this after a failed call to see what actually happened before retrying anything.

Internal plumbing for invideo's embedded live view — it runs automatically. NEVER call this tool yourself: it does not create an agent, does not start any work, and returns nothing useful to you. To start work, use create_agent; to check on work, use get_conversation_history.

Generate video, images, audio or 3D models with a model from find_models, charged to the user's credits, where the URL points: a page's URL starts a new thread there; a thread's, a sequence's or a timeline's adds to that thread. When in doubt, seedance_2_5 at 720p and gpt_image_25_sunburst at high quality are good known defaults. Pass the model id, its inputs as one object keyed by the input names get_model lists, and max_credits: the most the estimate may be. Call with dry_run first to see the price and check the inputs without spending anything. Answers the thread's URL, and the sequences' URLs once they appear; read them to follow the generation. Pass an idempotency_key so a retried call after a timeout finds the first generation instead of paying twice.

generate

Open the project in a panel beside the chat: its generations, pages and context, and its editor, where the user watches your edits land live, plays them back and edits by hand. A URL from another tool's result opens what it names: a timeline's URL opens its editor, a page's URL that page. Each call opens a new panel, so call it only when none is open, after new_project or when the user wants to see a project; with one open, show_in_project_panel moves it instead. While it is open, what the user is looking at and has selected arrive as context: "this" means that selection.

open_project_panel

List the agents already working in a video project, so you can pick one to continue with. Pass the project_id from create_project / list_projects. Each row's agent_id is the handle for send_follow_up_message, list_generations and get_conversation_history.

List the videos and images Agent Two has produced for an agent, including ones still generating. Pass the agent_id from create_agent or a list_agents row. Share each item's open_url with the user — it opens the video on invideo for full-quality playback, editing and export.