com.framesail/framesail

Tools

• account_edit

  The account's default model and settings for one kind of generation, used when neither the call nor the item's prompt editor names one. voice_block needs provider and segment_video needs talking_head: each family keeps its own default.

  shallow
• 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.

  shallow
• 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.12 ≈ -18.4 dB under narration — don't raise it without being asked); re-run export_video to hear it.

  shallow
• 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.

  shallow
• analyze_style

  Re-run style analysis (after changing a style's inputs). Async — await_jobs(style_id=...) until the style_analysis job completes.

  shallow
• animate_segment

  Animate one segment in a single call: flip it to a generated video shot (keeping its rendered image as the clip's first frame) and START the clip render immediately. BILLS video credits on this call — the segment's image must already be rendered (400 otherwise). A refused generation (out of credits, already running) rolls the flip back, so the segment is either animating or exactly as it was. This is the ONLY way to a generated video (voice=true for a Talking Head) — change_segment_type refuses that target; it owns the other kind switches (real media, overlay scene, back to a still — segment_type "image" with carry_frame=true reverts an animated shot for free). Async — returns {ai_job_id, segment}; await_jobs until the clip completes.

  shallow
• assets_edit

  Add a character, environment or object that Analyze Script missed, or rename one or rewrite its description. After a description change, render its reference image again (assets_generate asset_ids).

  shallow
• assets_generate

  Render reference images, which keep each character, environment and object looking the same in every segment. Needs both style template images. Without asset_ids it renders every asset with none, skipping ones already rendering, so a repeat never bills twice. Afterwards, view_image them to check likeness.

  shallow
• assets_read

  The project's characters, environments and objects, each with its description (what every render follows), reference_image (null: not rendered; view_image it) and, for characters, voice_id. Each needs a reference image before the voiceover.

  shallow
• 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.

  shallow
• 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.

  shallow
• build_scenes

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

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• create_project

  Create a project. The description (the video concept/topic) seeds script generation, so write a meaningful one. Pass video_format='portrait' for a vertical video — every shot, overlay, and the export are then composed for a 9:16 frame. The response's web_url is the project's page in the web app — share it so the user can follow along.

  shallow
• create_style

  Create a style. Two mutually exclusive paths: References (best): inputs=[{"input_type": "youtube" | "text", "value": "<url or description>"}] — YouTube videos are watched (a channel link or @handle resolves to that channel's newest usable upload) 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.

  shallow
• delete

  Permanently delete; irreversible, so confirm with the user first. project: it and everything in it. asset: a character, environment or object. music_track: a background music track. segment_extra: a segment's sound effect or overlay, with its scene layers. A segment's image, clip and voiceover can't be deleted.

  shallow
• delete_asset

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

  shallow
• delete_project

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

  shallow
• 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.

  shallow
• 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. Address the scene by project_id + segment_number (preferred — always resolves to the current scene) or by scene_id from a fresh list_scenes call. Scene durations are locked to the narration track: don't ask to extend/shorten a scene except the final one — for a held-shot feel mid-video, ask for calmer/static motion on the scene instead. For notes spanning the whole video use project_director_note instead.

  shallow
• editor_edit

  Polish the video in the editor; changes show in the next export. scene_note: edit one scene with a note (move, restyle, add or remove layers and overlays, change the text of a lower third, title card or callout, change motion); spends credits. Returns the changes and skipped_mutations: edits that didn't land (applied=false) or landed differently than asked (applied=true), each with a reason; check them. Scene lengths follow the narration; the image, clip and voiceover layers can't be removed. project_note: a note for the whole video, applied to up to 10 scenes per call; spends credits. captions: merge caption settings. add_sfx: attach a sound effect to a segment. add_music / update_music: background music timed in seconds; a track's duration follows from its trim.

  shallow
• editor_read

  scenes: the editor timeline, one scene per segment, as {total, offset, returned, scenes}; scenes build on their own from the storyboard. music: {tracks}, timed in seconds. audio_library: tracks to add with editor_edit; when nothing matches, it lists the library's moods and genres.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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 types the style already has (get_style's `templates`). A template already exists is a hard stop here — the call refuses unless replace=True, because overwriting one silently re-anchors every future render. Async — await_jobs(style_id=...), then get_style.

  shallow
• 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.

  shallow
• 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.

  shallow
• get_generation_options

  What a generate call can be told to use. models: the allowed models with credit estimates and settings_schema (the valid settings keys); is_default marks the default (the account's saved choice, else Framesail's). Voice and clip models come in families, each with its own default: pass provider or talking_head for one family. prompt_sections: sections with entity_backed=false can be overridden with editable_sections; entity_backed=true sections show the item's own content (description, prompts, text, brief): change it with the edit tools.

  shallow
• 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.

  shallow
• get_project

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

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• get_status

  Where things stand and what to do next; start and resume here. Always reports the account: plan, credits, credits held by running jobs, and credits_available to spend. project_id adds the project's settings, each step's state and web link, jobs with readable errors, export_url and next_step. channel_id reports the channel style instead: analysis_done, inputs_stale, templates, templates_stale and next_step. Without API access it reports only the account and subscription_needed: pass that on to the user.

  shallow
• get_style

  Fetch one style row — its inputs (reference material), analyzed fields (art_style, narrative_style, director_style, script_prompt, ...), and `templates`: {"character": url|null, "environment": url|null}, the two template images. A null there means that template is genuinely missing and needs generate_style_template; a URL means it exists (view_image it) — don't re-render it. Show fields to the user for review; fine-tune with update_style_fields.

  shallow
• get_video_url

  Download URL for the most recent completed export.

  shallow
• 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.

  shallow
• 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".

  shallow
• list_channels

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

  shallow
• 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. Voice models carry a `provider` field — a voice_block model must match the project's voice_tts_provider or generate_voiceover rejects it.

  shallow
• list_music_tracks

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

  shallow
• list_projects

  List projects in a channel.

  shallow
• list_provider_keys

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

  shallow
• list_scenes

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

  shallow
• 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).

  shallow
• 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.

  shallow
• list_voice_blocks

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

  shallow
• 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.

  shallow
• 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.

  shallow
• projects_edit

  Create a channel or a project, or change a project's title, brief or video format. A new project takes its channel's style; a channel with no style needs one (style_edit action=create) before anything is generated. Share the returned web_url so the user can follow along.

  shallow
• projects_read

  Your channels, or the projects in one channel.

  shallow
• 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}.

  shallow
• remove_music_track

  Remove a music track from the project.

  shallow
• remove_segment_asset

  Delete a segment's sound effect or overlay (lower third, title card, callout) — the asset and every scene layer built from it, immediately. These are the only removable assets: the segment's image, video and voiceover are structural. With one SFX/overlay attached, no id needed.

  shallow
• 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).

  shallow
• render

  Render segment images and clips, the biggest spend in the video: always run it with dry_run=true first and get the user's yes on the estimate. generate: without segment_numbers, everything not yet rendered (items rendering are skipped); with them, those segments, finished renders included, e.g. the first minute before the whole video. Overrides need segment_numbers and what=images or what=clips. animate: turn one segment's rendered image into a clip; animate only images worth motion. dry_run quotes the default clip or talking head model. A refused render leaves the segment as it was; to go back to the image, segment_restructure change_type to=image keep_image=true. Check renders with storyboard_read action=segment_assets and view_image.

  shallow
• 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}.

  shallow
• 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.

  shallow
• rollback_segment_asset

  Restore a previously rendered version of a segment's image or video — every regeneration archives the render it replaces (last 5), so a regen that came out worse is reversible for free. The current render is archived in its place, making the rollback itself reversible. The frame/clip pair restales as usual: rolling the image back marks a rendered clip out of date.

  shallow
• 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.

  shallow
• 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}.

  shallow
• script_edit

  Change the script or its settings; only revise spends credits. save: replace the active version's text (the old text is lost: show the user the current script first), then run Analyze Script. Notation, never read aloud: `[SCENE: <visual direction>]` as its own paragraph directs the storyboard for the narration after it, until the next one, over the director style. `<break time="1.5s" />` is the only thing that makes the voice pause (about 0.5s between thoughts, 1.0s between sections; one tag with the total, never two in a row). A paragraph starting `Name: "..."` is that character's dialogue. A delivery cue in square brackets inside a line (`[laughs]`, `[sighs]`, `[whispers]`) shapes how it is said; keep it inline, never on its own line. MiniMax performs sounds such as laughs, sighs, breathes, gasps and coughs and drops other cues. activate_version: switch to another version (each generated script is one). revise: an AI rewrite of a passage or the whole script in the narrative voice; returns revised_text without saving it: splice it in and save.

  shallow
• script_generate

  generate: write the script from the brief and the narrative style; each run is a new version (review it with script_read). analyze (Analyze Script): find the script's characters, environments and objects (including any named only in `[SCENE: ...]` directions) and split it into voice blocks. Existing assets are kept as they are (description, reference image, voice) and new ones added; assets the script no longer names stay until the user deletes them. Review with assets_read.

  shallow
• script_read

  The active script, its versions, and the script settings (script_target_minutes, voice_mix, visual concept). Show the script to the user before Analyze Script.

  shallow
• segment_edit

  Change one segment without losing renders; only split spends credits. Returns the changed segments. set_prompts: write prompts verbatim, no AI rewrite. The renders stay as they are: render the segment again to apply the new prompts. set_continuation: make this segment's image continue an earlier one's (same composition, only the change); render the image again. rollback: restore one of the last 5 renders of the image or clip; the current one takes its place, so it can be undone, and the prompt editor's model stays as it is. split: cut into 2-4 parts; the inheriting part keeps the prompts and renders; the others start empty and get prompts written from their narration in the background (spends credits), or give them prompts with set_prompts. Later segments renumber: read the storyboard again before more edits.

  shallow
• segment_restructure

  Change what a segment is. Every call previews first: when no rendered image or clip would be lost it runs; otherwise it changes nothing and returns what would be lost. Show the user, then call again with confirm=true. combine: merge with a neighboring segment. The kept segment's renders stay, retimed to the combined length, but go stale: its prompts are rewritten for the combined narration, so render it again after. The other's are deleted (the preview names it). change_type: to an image, real photo, B-roll (both fetched) or overlay segment. Clips and talking heads come from render action=animate. keep_image turns a clip back into its image, keeping the render. A change between an image, real photo and B-roll keeps the prompts; render the image again. rewrite: an AI rewrite of the prompts from feedback; render the image and clip again after. For exact text, use segment_edit set_prompts. combine, rewrite and a change to or from an overlay segment write prompts in the background, and a change to a real photo or B-roll with no searches yet writes its searches (its prompts stay): a small AI step that spends credits (get_status wait=true). Until it finishes, change_type is refused (409). Sound effects and overlays always survive; change an overlay's text with editor_edit scene_note. Later segments may renumber: read the storyboard again.

  shallow
• 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.

  shallow
• 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.)

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• storyboard_edit

  Storyboard settings, used by the next storyboard run.

  shallow
• storyboard_generate

  Plan the storyboard: every segment, its timing, image and motion prompts, overlays and continuations, following the channel style and any `[SCENE: ...]` directions. Needs the finished voiceover (its timing drives the cuts). It plans images, plus real photos and B-roll when the director style has the `@real-media` tag; clips come later, by animating rendered images. Running it again replaces the whole plan, edits included. The longest step (several minutes): get_status wait=true, repeatedly.

  shallow
• storyboard_read

  segments: {total, offset, returned, segments}. Each segment has its segment_number (the handle segment tools take), kind (image, clip, talking head, real photo, B-roll or overlay segment), narration, duration, direction, image_prompt, video_prompt (the motion when animated), media_queries (searches for a real photo or B-roll), the characters, environments and objects it shows, continues_from_segment (its image continues that earlier segment's image) and its assets. segment_assets: {segment_number, assets}: its image, clip, real photos, overlays and sound effects, each with kind, status, prompt, model, earlier_renders (what a rollback can restore) and public_url (for view_image).

  shallow
• style_edit

  Create or change the channel style (one per channel, used by all its projects). create: offer the user two real options, never invented ones. (a) References (best): YouTube links of their channel or of videos whose look they like, or a written description. Analysis starts at once and writes the fields: wait with get_status channel_id wait=true, then render both template images (style_generate action=template). A reference informs every axis, narrative included; for its look only, give it contributes_to ["art_style"]. (b) Presets: one per axis, all three; instant, and the art preset brings its template images. Presets and references don't mix. update_fields: replace fields' text; it never starts an analysis (an analysis rewrites art_style, narrative_style, director_style and text_style). Those four and script_prompt can't be removed, every field needs text, and summaries are written only by analysis. Real photos and B-roll are turned on by the literal `@real-media` tag in director_style, with prose on when and how much; remove it to turn them off. update_references: replace the references, fields untouched (inputs_stale turns true). File references can only be added in the app.

  shallow
• style_generate

  analyze: read the references again and rewrite art_style, narrative_style, director_style and text_style, replacing hand edits. template: render one of the style's two template images. Reference images render on them (characters on the character template, environments and objects on the environment one) and segment images fall back on them, so finish both before any reference image. An existing one is refused unless replace=true: replacing it changes the look of everything rendered after.

  shallow
• style_read

  get: the channel style: its references, its fields (art_style, narrative_style, director_style, text_style, any added; script_prompt on request), the summary analysis wrote for each, and templates, the character and environment template images (null: not rendered; a URL: it exists, so view_image it rather than render it again). inputs_stale: the references changed since the last analysis (offer style_generate action=analyze). templates_stale: the art style changed since the templates were rendered (offer to render them again). presets: the preset catalog, one list per axis (art_style, narrative_style, director_style), with labels, descriptions and, for art presets, preview images. Let the user pick one per axis.

  shallow
• update_asset

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

  shallow
• 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.

  shallow
• 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.

  shallow
• update_project

  Patch project fields. Updatable: title, description, asset_mix, sfx_level, video_concept, voice_mix, voice_tts_provider, script_target_minutes, narrator_speed, video_format. (The narrator's TTS voice is NOT here — use set_narrator_voice.) video_format ('landscape' | 'portrait') is only changeable until the storyboard exists — after that the shots and overlays are composed for the current frame and the patch 409s. Switch it before generate_storyboard.

  shallow
• 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.

  shallow
• update_segment_prompts

  Set one segment's final prompts VERBATIM — no LLM rewrite. The direct counterpart to update_segment_content: your text is written as-is to the segment's creative direction and to the matching asset configs the renderer reads. Asset statuses are untouched: an already-rendered asset stays complete, and generate_segments skips complete assets — so to see the edit rendered, call regenerate_segment_asset on that segment (the ONLY re-render path after a prompt edit). Continuation links, SFX, and overlays are untouched. Pass only the prompt(s) you want to change; media_queries edits a fetched segment's stock-search text the same way.

  shallow
• 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.

  shallow
• update_style_references

  Replace a style's reference set — add or remove references without touching the analyzed fields. FULL REPLACE: read the current list with get_style first and send every entry you're keeping plus the changes. New entries are youtube (video link, or a channel link/@handle) or text; new image/video FILES can only be added via the multipart REST endpoint PATCH /styles/{id}, but existing ones round-trip fine. Optional `contributes_to` scopes an entry to a subset of the analyzed fields (art_style / narrative_style / director_style); omit it for all three. Saving does NOT re-run analysis: the response's `inputs_stale` flips true and the analyzed fields keep their current text until the user asks for analyze_style (which rewrites them from the new set).

  shallow
• 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.

  shallow
• 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.

  shallow
• voiceover_edit

  Voices and voice blocks; free. set_voice: the narrator's or a character's voice; every speaker needs one before the voiceover. rescan_blocks: split the active script into voice blocks again after an edit, assets untouched; blocks whose words are unchanged keep their audio. settings: the voice engine and narrator speed.

  shallow
• voiceover_generate

  Generate voice block audio. Every speaker needs a voice first, and every asset a reference image. Without voice_block_ids it fills every block with no audio, skipping ones already generating. A model must match the project's voice engine. An existing storyboard retimes to the new audio on its own.

  shallow
• voiceover_read

  voices: one engine's voice ids, labels and preview audio, as {groups, voices}. blocks: the voice blocks (narration and dialogue) with their speaker, voice_id (the speaker's voice), audio and any `[SCENE: ...]` direction over them (never spoken), as {blocks, total_duration_ms, all_complete}.

  shallow
• 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.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/af83a225-1226-495a-ae60-95f84f9e0bf6/badge.svg)](https://vouch.tools/servers/af83a225-1226-495a-ae60-95f84f9e0bf6)