Butter

Ask the user what comes next for what endSession built: it 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.

Ask 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.

Look 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.

Duplicate 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.

Read 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; the session html only knows the project as originally built. Custom blocks and unknown components are listed as opaque references.

Close 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.

Finish the session and turn a submitted version into an editable Butter project. Call it straight after prepareEndSession, without waiting for the user's approval. It cannot be called until prepareEndSession has been called for the same version: that returns the instructions for building the manifest this takes. A successful result carries only the ids; call repairProject with them next — the project link and the build report reach the user through the card it routes to. A successful endSession ends the session for good: it accepts no further calls, and only repairProject and askNextSteps still take its ids. Any work after it starts a session of its own, the way the next steps route it.

Generate images and short clips 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 writing any HTML and build the scenes on what it returns. Visuals drawn in CSS, SVG or type do not replace it. Every asset spends the user's AI credits, a clip several times 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 hosted: use their urls as they are, never 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 that url as `imageUrl`. An image 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`.

Get 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.

Bring a file from one of the connectedSources startSession returned into the session, hosted on Butter, and get back the url to use in its place. It counts as an upload in every way: the page and the manifest use the url exactly as one uploadSessionAsset returned, and it stays valid in later sessions, so import each file once. 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.