Framesail AI

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

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.

List projects in a channel.

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…

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

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…

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

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 b…

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 n…

THE resume/orientation tool: one call returns every pipeline step's state (script -> scan -> reference_images -> voices -> voiceover -> style_templates -> storyboard -> segment_assets -> scene…

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 …

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 …

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, ...). Sectio…

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/orien…

Generate the project's script from its description/concept and the channel's narrative style. Async — returns {job_id}; poll get_workflow_status.

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 -> s…

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 (g…

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 wh…

Switch the project's active script to another saved version (ids come from get_script's version list — each generate_script run creates one; save_script edits the active version in place). Re-…

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, …

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 nes…

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

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

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

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 objec…

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…

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…

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…

List the project's voice blocks (per-speaker narration chunks) with their audio status and assigned voices. A block's `scene_direction` is the script's `[SCENE: ...]` direction governing it (n…

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 rege…

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 …

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-ge…

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 (timin…

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/regene…

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…

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 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 cu…

Change what a segment's base visual IS: a generated still ("image"), fetched real media (media_source="real" — a real photo for "image", stock b-roll footage for "video"), or an overlay scene.…

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 thi…

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 …

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 …

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, over…

Merge a segment with an adjacent one (segment numbers must be neighbors). keep: "this" | "other" — whose creative data survives: its assets are kept (rendered frame/clip marked stale against t…

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 …

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.

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

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 use…

Compile segments + assets + voiceover into the editor/render timeline (scenes). Run after segment assets are complete, before export. Returns a receipt — {scene_count, scenes: [{scene_id, segm…

List the project's scenes in timeline order. Default rows are light summaries ({scene_id, segment_number, duration_frames, status, layer_count}) — enough to address a scene by number or id; …

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 +…

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 eac…

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.

Download URL for the most recent completed export.

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 @variable…

Fetch one style row — its inputs (reference material), analyzed fields (art_style, narrative_style, director_style, script_prompt, ...), and `templates`: {"character": url|null, "environment":…

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 alread…

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 keepi…

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 …

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 …

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

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…

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.

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,…

List registered BYOK providers (masked — only the last 4 characters). Returns {keys: [...]}; an empty list means no keys are registered (every job bills platform credits).

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.

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 pro…

Browse the audio library for background music and sound effects. category: "music" | "sfx". Returns {tracks} — track ids feed add_music_track / add_segment_sfx. Zero matches also returns the m…

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

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…

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

Remove a music track from the project.

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 …