com.framesail/framesail

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. Blocks whose spoken text is unchanged keep their audio; only edited blocks come back empty, so a follow-up generate_voiceover fills just the gaps. Synchronous and free — the split is deterministic. Returns {block_count}.

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. `[SCENE: ...]` directions in range are preserved exactly, in place, unless the instruction asks to change them. 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.

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.

Save script text (your own draft, or an edited version of the generated one). Saving UPDATES the active version in place — the previous text is not kept, so show the user the current script (get_script) before overwriting it. New versions are created by generate_script runs, and activate_script_version switches between those. Run scan_script afterwards so assets and voice blocks reflect the new text. Three notations the script text carries, none of them ever spoken: SCENE DIRECTIONS — `[SCENE: <visual direction>]` as its OWN paragraph (blank line before and after; brackets inside a narration paragraph are never matched). It directs the storyboard for the narration that follows, until the next direction, and for that span OUTRANKS the director style's shot choices — say what is on screen, who is in frame, and any on-screen text to bake in verbatim. It does not constrain how many segments the span is cut into. scan_script extracts characters/places named only inside a direction too, under the exact name used. PAUSES — `<break time="1.5s" />` is the ONLY thing that makes the voice pause; ellipses, dashes and paragraph breaks produce no silence. Use ~0.5s between thoughts, ~1.0s at act seams, longer where a card needs reading time; write ONE tag with the total ("4.0s"), never two back to back. narrator_speed changes how fast words are said; breaks add the silence between them. SPEAKERS — a paragraph starting `Name: "..."` assigns that line to a character, who gets their own voice (set_character_voice) and their own shot. Narration with no prefix is the narrator's.

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). Extraction reads the narration AND any `[SCENE: ...]` directions — a character or place named only inside a direction is still extracted, under the exact name the direction uses. Directions never leak into voice blocks (they ride onto the blocks they govern as staging instead). Review list_assets afterwards and create_asset anything the video needs that neither narration nor directions ever name. Async — returns {job_id}.

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

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.

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 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 — that part keeps its rendered assets, SFX, overlays and continuation links (a rendered clip goes stale; re-render it). The other parts start fresh. Later segments renumber — re-check get_segments before further edits.

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

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.

Tweak a music track. fields keys: name, volume (0-1), loop, start_frame, duration_frames, position, trim_start_frame, trim_end_frame.

Patch project fields. Updatable: title, description, 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.) narrator_speed is the narration rate (0.5-2.0, default 1.0; clamped to 0.7-1.2 on ElevenLabs). It changes how fast words are SAID and nothing else — it adds no silence between them, so "slow this down" usually wants `<break>` tags in the script text too (see save_script). 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.

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). When you already know the exact prompt text, use update_segment_prompts instead — it writes your words verbatim with no LLM in the loop.

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.

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 a PATCH, merged over what the style already has: send only the keys you are changing and leave the rest out — there is no need to read the whole dict back with get_style and round-trip it. Pass {key: null} to delete a user-added key (the well-known art_style / narrative_style / director_style / script_prompt cannot be deleted, only rewritten, and cannot be set empty). Editing fields does NOT trigger re-analysis, so your edits stick. Real media is switched by the literal `@real-media` tag inside director_style's prose: add the tag plus prose describing when/how/how much real media appears to turn it on; remove the tag (or its passage) to turn it off.

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

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.

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.

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.