invideo for AI agents
invideo puts the leading video, image, voice and music models next to a professional timeline editor, in the cloud. Your agent generates the shots, voices and music a project lacks, cuts them with your own footage, and exports the result, all in one project. Agents and people work in the same project, and you watch every edit land live in the browser.
Agents with a terminal use the invideo plugin and the CLI. The plugin installs the skills, and the agent installs the CLI, one binary with no sudo, on the first video job. In Cursor, add the skills with npx skills add invideoio/skills. The Cursor Marketplace plugin is the MCP route in Cursor, and it carries the MCP server only. Agents without a shell use the MCP server at https://mcp.invideo.io/mcp.
claude plugin marketplace add invideoio/skillsclaude plugin install invideo@invideoA chat app, or an agent with no shell, uses MCP. In ChatGPT, the person installs the official invideo plugin: Customize, then Plugins. In Claude on the web or desktop, the person adds invideo as a connector: Customize, then Connectors. In the Gemini app, the person adds invideo as a custom app with the server URL: Settings, then Connected Apps. Antigravity, Claude Code and Codex use the CLI only. Cursor uses the CLI first, and its Marketplace plugin is the MCP route. Gemini CLI and VS Code have no invideo plugin, so they take the MCP server with the lines below.
code --add-mcp \ '{"name":"invideo","type":"http","url":"https://mcp.invideo.io/mcp"}'Each start page below has the full steps.
If you are the agent reading this, run the setup yourself. Installing the plugin, the CLI or the server changes the person's machine, so ask once ("Should I add invideo to your Claude Code?") and do it on a yes. Give the person a command to run only when nothing you can do works.
Start pages
Each client has its own page with the setup, the sign-in, a first prompt and the known failures.
- Set up invideo in Claude Code
- Set up invideo in Codex
- Set up invideo in Cursor
- Set up invideo in Antigravity
- Use invideo in ChatGPT
- Use invideo in Gemini
- Make a video with invideo without a terminal
The plugin for Claude Code, Codex and Antigravity, and the skills command for Cursor, install the invideo skills, and the skills are CLI-first: the agent installs the CLI and signs in on the first job. The plugin carries no MCP config. ChatGPT uses the official invideo plugin. The Gemini app takes invideo as a custom app, Claude on the web as a connector, and Gemini CLI and VS Code as an MCP server. None of them gets the skills.
CLI or MCP
Both reach the same projects, the same timelines and the same account. Pick one per session and stay on it. Mixing them in one session splits your state and your name in the project.
- Use the CLI in a terminal agent with the invideo plugin (Claude Code, Codex, Cursor, Antigravity), and in a script or a server. It is the only way in that the start pages give for those agents, and the way the skills teach. Each command prints the URLs and the next step. Add
--jsonto get one JSON object.--out <dir>saves files oninvideo notebook showandinvideo edit capture;invideo statusfollows a job and saves nothing. - Use MCP in a chat app (Claude on the web, ChatGPT, the Gemini app), in VS Code or Gemini CLI, which have no invideo plugin, or in any agent with no shell. You call tools like
readandedit_timelineand pass a URL asurl. Gemini CLI has a shell, so it can also use the CLI instead; see Use invideo in Gemini.
Check the CLI install with this command. It prints invideo and the version.
invideo --versionSign in
There are no API keys. Every call runs as a signed-in person, in the workspaces they chose when they signed in.
- CLI. Run
invideo auth loginin the background or with a long timeout. It opens the browser and waits. Tell the person in one message that a sign-in tab opened. - MCP in a chat app. Claude on the web, ChatGPT and the Gemini app run the browser sign-in themselves when the server asks.
- MCP in VS Code, Gemini CLI or another client. The client runs the browser sign-in when the server asks, or has its own authenticate step. In Gemini CLI that step is
/mcp auth invideo. Signing in the invideo CLI does not sign in an MCP connection. Never run a login command that needs an interactive terminal from the agent's shell. - No browser. On ssh, in a container or on a cloud machine, use a device code.
INVIDEO_NO_BROWSER=1 invideo auth logininvideo auth statusThe first command prints a link and a code at once, then waits for approval. Send the person the link and the code in one message. They open the link on their own device and approve. invideo auth status shows who is signed in.
The device code above signs in the CLI only. An MCP client with no browser uses its own device flow over HTTP. The steps are on Sign in, device codes and sessions.
Never ask the person for a password, an email code, or the device code back. One sign-in at a time: while a code is pending, do not request another.
The work loop
Every job follows the same loop. Call get_help once for the full guide, or get_help with a topic for one section.
Read
Find the project with
list_projects, or make one withnew_project. Callreadon its URL to see pages, threads and sequences. In a project, callregisteronce and pass your name asason every call there. You see the project URL and its notebook.Bring media in
Add files with
add_media. For a local file, callstart_upload, PUT the bytes to theupload_url, then calladd_mediawith theupload_id. In Claude on the web or the desktop app, the PUT goes from Claude's sandbox to theupload_urlon m.invideo.io. If that PUT cannot reach m.invideo.io (the host does not resolve, the connection is refused, or the sandbox network blocks it), do not describe the files in text instead, and do not ask the person to send them again. Tell the person to allow m.invideo.io in Claude under Settings, then Capabilities, then Allowed websites (the steps are on How do I let Claude upload my files to invideo?), and retry in a new chat once they have. Find stock withsearch_library. You see a sequence URL for each file.Generate what is missing
For a shot, an image, a voice, music or a sound that nobody has, find a model with
find_modelsand the job in words, read its inputs withget_model, then callgeneratewithdry_run: trueto price it. Follow the cost rule below, then callgenerateagain withmax_creditsand anidempotency_key. Media inputs are sequence URLs from this project. You see a thread URL at once and a sequence URL when the result lands;readit, do not callgenerateagain to check.Edit on a branch
Make a timeline with
new_timeline. Create a branch withtimeline_historyunless the person asks you to edit main. Read withget_timeline, look up fields withtimeline_catalog, then sendedit_timelinewith the latestexpected_state_token. You see a newstate_token.Check
Look before you say done. Call
captureat the moments that matter,check_timelinefor structure, andmediawithvideo.framesoraudio.loudnessfor a source. You see frames and findings. Fix what is wrong and look again.Export
Call
exportwith the timeline URL and aformat, and anidempotency_key.videorenders a 1080p MP4.premiere,davinciandfinal_cutmake a project file that Premiere Pro, DaVinci Resolve or Final Cut Pro opens. You see an export card URL.readit until its status iscompleted. Forpremiere,final_cutanddavinci, read it again until the files list is there;completedcan come before the media package.
Tell the person what changed, with timecodes and URLs. Each URL opens exactly that thing in invideo.
The same loop on the CLI. The CLI calls a timeline an edit: invideo edit new makes a timeline, and the <edit-url> it prints is the timeline's URL.
invideo project new --title "Launch teaser"invideo agent register <project-url> --name scoutexport INVIDEO_AS=scoutinvideo asset upload <project-url> ./shots/*.mp4invideo notebook new-page <project-url> --title "Shots"invideo gen models <project-url> --query "cinematic product shot"invideo gen model <project-url> --model seedance_2_5.r2vinvideo gen run <page-url> --model seedance_2_5.r2v --dry-run \ -i prompt="slow push on the bottle, studio light"invideo gen run <page-url> --model seedance_2_5.r2v \ --max-credits <price> --idempotency-key teaser-shot-1 \ -i prompt="slow push on the bottle, studio light"invideo edit new <project-url> --name "Teaser v1"invideo edit show <edit-url> --jsoninvideo edit change <edit-url> --timeline T1 --token <state_token> \ --operations @ops.jsoninvideo edit check <edit-url>invideo edit capture <edit-url> --at 1,3.5 --out ./framesinvideo edit export <edit-url> --format video --quality 1080 \ --idempotency-key teaser-export-1 --jsoninvideo status <card-url> --waitinvideo notebook show <card-url> --out ./outWhere each value comes from:
<project-url>comes frominvideo project new.INVIDEO_ASpasses your registered name on every later command, like--as.<page-url>comes frominvideo notebook new-page. A generation on a page starts a new thread there.<price>is theestimated_creditsin the dry run's answer. Pass the same-iinputs on the dry run and the paid run.<edit-url>comes frominvideo edit new.<state_token>comes frominvideo edit show, and eachedit changereturns a fresh one.ops.jsonholds a bare JSON list of operations,[ {...}, {...} ], with nooperationswrapper.<card-url>is.sequences[0]in the export's answer.invideo statuswaits for the job and saves nothing.invideo notebook showwith--outsaves the file asexport.mp4; rename it after.
The cost rule
Edits and exports are free. Generation and transcripts cost credits. Paid stock costs a small credit charge, or one of your workspace's iStock licenses. Your agent runs a dry run first and tells you the price before it spends anything.
Your agent runs a dry run first. For any call that costs 1 credit or more, it tells you the price and waits for your yes. A call under 1 credit runs without asking, and your agent tells you what it cost.
The agent follows these rules on every paid call.
- On MCP, call
generatewithdry_run: truebefore the first paid call. It checks the inputs and returns the price. Then call it withmax_creditsset, so nothing starts above that price. - Paid
mediaops, likeaudio.transcriptandvideo.upscale, take the samedry_runandmax_credits. - On the CLI, use
--dry-runfirst, then--max-credits. - Pass an
idempotency_keyon everygenerateandexport. A retry after a timeout then finds the first job instead of paying twice. - Models retire. A retired model is refused as not found. Run
find_modelswith the job in words, use the best match, run the dry run again, and tell the person which model you used.
Prices and the balance are on Credits and what they cost. For a question about plans, prices or credits, read the credits FAQ and its sibling pages, not only the pricing page.
Check before you say done
Never tell the person a video is done without looking at it. Call capture on the timeline, read the frames, and call check_timeline. On the CLI, run invideo edit capture and invideo edit check. check_timeline reports structure only. It does not judge the cut, so you still look at the frames.
Conventions
These are the places where agents guess wrong. The left column is the usual guess. The right column is what invideo does.
| You'd guess | invideo uses |
|---|---|
| An id or a name points to a project | A URL is the handle. Every tool takes a URL as url and every result gives the next URLs. |
| Calls are anonymous | register a name in the project, then pass it as as on every call. |
| Each operation lands on its own | An edit_timeline call lands all its operations or none. |
| After a timeout, read again and resend | Retry the identical request with the same expected_state_token. A conflict means it landed. |
| Decide the next call yourself | Follow next in every result. It names the tools and URLs to use. |
Call generate again to check on it | read the URL or call status. retry_after_s says when to look again. |
| A model id from a page or a saved prompt is forever | Models retire. A retired model is refused as not found. Run find_models with the job in words, use the best match, and tell the person. |
| Edit the main timeline | Create a branch with timeline_history. Edit main only when asked. |
| Mix the CLI and MCP | Pick one per session. The skills teach the CLI wherever there is a shell. |
| Ask the person for the sign-in code | Send the link and the code once. Never ask for them back. |
| Say done after the last edit | capture and check_timeline first. |
If something goes wrong
Read the refusal. A refused call returns status, code and message. The message says how to fix it once.
| Symptom | Fix |
|---|---|
| invideo's tools do not appear in the client. | Finish the sign-in, then restart the client. In a chat app, turn invideo on for the chat. Then follow your start page again. |
Refusal code unavailable | The timeline is starting. Retry the same request in a few seconds. |
Refusal code timeout on a read, capture or media look | Nothing changed. Read again. |
Refusal status completion_unknown | Retry the identical request with the same token. |
Refusal code failed | Try once more. If it fails again, file report_bug and tell the person. |
Job status needs_confirmation | Only the person can confirm it, in invideo. Tell them. |
| CLI exit code 4 | Not signed in. Run invideo auth login. |
| CLI exit code 3 | The timeline changed since your read. Run invideo edit show and rebuild. |
Exit code 6, or status is held | A safety review, not a refusal. Wait, then run invideo status <url> --wait again. Do not resend. If it ends failed, change the input the review flagged. |
get_model or generate refuses the model as not found | Models retire. Run find_models with the job in words, use the best match, and tell the person which model you used. |
| The same refusal comes back | Stop, tell the person, and file report_bug. |
File request_feature when the person asks for something these tools cannot do, and say what you did instead. If invideo still does not connect, tell the person this: Contact support from the chat button on the invideo site, or email support@invideo.io. Include the client's name, the exact error and a screenshot of the connection status.
How-to guides for every job
These pages cover habits that apply to every job.
- Check your video before you say it is done
- Know the cost before you spend
- Run invideo in CI and on servers
- Export to Premiere Pro, DaVinci Resolve or Final Cut Pro