askNextSteps
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by endSession. Ask the user what comes next for what endSession built: renders the card with the next steps, and returns the build report to relay — the project link, what became editable, what did not survive. Call it after repairProject: straight away when it reports nothing to repair, or with repaired on the build once its repairs are made. Call it ONCE per request, with every build the request produced in builds — one entry even when there is just one; the one card lets the user choose next steps for each — and with suggestedOptions when this user's stored preferences point to a step the standard choices do not offer. The card renders below everything said before it.
askQuestions
ChatGPTAsk the user one or more questions in a form: they tap a suggested answer, type their own, or skip. Use it for anything you need before building that the user has not told you, no source gives you and their userPreferences do not settle, and tailor the questions and options to those preferences. It runs inside a live session: first call startSession — or startEditSession when the user wants a built project changed — and pass the sessionId it returned. After calling it, end your turn — the answers arrive as the user's next message.
browseButterUploads
ChatGPTLook through the files the user has uploaded to Butter: the Uploads section of their active workspace. Read only. Lists the newest first, with the folders at the top level first; open a folder by passing its id as folderId. Narrow by kind (image, video or audio). Search by name with query, and by when a file was uploaded with addedAfter and addedBefore: a search looks through every folder, naming the folder of each file it finds, unless folderId limits it to one. Each file comes with its upload date, and a picture of the images and videos, numbered as listed, comes with the list. Brand kit assets are not listed here: getBrandKit returns those. Browsing hosts nothing: bring a file you use into the session with uploadSessionAsset, passing its url.
browseConnectorAssets
ChatGPTLook through the files in one of the connectedSources startSession returned: the file stores, such as Google Drive or Dropbox, that the user's Butter workspace has connected. Lists one folder at a time, the top level when folderId is left out, or searches by name with query. Each item comes back with its id and kind (folder, image, video, audio or file): open a folder by passing its id as folderId, and bring an image, video or audio file into the session with importConnectorAsset. Browsing hosts nothing.
claimSession
ChatGPTSign the user in and move an anonymous session's project permanently into their Butter account. Call this after endSession reports a temporary project. Before calling: if the studio tab is open, call save_project then close that tab to prevent edits racing the claim. This tool requires the user to log in — it will prompt them if they are not already signed in. On success it returns a new magic-linked studio URL; open it in a fresh tab so the user can see their saved project.
cloneProject
ChatGPTDuplicate a built Butter project, everything surviving verbatim — custom blocks and studio edits included. Use it when the user wants a new version with small changes while keeping the original: clone, then startEditSession on the clone. A new take that re-authors the video is a fresh startSession instead, informed by describeProject.
createProject
ChatGPTCreate the session's one Butter project, where the video is built: forked from the template the user chose, or blank at the canvas size the video needs. Registers the project on the session and imports every asset and font already uploaded to the session so the studio can place them. Call it once intake has settled the template or the format. Returns the muted studio link, a still per template scene, the imported assets' ids and urls, and how to build the video in the studio with its page tools.
createProjectFromTemplate
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by createProject. Start a project from the Butter template the user chose: forks it into the user's library, registers the project on the session, and imports every asset and font already uploaded to the session so the studio can place them. Call it as soon as the template is chosen, before gathering any images or footage — the fork is where you learn what the template needs: watch it in its studio, inventory its shots, then gather what fits each one and the ad as a whole, and bring later files in through importSessionAssets. Returns the muted studio link, a still per scene, and the ids and urls the page tools need. Use it instead of writing HTML when the user chose a template.
describeProject
ChatGPTRead the current state of a built Butter project — including every edit made in the studio since it was built. Call it before building a variant or adaptation of a project, so those edits carry forward. Custom blocks and unknown components are listed as opaque references.
endEditSession
ChatGPTClose edit sessions as soon as the requested changes are saved — do not wait for the user to approve first. Call it ONCE per request, with every edit session the request opened in sessions — one entry even when there is just one; the one card lets the user choose next steps for each edited project. Each entry carries the summary of what actually changed in that project, and any requested change you could not make in its failures. The result renders the next-steps card again, built from each project as its edit left it; the card is how the user reviews and asks for more.
endSession
ChatGPTClose build sessions once their projects are finished in the studio — do not wait for the user to approve first. Call it ONCE per request, with every build session the request opened in sessions — one entry even when there is just one; each must have made its project with createProject. Each entry carries a summary of the project, and anything the user asked for that you could not make in its failures. The result renders the next-steps card, built from each project as the studio left it; the card gives the user the link and how to ask for more. A successful endSession ends the session for good: it accepts no further calls. Its project stays reachable through its id — startEditSession changes it in place — and anything new starts a session of its own, the way the next steps route it.
exportLocally
ChatGPTGenerate a ready-to-run terminal command that exports a Butter project to the user's computer in the background — no cloud costs, and the browser tab does not need to stay focused. Prefer this over clicking the export button when the user asks to export and hasn't expressed a preference, since it is simpler and runs unattended. Returns a command (npx butter-export "...") and install instructions. When the user is signed in the URL is a one-time magic link that expires in 15 minutes; for anonymous sessions it is a plain URL.
generateSessionAssets
ChatGPTGenerate images, short clips and sound with AI, hosted on Butter, for a video the user's own assets cannot fill. Call it only after the user agreed to generation in an askQuestions answer — at intake or when the assets fell short — and only for what their answer allows. Once they have agreed, calling it is required: generate before building the scenes and build them on what it returns. Shapes, gradients, code components or type do not replace it. Every asset spends the user's AI credits, a clip several times what an image does and a sound about what an image does. A workspace without enough credits gets nothing generated and pays nothing. Up to 4 assets per call, generated in parallel, and 12 per session. Results come back already in the user's Butter library, with the assetId replace_asset and add_audio_track take: never pass them through uploadSessionAsset. Never generate a logo, on-screen text, or the user's product itself — those come from the user or their site. Generate what surrounds them: settings, textures, people, b-roll. To show the real product in motion, upload its photo with uploadSessionAsset and give a clip its hostedUrl as imageUrl. It makes sound as well as pictures: music for a bed, soundEffect for one moment, voiceover for a read. Generate sound only when the user's own answer about sound chose to generate it, and only the kinds they picked there: agreeing to generated images is not agreeing to sound. An image or a sound takes seconds, a clip a minute or more: a call returns what finished within about 45 seconds and a jobId for the rest, which a later call collects through jobIds.
getBrandKit
ChatGPTRead the user's active Butter brand kit: its colors, fonts, assets (logos, product images, lifestyle images and video, talking heads and the like, each with the sections it is filed under) and what it says about the brand, its tone and voice. Read only. When the video should be on-brand, read it before looking anywhere else for the palette, logo or typeface. Its assets are already in the user's library: place them with replace_asset or add_audio_track by url and id.
getWorkflow
ChatGPTGet the full instructions for one Butter workflow — the questions to ask, what to gather, what to keep and vary, how many videos to make, how to build each one, and the handoff. Follow what it returns exactly.
importConnectorAsset
ChatGPTBring a file from one of the connectedSources startSession returned into the user's Butter uploads, in this session's folder, and get back its library url and assetId, what replace_asset and add_audio_track take in the studio, and its hostedUrl, what transcribeFootage and a clip's imageUrl take. Import each file once and reuse its assetId. Pass the id browseConnectorAssets listed it under. Images, videos and audio files: images up to 40MB and 50 megapixels, videos up to 1GB; not folders, and not Google Docs, Sheets or Slides.
importSessionAssets
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by createProject. Import the session's uploads and generated files that arrived after createProjectFromTemplate into the user's library, so the studio page tools can place them: returns each one's url and assetId. Files already imported are skipped. Not needed for files that were on the session when the project was created.
listWorkflows
ChatGPTList the Butter workflows available for making ads and videos, optionally for one intent (create, remix-ad, scale-winners). The starting point for any request to make, remix or scale video or ad creative, including vague ones such as "make me a video" or "what can you make for my brand?". Returns each workflow title with when to use it; pick one, then call getWorkflow with its title.
prepareEndSession
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by endSession. Provides the instructions for ending the session: how to measure a submitted version into the manifest endSession requires. Call it as soon as the version you are shipping is submitted with no blocking lint findings, without showing it to the user or waiting for their approval, then call endSession — endSession cannot be called for a version until prepareEndSession has been called for it, and a version with blocking findings is refused.
projectLinks
ChatGPTThe next-steps card calls this by itself to refresh project links after one is opened. You never need to call it, and its result carries nothing to relay.
projectThumbnails
ChatGPTThe next-steps card calls this by itself to fill in project thumbnails as their screenshots finish. You never need to call it, and its result carries nothing to relay.
repairProject
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by endSession. Finish a project before the user meets it. For the project endSession just built: repair what did not survive conversion, and run the project tasks requested at endSession — work done on the built project in its studio. Call it straight after endSession, with the same ids, before telling the user anything — do not ask first. When nothing needs doing it hands you on to askNextSteps; when something does it returns the studio steps, ending on askNextSteps with how the repairs and each task went. For a project created from a template, call it with the projectId once the template is filled: it returns a visual pass to make in the studio — watching the project for unreadable text and cropped copy or images — ending on askNextSteps.
requestAssetUpload
ChatGPTStart an upload of a local file too large for uploadSessionAsset's dataBase64 (over 2MB), for callers that can run a shell command. Returns a signed upload: run the curl command given to upload the file directly so its bytes never pass through the conversation (images and audio use multipart POST; videos use a plain PUT). Then call uploadSessionAsset with the uploadId to get the url to use. The signature expires after an hour. Images up to 40MB, videos and audio up to 100MB, in common formats (no SVG). A larger file, or one with a public https link, goes to uploadSessionAsset as url instead.
searchTemplates
ChatGPTKeyword-search Butter's library of ~1000 production-grade ad templates during design research. It returns video templates unless static asks for still ones. Each template is indexed by name, tags, aspect ratio and a one-paragraph visual description, so queries work best as concrete visual and structural words (industry, theme, layout, motion, mood) — never brand names. Returns the merged ranking with a link to open each template; judge the fit yourself from the descriptions and by opening the links. Read-only: it does not create or change a project.
startEditSession
ChatGPTOpen edit sessions on built Butter projects, to change those projects in place by driving the Butter editor in the browser. Use it when the user wants the built projects themselves changed; a variant or a new video is a fresh startSession instead. Call it ONCE per request, with every project the request edits in projects — one entry even when there is just one; it opens one edit session per project, and one endEditSession call closes them all. Returns each project's edit session id and studio link.
startSession
ChatGPTOpen a Butter video session: one session makes one project. Returns the session id, the preferences stored for this user, the file stores their workspace has connected, and how the session runs — intake, then createProject, then building the video in the Butter studio, then endSession. If this chat has already started a Butter session, pass the id of the most recent one as previousSessionId, so the sessions of one conversation link up.
submitSessionVersion
ChatGPTRetired stub — always errors and does nothing. Original description: Deprecated: replaced by endSession. Submit a version of the video as one self-contained, self-playing HTML document. Returns lint findings. Never show the user the HTML or anything rendered from it. Once the version you are shipping has no blocking findings, call prepareEndSession next.
uploadSessionAsset
ChatGPTBring an image, video or audio file into the user's Butter uploads, in this session's folder, and get back its library url and assetId, what replace_asset and add_audio_track take in the studio, and its hostedUrl, what transcribeFootage and a clip's imageUrl take. Bring each file in once and reuse its assetId wherever the same asset appears, across variants included. Prefer url — the server fetches it, and nothing binary passes through the conversation. Use dataBase64 only for bytes that exist nowhere else, such as a small local file or a screenshot you just captured. A local file too large for dataBase64 goes through requestAssetUpload, then here with its uploadId. A file the user attached in the chat goes in as file when the host passes attachments to tools; never pass a sandbox path as url. A file already in the user's Butter library (browseButterUploads, getBrandKit) needs no upload: use its url and id as they are.
uploadSessionFont
ChatGPTAdd a font that is not on Google Fonts or in the brand kit, such as a brand's own typeface or a file the user supplied, to the user's Butter fonts, so set_font and replace_font resolve it by family. Call it once per weight and style: each call adds one font file. Prefer url: find the font file in the brand site's @font-face CSS or its <link rel="preload" as="font">. woff2, woff, ttf and otf are accepted, but the file must be a static weight: a variable font is refused, because Butter draws text pinned to one as blank. Upload each file once. Google Fonts never go through this tool.
