Framesail

Tools · 68

• activate_script_version

  Switch the project's active script to another saved version (ids come from get\_script's version list — every save\_script creates one). Re-run scan\_script / rescan\_voice\_blocks afterwards if the text differs, since downstream artifacts follow the active version.

• add_music_track

  Add background music to the project from the audio library (find track ids with browse\_audio\_library, category="music"). Defaults loop the track under the whole video at bed level (volume 0.2 ≈ -14 dB under narration — don't raise it without being asked); re-run export\_video to hear it.

• add_segment_sfx

  Attach a sound effect from the audio library to a segment (find track ids via browse\_audio\_library with category="sfx"). Re-run build\_scenes to get it onto the timeline.

• analyze_style

  Re-run style analysis (after changing a style's inputs). Async — await\_jobs(style\_id=...) until the style\_analysis job completes.

• await_jobs

  Block (server-side) until the scope has no pending/running jobs, or the timeout passes — use this instead of polling get\_workflow\_status yourself. Returns {done, jobs}. If done=false the work is still running: just call await\_jobs again (a 3-5 minute storyboard takes a few consecutive calls). Keep timeout\_seconds <= 50 so the client doesn't time out the tool call.

• browse_audio_library

  Browse the audio library for background music and sound effects. category: "music" | "sfx". Returns track ids for add\_music\_track / add\_segment\_sfx.

• build_scenes

  Compile segments + assets + voiceover into the editor/render timeline (scenes). Run after segment assets are complete, before export.

• change_segment_type

  Change a segment's visual type: "image" | "video" | "overlay\_scene". carry\_frame=true reuses the already-rendered image as the video start frame (or vice versa) instead of recreating it.

• combine_segments

  Merge a segment with an adjacent one (segment numbers must be neighbors). keep: "this" | "other" — whose creative data survives. Later segments renumber — re-check get\_segments before further edits.

• create_asset

  Manually add a character/environment/object the scan missed. asset\_type: "character" | "environment" | "object". The description is the generation-facing spec of its look — be specific.

• create_channel

  Create a new channel — the container for projects and their reusable styles. Use when the user wants a fresh creative identity rather than adding to an existing channel.

• create_project

  Create a project. The description (the video concept/topic) seeds script generation, so write a meaningful one. The response's web\_url is the project's page in the web app — share it so the user can follow along.

• create_style

  Create a style. Two mutually exclusive paths: ``` References (best): inputs=[{"input_type": "youtube" | "text", "value": "<url or description>"}] — YouTube videos are watched and text directions read; async analysis writes the style's art/narrative/director fields: await_jobs(style_id=...) before using the style. (Image/video FILE references require the multipart REST endpoint POST /styles.) Presets (instant, no analysis): presets={"art_style": id, "narrative_style": id, "director_style": id} — all three axes, ids from list_style_presets. ```

• delete_asset

  Delete a project asset (e.g. one the scan over-extracted).

• delete_project

  Permanently delete a project and everything in it (script versions, assets, voiceover, segments, renders). Irreversible — confirm with your user first.

• delete_style

  Delete a style (e.g. a failed analysis experiment). Don't delete a style that projects still use as their default — rebind them first with set\_project\_style.

• director_note

  Edit ONE scene with a natural-language note (the same director chat the editor UI uses): move/restyle/add/remove layers and overlays, retime, etc. Synchronous — returns the applied mutations + updated scene. Use list\_scenes to find scene ids; for notes spanning the whole video use project\_director\_note instead.

• export_video

  Render the final MP4 (Remotion). Fetches the current timeline and queues the render. Async — poll get\_workflow\_status for the video\_export job, then call get\_video\_url.

• generate_asset_reference

  Render an asset's reference image in the channel's art style — the visual anchor that keeps a character/environment looking identical across every shot. EVERY character, environment, and object asset needs one before generate\_voiceover (the server enforces this; fire the jobs for all assets, then one await\_jobs). Async — the job writes the image onto the asset row: await\_jobs(project\_id), then list\_assets and view\_image the file\_path to check likeness.

• generate_script

  Generate the project's script from its description/concept and the channel's narrative style. Async — returns {job\_id}; poll get\_workflow\_status.

• generate_segments

  Render every actionable segment asset (images, video clips, overlays) across the project, in dependency order. THE most expensive call in the pipeline: ALWAYS dry\_run=true first, show your user the estimate next to get\_credit\_balance, and wait for a fresh yes before the real run — prior blanket permission ("do the whole thing") does not cover this spend. Pass segment\_numbers to render only a subset — e.g. segments 1-18 for the opening minute before committing to the full video. Safe to re-run: completed and currently-generating assets are skipped, so a second call only picks up new/failed work. Async — one job per asset; await\_jobs until all complete.

• generate_storyboard

  Plan the full visual storyboard: segments, shot pacing, image/video prompts, overlays, continuation chains — driven by the channel's director and art styles. Requires voiceover to exist (timing comes from it). BEFORE calling: confirm the project's asset\_mix with your user (image vs video vs generated\_graphic percentages, update\_project) — the storyboard plans against it and video-heavy mixes multiply the later render cost. Async — returns {job\_id}; this is the longest LLM step.

• generate_style_template

  Render one of a style's two template images — a REAL step of style setup, not an optional extra: a style isn't finished until both its character and environment templates are rendered (the app shows them on the style card). Asset reference images render against them (characters → character template; environments and objects → environment template), and segment renders fall back on them when a shot has no asset reference — so finish BOTH before generate\_asset\_reference. Run once per template\_type ("character" | "environment") for every new style; skip only types the style already has (get\_style shows them). Async — await\_jobs(style\_id=...), then get\_style.

• generate_voiceover

  Generate TTS audio for the project's voice blocks. Without voice\_block\_ids it fills gaps: only blocks with no audio yet run, so re-calling it is always safe (already-generated and currently-generating blocks are skipped, never re-billed). Pass voice\_block\_ids to explicitly REgenerate those blocks (e.g. after changing a block's voice). Speakers must have voices bound first — set\_narrator\_voice / set\_character\_voice. Optional editable\_sections/settings apply to every selected block (see get\_section\_template("voice\_block") and list\_models("voice\_block")). Async — returns one job per block.

• get_credit_balance

  Current credit balance + plan info. Check before expensive steps (a full segment render can cost hundreds of credits — generate\_segments dry\_run gives the estimate). Jobs covered by a BYOK provider key bill 0.

• get_pipeline_progress

  THE resume/orientation tool: one call returns every pipeline step's state (script -> scan -> reference\_images -> voices -> voiceover -> style\_templates -> storyboard -> segment\_assets -> scenes -> export), any running jobs, and a next\_action telling you exactly what to do next. Call this when picking up an existing project, after any await\_jobs, or whenever you're unsure where a video stands — never guess pipeline position. ``` Every step carries a web_url — the page in the Framesail web app where your user can see that step's output. Share it whenever you present a step's results ("review the storyboard here: ...") so they can inspect and edit in the browser; the app and this API act on the same live state. ```

• get_project

  Fetch a project row — settings, voice config, default style, export URL.

• get_script

  Read the active script's full text + the version list. Use this to show the script to your user for review/feedback before scan\_script — the review-edit-resave loop (get\_script -> discuss -> save\_script) is the expected workflow when the user wants input.

• get_section_template

  Inspect the prompt sections a generation job exposes for per-call override via editable\_sections (jobs: script, script\_scan, storyboard, segment\_image, segment\_video, voice\_block, ...). Sections marked locked cannot be overridden.

• get_segment_assets

  List one segment's assets (images/video/overlays) including their status, config (prompts, model), and public URLs of rendered files — pass an image's public\_url to view\_image to actually look at it.

• get_segments

  List the storyboard's segments (narration span, type, duration, creative direction). The 1-based segment\_number is the handle every segment tool takes (update/split/combine/continuation/regenerate) — you never need a UUID. ``` Each segment also reports `continues_from_segment`. When set, this shot is a CONTINUATION of that earlier segment: its rendered frame carries over (same composition, characters, and setting) and only the delta changes — an added overlay, a shifted expression, a closer angle, a slow reframe. Null means a fresh, independent shot. The storyboard plans these chains automatically; adjust them with set_segment_continuation. ```

• get_style

  Fetch one style row — its inputs (reference material) and analyzed fields (art\_style, narrative\_style, director\_style, script\_prompt, ...). Show fields to the user for review; fine-tune with update\_style\_fields.

• get_video_url

  Download URL for the most recent completed export.

• get_workflow_status

  Poll this between steps: returns active + recently-finished AI jobs (scope by project\_id, or style\_id for style analysis), plus per-segment- asset render statuses for projects. A step is done when its jobs reach status=complete (or error, with a user-readable message). NOTE: finished jobs drop out of `jobs` after \~30s — a short list does NOT mean work was lost; judge render batches by `segment_assets` statuses (or get\_pipeline\_progress), never by counting jobs. Prefer await\_jobs over polling this in a tight loop.

• list_assets

  List the project's assets extracted by scan\_script — characters, environments, objects. Each has a description (the spec every shot uses to render it — surfaced top-level here; the raw row nests it at ai\_output.description), an optional reference image (file\_path is a public URL — view\_image it), and for characters a voice\_id. Review these after scan\_script: fix descriptions, then generate\_asset\_reference for each one (all of them need a reference image before voiceover). asset\_type filter: "character" | "environment" | "object".

• list_channels

  List your channels. Every project lives in a channel, which owns the reusable styles (art/narrative/director) that drive generation.

• list_models

  List the models allowed for a generation job, with display names, credit estimates, and each model's settings\_schema — the valid keys for that tool's `settings` param (e.g. image quality/orientation, video duration). The first entry is the default every tool uses when model is omitted.

• list_music_tracks

  List the project's background music tracks (volume, loop, timing).

• list_projects

  List projects in a channel.

• list_provider_keys

  List registered BYOK providers (masked — only the last 4 characters).

• list_scenes

  List the project's scenes (composition layers, durations, layout).

• list_style_presets

  The curated preset catalog for the no-AI style creation path, grouped by axis (art\_style / narrative\_style / director\_style). Show the user the labels + descriptions and let THEM pick one per axis — don't choose silently. Art presets include preview image URLs (view\_image works on them). Create with create\_style(presets={axis: id, ...}) — instant, no analysis job. Full field text lands on the style row (get\_style shows it after creation).

• list_styles

  List the channel's style rows (variable groups). Styles hold the art\_style / narrative\_style / director\_style / script\_prompt fields that drive every generation step, plus any custom @variables.

• list_voice_blocks

  List the project's voice blocks (per-speaker narration chunks) with their audio status and assigned voices.

• list_voices

  List available TTS voices (id, label, preview audio URL) for a provider: "minimax" (default engine) or "elevenlabs". Match the project's voice\_tts\_provider (see get\_project) so picked ids work with its engine.

• project_director_note

  Apply a project-WIDE director note ("make the intro punchier", "all captions bigger", "tighten pacing in the back half"). A routing pass picks only the scenes the note applies to and edits each one. Synchronous — a few seconds per affected scene. Returns the per-scene results; re-run export\_video afterwards to see changes in the final render.

• regenerate_segment_asset

  Regenerate a segment's primary image or video with optional overrides — the API equivalent of the editor's expert drawer. asset\_type: "image" | "video" (for a video segment, "image" targets its start frame). Use a different model, override prompt sections (see get\_section\_template("segment\_image")), or tweak settings (e.g. image quality), then re-run just this asset. Async — returns {job\_id}.

• remove_music_track

  Remove a music track from the project.

• remove_segment_sfx

  Remove a sound effect from a segment. With one SFX attached, no name needed; with several, pass sfx\_name (the asset name shown by get\_segment\_assets).

• rescan_voice_blocks

  Re-extract voice blocks from the active script WITHOUT touching assets or their reference images — the non-destructive alternative to scan\_script after a script edit. Existing audio is superseded by the new block split, so re-run generate\_voiceover afterwards. Async — returns {job\_id}.

• revise_script

  AI-rewrite a passage of the active script in the project's narrative voice (the same in-editor revise the UI offers). selected\_text must appear verbatim in the script; omit it to revise the whole script. Synchronous — returns {revised\_text}, which is NOT saved: splice it over selected\_text (or replace the full script) and call save\_script to keep it.

• save_script

  Save script text (your own draft, or an edited version of the generated one — saving creates a new version, old versions are kept). Run scan\_script afterwards so assets and voice blocks reflect the new text.

• scan_script

  Analyze the active script: extracts character/environment/object assets and splits narration into voice blocks. DESTRUCTIVE on re-run (assets are recreated, not merged — curated descriptions, reference images, and voices are lost; prefer rescan\_voice\_blocks after script edits). Async — returns {job\_id}.

• set_character_voice

  Bind a TTS voice to a character asset — required before generate\_voiceover for every character with dialogue (the narrator's voice is separate: set\_narrator\_voice). Browse ids with list\_voices.

• set_narrator_voice

  Set the project's narrator TTS voice — required before generate\_voiceover whenever the script has narration. Browse ids with list\_voices. (Character dialogue voices are separate: set\_character\_voice.)

• set_project_style

  Set the project's default style — the style whose art/narrative/director fields drive its generations. Use after create\_style to put a new visual identity into effect, or to switch a project between channel styles.

• set_provider_key

  Register a BYOK provider API key (encrypted at rest, BYOK plan only). Jobs whose model belongs to this provider then run on YOUR key and charge 0 credits. Providers: openai, gemini, anthropic, fal, elevenlabs, minimax.

• set_segment_continuation

  Make a segment's image render as a continuation of an EARLIER segment's frame (same composition evolving — the storyboard's continues\_from\_segment, settable after the fact). continues\_from is that earlier segment's number; pass 0 to clear the link. Regenerate the segment's image afterwards — the reference is applied at generation time.

• split_segment

  Split a segment at the given time offsets (ms, 1-3 cuts → 2-4 parts). inherit\_index picks which resulting part keeps the original creative data. Later segments renumber — re-check get\_segments before further edits.

• update_asset

  Rename an asset and/or rewrite its description. If the look changed, regenerate its reference image afterwards so renders match.

• update_caption_config

  Merge a patch into the project's burned-in caption config (keys like enabled, plus styling). Read the current value from get\_project (caption\_config). Applies at the next export — no rebuild needed.

• update_music_track

  Tweak a music track. fields keys: name, volume (0-1), loop, start\_frame, duration\_frames, position, trim\_start\_frame, trim\_end\_frame.

• update_project

  Patch project fields. Updatable: title, description, asset\_mix, sfx\_level, video\_concept, voice\_mix, voice\_tts\_provider, script\_target\_minutes, narrator\_speed. (The narrator's TTS voice is NOT here — use set\_narrator\_voice.)

• update_segment_content

  Rewrite one segment's creative direction from feedback ("make this shot a close-up", "show the machine from above") — an LLM rewrites the shot's prompts; continuation links, SFX, and overlays are preserved. The visual assets reset to not\_started: re-render them afterwards (generate\_segments or regenerate\_segment\_asset). For a precise prompt tweak with no rewrite, use regenerate\_segment\_asset with editable\_sections instead.

• update_style_fields

  Hand-edit a style's analyzed fields after reviewing them — e.g. tighten the art\_style wording or adjust the director\_style pacing rules. `fields` is the FULL flat dict to write: {key: {"value": str, "applies\_to": \[...]}} (fetch with get\_style, modify, send back). Editing fields does NOT trigger re-analysis, so your edits stick.

• update_voice_block

  Override one voice block's voice or playback volume (block ids from list\_voice\_blocks). Re-run generate\_voiceover for the block afterwards if you changed its voice — existing audio is not regenerated automatically.

• view_image

  Fetch a rendered Framesail image so you (and your user) can SEE it — pass a URL from get\_segment\_assets, get\_style, or asset endpoints. Returns the image inline. Only Framesail media URLs are allowed.

• whoami

  Verify the connection: the account email and plan behind the current credential. Call once after connecting — before creating anything — to confirm you're on the right account; costs nothing.