Framevine

Append generated videos from a thread to its timeline, in the order given. Goes into the active cut unless cutId is given; a first cut is created if the thread has none. Only video nodes that have not failed can be added, and a video already in the cut is skipped. Returns the updated timeline.

Create a new, empty cut (an alternative edit) on a thread's timeline. Returns the new cut; add clips with add_clips_to_timeline.

Save an image from the user's library (for example one returned by upload_image) as a named reference, so prompts can reuse it as @Name. Names start with a letter, use only letters (any language, e.g. さくら), digits, '_', '.', '-' or '・', max 32 characters, and 'source' and 'imageN' are reserved. Names are unique per user.

Create a new, empty Framevine thread (a canvas that holds related generations). Optionally give it a title. Returns the thread id to use with the generation tools. Does not spend credits.

Remove a generation (node) from a thread, for example a bad take. This is a soft delete: it can be undone with restore_node, and credits already spent are not refunded.

Delete a named reference (ids from list_references) so its @Name no longer works in prompts. The image itself stays in the library.

Copy a cut with all its clips, so you can try a different edit without changing the original. Returns the new cut.

Edit an existing image node with a new instruction prompt (e.g. "make the sky pink"), producing a new image node. Use redo_generation to re-roll the same inputs instead. Spends credits. Returns immediately with a new nodeId and status; poll get_generation_status until it is COMPLETED or FAILED.

Edit an existing completed video node with a text instruction. prompt describes the change and what should stay unchanged. modelKey must be a video model from list_models that supports video editing. Spends credits; use estimate_cost first if unsure. Returns immediately with a new nodeId and status, plus the parent node it edited so you can confirm it was the right one; poll get_generation_status until it is COMPLETED or FAILED. If the user's intent is ambiguous across branches, call get_thread and ask which node before spending credits.

Get the exact credit cost of a generation before running it, plus whether the user's balance and storage can cover it. Does not spend credits. Use list_models for valid model keys.

Extend an existing completed video node with a continuation. prompt describes what happens next; pass endNodeId (a completed image node) to steer toward an end frame. modelKey comes from list_models (a video model) and durationSeconds must be one that model supports. Spends credits; use estimate_cost first if unsure. Returns immediately with a new nodeId and status, plus the parent node it extended so you can confirm it was the right one; poll get_generation_status until it is COMPLETED or FAILED. If the user's intent is ambiguous across branches, call get_thread and ask which node before spending credits.

Mark a thread as a favorite, or remove it from favorites. Does not spend credits.

Start generating a NEW image from a text prompt in a thread (create one with create_thread first). Spends credits; use estimate_cost first if unsure. Optionally pass sourceFileIds (file ids from upload_image or the library) as visual inputs. Use @Name to reference a named reference. Returns immediately with a nodeId and status; poll get_generation_status until it is COMPLETED or FAILED.

Start generating a NEW video from a text prompt in a thread (create one with create_thread first). modelKey comes from list_models (a video model) and durationSeconds must be one that model supports. Spends credits; use estimate_cost first if unsure. Optionally pass sourceFileIds (file ids from upload_image or the library) as start/reference frames. Returns immediately with a nodeId and status; poll get_generation_status until it is COMPLETED or FAILED.

Get the user's Framevine account usage in one call. credits: the current balance (total, plus subscription and purchased credits), how many credits they have used today and this month, and how many credits this connection can spend right now (availableToSpendCredits): the lower of the balance and what is left of the daily limit the user set for this app. connectionDailyLimitCredits and connectionRemainingTodayCredits are null when the user chose no daily limit. storage: their plan, used, total and available bytes, percent used, how many days files are kept, and a breakdown into uploads, generations and hidden files. Pass threadId to also get threadSpend: what that thread's generations cost (the total credits used, and for each generation, newest first, its operation, model, status and the credits charged, refunded and net). All of these are positive numbers of credits spent: totalCreditsUsed and netCredits are net of refunds (charged minus refunded). Call this first to check the user can afford generations and has room for large uploads or video, or after a purchase to confirm credits arrived. Use estimate_cost to see whether one specific generation will fit.

Check the status of one generation (node). Returns its status, progress percent (progressEstimated is true when it is estimated from typical run times rather than reported by the provider) and, when it failed, the failure reason; once complete, the output file id, media URL, thumbnail URL and dimensions. Poll this after starting a generation until the status is complete or failed. Once complete it also returns a small preview image (for a video, its poster frame) so you can see the result.

Get a fresh, signed download URL for one of the user's files (an outputFileId from a generation, or a fileId from the library). The URL works without signing in and expires after ttlMinutes (default 60, max 1440). Use it when an outputUrl has expired or is not directly downloadable. Fails if the file is still being generated or uploaded. For a generation's output it also returns a small preview image (for a video, its poster frame), since some clients can't open the URL themselves.

Get a Stripe Checkout link where the user can buy a credit pack. Nothing is charged by this tool: the user must open the link and pay on Stripe's page. Call without packId to list the available packs (packId, credits, price), then call again with the chosen packId.

Check a timeline render started by render_timeline. Returns its status (QUEUED, PROCESSING, COMPLETED, FAILED or CANCELLED), progress, and the output video URL once COMPLETED.

Get one Framevine thread with its nodes (generations) in order. Each node has its id, type (image or video), operation, status, progress, prompt, model, parent and child node ids (branches), and, once completed, the output file id, media URL and dimensions. Use node ids as inputs to edit, redo, or extend tools.

Show a thread's timeline: its cuts (named sequences of video clips), the active cut, and each clip's id, position, trim range, source video node, status and video URL. Use clip ids with reorder_clips and remove_clips. A thread with no timeline yet returns an empty cuts list.

Animate an existing completed image node into a video. The node is used as the start frame; pass endNodeId (another completed image node) to interpolate between two frames. modelKey comes from list_models (a video model) and durationSeconds must be one that model supports. Spends credits; use estimate_cost first if unsure. Returns immediately with a new nodeId and status; poll get_generation_status until it is COMPLETED or FAILED.

List the user's library folders, in their sidebar order, with each folder's id, name and thread count. Use a folder id with move_thread_to_folder.

List files in the user's library (uploads and generated outputs), paged. Each item has its file id, media kind, MIME type, name, size, purpose, media URL and creation time. Use a file id as an input to generation tools.

List the image and video generation models available on Framevine, with each model's modelKey, media type (image or video), supported durations and aspect ratios, and what image inputs it accepts. Call this before generating to pick a valid modelKey, and use estimate_cost for pricing.

List the user's most recently completed generations (images and videos) across all threads, newest first. Each item has its node id, thread id, type, operation, prompt, model, output file id, media URL and dimensions. Use the node id and thread id with get_thread or edit tools. Small preview images of the first few results are attached (videos show their poster frame).

List the user's named references (characters, objects and other images saved under a name). Mention one in a generation prompt as @Name to reuse it. Each item has its reference id, name, kind, file id, image URL and how many generations use it.

List the user's most recent Framevine threads (conversation-like canvases of generations), newest first, with each thread's id, title, favorite flag, node count, and the type and status of its latest generation. Use a thread id with get_thread to see its contents.

Move a thread into a library folder (folder ids come from list_folders), or out of any folder by omitting folderId.

Generate another take of an existing image or video node, reusing its original inputs and settings (use generate_image/generate_video for a new prompt from scratch). Optionally override the prompt, modelKey or image quality. Spends credits. Returns immediately with a new nodeId and status; poll get_generation_status until it is COMPLETED or FAILED.

Remove clips from a cut by clip id (from get_timeline). This only takes the clips off the timeline: the videos and their files stay in the thread and library and can be added again. Only the active cut can be changed. Returns the updated cut.

Rename a thread (change its title) or a cut on a thread's timeline. target is "thread" or "cut"; a cut also needs cutId. Does not spend credits.

Stitch the clips of a cut into one video. Does not spend credits (an identical render reuses the previous output), but renders use server CPU so they are limited per user (about 10 per hour). Returns a renderId and status; poll get_render_status until it is COMPLETED or FAILED.

Set the playback order of the clips in a cut. clipIds must list every clip of the cut exactly once in the new order (clip ids come from get_timeline). Only the active cut can be changed. Returns the cut.

Bring back a generation (node) removed with delete_node.

Rename a named reference or change its kind (reference ids come from list_references). Prompts that use the old @Name will no longer match it. Same naming rules as create_reference.

Add an image to the user's library and return its file id, for use as input to generation, reference and timeline tools. Provide exactly one of imageBase64 (raw base64 or a data: URL) or imageUrl (a public https URL). Content is safety-scanned like a normal upload.