MCP Server
framesail
com.framesail/framesail
What this MCP does
Creates long-form YouTube videos through script generation, storyboarding, visual assets, voiceover, music, scene composition, and MP4 export.
Capabilities
Tools
72
tools
activate_script_version
Activate script version
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-run scan_script /
rescan_voice_blocks afterwards if the text differs, since downstream
artifacts follow the active version.
Idempotent
Input schema
{'type': 'object', 'title': 'activate_script_versionArguments', 'required': ['script_id'], 'properties': {'script_id': {'type': 'string', 'title': 'Script Id', 'description': "ID of the script version to activate, from get_script's version list"}}}
add_music_track
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.
Input schema
{'type': 'object', 'title': 'add_music_trackArguments', 'required': ['project_id', 'library_track_id'], 'properties': {'loop': {'type': 'boolean', 'title': 'Loop', 'default': True, 'description': 'True loops the track under the whole video; false plays it once'}, 'name': {'type': 'string', 'title': 'Name', 'default': 'Music', 'description': "Display name for the track on the project's timeline"}, 'volume': {'type': 'number', 'title': 'Volume', 'default': 0.12, 'description': "Playback volume 0-1; the 0.12 default sits at bed level under narration â\x80\x94 don't raise it unless asked"}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'start_frame': {'type': 'integer', 'title': 'Start Frame', 'default': 0, 'description': 'Timeline frame at which the track starts (0 = start of the video)'}, 'library_track_id': {'type': 'string', 'title': 'Library Track Id', 'description': 'Audio library track ID, from browse_audio_library(category="music")'}}}
add_segment_sfx
Add segment sound effect
Attach a sound effect from the audio library to a segment (find track
ids via browse_audio_library with category="sfx"). It lands on the
segment's scene immediately â no build_scenes needed.
Input schema
{'type': 'object', 'title': 'add_segment_sfxArguments', 'required': ['project_id', 'segment_number', 'library_track_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}, 'library_track_id': {'type': 'string', 'title': 'Library Track Id', 'description': 'Audio library track ID, from browse_audio_library(category="sfx")'}}}
analyze_style
Re-analyze style
Re-run style analysis (after changing a style's inputs). Async â
await_jobs(style_id=...) until the style_analysis job completes.
Destructive
Input schema
{'type': 'object', 'title': 'analyze_styleArguments', 'required': ['style_id'], 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'ID of the style to re-analyze, from create_style or list_styles'}}}
animate_segment
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.
Input schema
{'type': 'object', 'title': 'animate_segmentArguments', 'required': ['project_id', 'segment_number'], 'properties': {'voice': {'type': 'boolean', 'title': 'Voice', 'default': False, 'description': 'True lip-syncs the on-frame speaker to the voiceover (lip-sync model family â\x80\x94 bills the exact segment length, so long segments cost proportionally more); False is an ordinary prompt-driven clip. Always explicit, never inferred.'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
await_jobs
Wait for 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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'await_jobsArguments', 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'default': '', 'description': 'Style ID whose analysis/template jobs to wait for; pass exactly one of project_id or style_id'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'default': '', 'description': 'Project ID whose jobs to wait for; pass exactly one of project_id or style_id'}, 'timeout_seconds': {'type': 'integer', 'title': 'Timeout Seconds', 'default': 50, 'description': "Max seconds to block server-side before returning done=false; keep <= 50 so the client doesn't time out the tool call"}}}
browse_audio_library
Browse audio library
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 mood and
genre tags the library actually carries, so retry with one of those
rather than guessing new filter words.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'browse_audio_libraryArguments', 'properties': {'mood': {'type': 'string', 'title': 'Mood', 'default': '', 'description': "Filter by the track's mood tag; empty for no filter"}, 'genre': {'type': 'string', 'title': 'Genre', 'default': '', 'description': "Filter by the track's genre tag; empty for no filter"}, 'search': {'type': 'string', 'title': 'Search', 'default': '', 'description': 'Free-text search over track names/descriptions; empty for no filter'}, 'category': {'type': 'string', 'title': 'Category', 'default': '', 'description': 'Track kind: "music" (background tracks) or "sfx" (sound effects); empty returns both'}}}
build_scenes
Build scenes
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, segment_number,
duration_frames, status, layer_count}]}; composition detail via
list_scenes.
Destructive
Input schema
{'type': 'object', 'title': 'build_scenesArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
change_segment_type
Change segment type
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. Generated video is NOT
set here â it's the state a rendered still reaches through animate_segment
(voice=true for a Talking Head), and a "video" target without
media_source="real" is refused with that guidance. segment_type "image"
with carry_frame=true reverts an animated shot back to its still for free.
media_source="real" turns the shot into fetched media with no start frame
and no generation. carry_frame=true reuses the already-rendered image
instead of recreating it; ignored for a real target. SFX and overlays
always survive a type change. dry_run=true previews what would be kept /
staled / recreated / deleted before you commit.
Destructive
Input schema
{'type': 'object', 'title': 'change_segment_typeArguments', 'required': ['project_id', 'segment_number', 'segment_type'], 'properties': {'dry_run': {'type': 'boolean', 'title': 'Dry Run', 'default': False, 'description': 'True previews the consequences (assets kept / staled / recreated / deleted, rendered assets lost) without changing anything'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'carry_frame': {'type': 'boolean', 'title': 'Carry Frame', 'default': False, 'description': "True reuses the already-rendered frame as the new type's starting visual instead of recreating it from scratch"}, 'media_source': {'type': 'string', 'title': 'Media Source', 'default': '', 'description': '"" keeps the segment\'s current source; "real" makes the visual fetched stock footage / a real photo (b-roll) instead of a generated one; "generated" switches back'}, 'segment_type': {'type': 'string', 'title': 'Segment Type', 'description': 'New visual type: "image", "video" (fetched b-roll only â\x80\x94 requires media_source "real"), or "overlay_scene"'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
combine_segments
Combine segments
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 the combined
narration and its prompts re-derived); the other segment's assets are
deleted. Later segments renumber â re-check get_segments before further
edits.
Destructive
Input schema
{'type': 'object', 'title': 'combine_segmentsArguments', 'required': ['project_id', 'segment_number', 'with_segment_number'], 'properties': {'keep': {'type': 'string', 'title': 'Keep', 'default': 'this', 'description': 'Whose creative data survives the merge: "this" (segment_number) or "other" (with_segment_number)'}, 'dry_run': {'type': 'boolean', 'title': 'Dry Run', 'default': False, 'description': 'True previews the consequences without changing anything'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}, 'with_segment_number': {'type': 'integer', 'title': 'With Segment Number', 'description': '1-based number of the adjacent segment to merge with (must neighbor segment_number)'}}}
create_asset
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.
The scan reads narration and `[SCENE: ...]` directions, so the common
miss is anyone NEITHER ever names â a host the video needs but no text
mentions, a recurring set the script only implies. Name the asset exactly
as the script or directions will refer to it so the storyboard binds the
two, then generate_asset_reference it like any scanned asset.
Input schema
{'type': 'object', 'title': 'create_assetArguments', 'required': ['project_id', 'asset_type', 'name'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'description': "Asset name as the script refers to it (e.g. the character's name)"}, 'asset_type': {'type': 'string', 'title': 'Asset Type', 'description': 'Kind of asset: "character", "environment", or "object"'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'description': {'type': 'string', 'title': 'Description', 'default': '', 'description': "Generation-facing spec of the asset's look; every shot renders from it, so be specific"}}}
create_channel
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.
Input schema
{'type': 'object', 'title': 'create_channelArguments', 'required': ['name'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'description': 'Display name for the new channel'}, 'description': {'type': 'string', 'title': 'Description', 'default': '', 'description': "Optional free-text description of the channel's content focus"}}}
create_project
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.
Input schema
{'type': 'object', 'title': 'create_projectArguments', 'required': ['channel_id', 'title'], 'properties': {'title': {'type': 'string', 'title': 'Title', 'description': 'Project title shown in the app'}, 'channel_id': {'type': 'string', 'title': 'Channel Id', 'description': 'ID of the channel to create the project in, from list_channels or create_channel'}, 'description': {'type': 'string', 'title': 'Description', 'default': '', 'description': 'The video concept/topic; seeds script generation, so make it specific and meaningful'}, 'video_format': {'enum': ['landscape', 'portrait'], 'type': 'string', 'title': 'Video Format', 'default': 'landscape', 'description': "Output frame shape: 'landscape' (16:9, the default â\x80\x94 YouTube and long-form) or 'portrait' (9:16 â\x80\x94 Shorts, Reels, TikTok). Fixed once the storyboard is generated, so pick it up front."}}}
create_style
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.
Input schema
{'type': 'object', 'title': 'create_styleArguments', 'required': ['channel_id', 'name'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'description': 'Display name for the style'}, 'inputs': {'anyOf': [{'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}}, {'type': 'null'}], 'title': 'Inputs', 'default': None, 'description': 'Reference material to analyze, [{"input_type": "youtube" | "text", "value": "<url or description>"}]; a youtube value can be a video link or a channel link/@handle (resolved to that channel\'s newest usable upload). Triggers an async analysis job. Mutually exclusive with presets'}, 'presets': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Presets', 'default': None, 'description': 'Preset IDs per axis, {"art_style": id, "narrative_style": id, "director_style": id}, from list_style_presets; instant, no analysis. Mutually exclusive with inputs'}, 'channel_id': {'type': 'string', 'title': 'Channel Id', 'description': 'ID of the channel to create the style in, from list_channels'}}}
delete_asset
Delete asset
Delete a project asset (e.g. one the scan over-extracted).
Destructive
Input schema
{'type': 'object', 'title': 'delete_assetArguments', 'required': ['asset_id'], 'properties': {'asset_id': {'type': 'string', 'title': 'Asset Id', 'description': 'ID of the asset to delete, from list_assets'}}}
delete_project
Delete project
Permanently delete a project and everything in it (script versions,
assets, voiceover, segments, renders). Irreversible â confirm with your
user first.
Destructive
Input schema
{'type': 'object', 'title': 'delete_projectArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'ID of the project to permanently delete, from list_projects'}}}
delete_style
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.
Destructive
Input schema
{'type': 'object', 'title': 'delete_styleArguments', 'required': ['style_id'], 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'ID of the style to delete, from list_styles'}}}
director_note
Director note (one scene)
Edit ONE scene with a natural-language note (the same director chat the
editor UI uses): move/restyle/add/remove layers and overlays, change
motion, etc. Storyboard image, video and voiceover layers can't be removed.
Synchronous â returns summary, mutations, skipped_mutations (edits that
did NOT land, with reasons â check it) and the scene's layers ({id, name,
layerType, segmentAssetId}); list_scenes(include_composition=True) has the
full composition. Address the scene by
project_id + segment_number (preferred) or a scene_id from a fresh
list_scenes call. Scene durations are locked to the narration: don't ask
to extend/shorten any but the final scene. remove_segment_asset deletes
an SFX or overlay by id without a model in the loop; for whole-video
notes, project_director_note.
Input schema
{'type': 'object', 'title': 'director_noteArguments', 'required': ['message'], 'properties': {'message': {'type': 'string', 'title': 'Message', 'description': 'Natural-language edit note for this scene, e.g. "move the caption to the top" or "calmer motion"'}, 'scene_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Scene Id', 'default': None, 'description': 'ID of the scene to edit, from a FRESH list_scenes call â\x80\x94 scene ids change whenever segments are edited (split/combine/update-content), so never reuse ids saved earlier; prefer project_id + segment_number'}, 'project_id': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Project Id', 'default': None, 'description': 'Project ID; required (with segment_number) when not passing scene_id'}, 'segment_number': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'title': 'Segment Number', 'default': None, 'description': '1-based segment number of the scene to edit (from list_scenes or get_segments) â\x80\x94 preferred over scene_id because it is resolved to the current scene at call time'}, 'conversation_history': {'anyOf': [{'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}}, {'type': 'null'}], 'title': 'Conversation History', 'default': None, 'description': 'Prior chat turns as [{"role": ..., "content": ...}] to continue an editing conversation on this scene; omit to start fresh'}}}
export_video
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.
Input schema
{'type': 'object', 'title': 'export_videoArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
generate_asset_reference
Generate asset reference image
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.
Input schema
{'type': 'object', 'title': 'generate_asset_referenceArguments', 'required': ['asset_id'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': "Image model ID; empty uses the asset's saved drawer choice, else the account default, else the server default"}, 'asset_id': {'type': 'string', 'title': 'Asset Id', 'description': 'ID of the asset to render a reference image for, from list_assets'}, 'settings': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Settings', 'default': None, 'description': "Model-specific settings (e.g. image quality/orientation); valid keys come from the model's settings_schema in list_models"}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template for the reference-image job'}}}
generate_script
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.
Input schema
{'type': 'object', 'title': 'generate_scriptArguments', 'required': ['project_id'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': 'Model ID to generate with; empty uses the default (see list_models("script"))'}, 'settings': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Settings', 'default': None, 'description': 'Model-specific settings; valid keys come from the model\'s settings_schema in list_models("script")'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template("script") for the sections this job exposes'}}}
generate_segments
Render 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 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. The
staged flow is cheapest: asset_scope="no_clips" first (images + overlays),
review, then animate_segment the shots that deserve motion. 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.
Idempotent
Input schema
{'type': 'object', 'title': 'generate_segmentsArguments', 'required': ['project_id'], 'properties': {'dry_run': {'type': 'boolean', 'title': 'Dry Run', 'default': False, 'description': 'True returns the credit-cost estimate without rendering anything; ALWAYS run true first and get user approval before the real run'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'asset_scope': {'type': 'string', 'title': 'Asset Scope', 'default': '', 'description': '"" renders everything actionable; "no_clips" is the cheap base pass (images, overlays, fetched b-roll â\x80\x94 no generated video clips); "clips_only" renders just the generated clips'}, 'segment_numbers': {'anyOf': [{'type': 'array', 'items': {'type': 'integer'}}, {'type': 'null'}], 'title': 'Segment Numbers', 'default': None, 'description': '1-based segment numbers (from get_segments) to render only a subset; omit to render every actionable asset in the project'}}}
generate_storyboard
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).
Plans generated stills + real media only (real media requires the style's
@real-media tag); generated video is added per segment after the images
render, with animate_segment.
Async â returns {job_id}; this is the longest LLM step.
Destructive
Input schema
{'type': 'object', 'title': 'generate_storyboardArguments', 'required': ['project_id'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': 'Model ID to plan with; empty uses the default (see list_models("storyboard"))'}, 'settings': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Settings', 'default': None, 'description': 'Model-specific settings; valid keys come from the model\'s settings_schema in list_models("storyboard")'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template("storyboard")'}}}
generate_style_template
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.
Input schema
{'type': 'object', 'title': 'generate_style_templateArguments', 'required': ['style_id', 'template_type'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': "Image model ID; empty uses the template job's default (see list_models)"}, 'replace': {'type': 'boolean', 'title': 'Replace', 'default': False, 'description': 'Set True ONLY to deliberately overwrite an existing template of this type â\x80\x94 the user must have asked for a new one. Leave False and the call refuses rather than clobbering a template the style already has'}, 'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'Style ID, as returned by create_style or list_styles'}, 'template_type': {'type': 'string', 'title': 'Template Type', 'description': 'Which of the style\'s two template images to render: "character" or "environment" â\x80\x94 run once for each'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template for the template job'}}}
generate_voiceover
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")).
On a project that already has a storyboard, segment timings are
re-aligned to the new audio automatically when the run finishes (prompts
and rendered images untouched) â await_jobs until the project is idle
before exporting. Async â returns one job per block.
Input schema
{'type': 'object', 'title': 'generate_voiceoverArguments', 'required': ['project_id'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': 'TTS model ID; empty uses the default for the project\'s TTS provider. If set, it must belong to that provider â\x80\x94 see list_models("voice_block") for each model\'s provider'}, 'settings': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Settings', 'default': None, 'description': 'Model-specific TTS settings applied to every selected block; valid keys come from the model\'s settings_schema in list_models("voice_block")'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'voice_block_ids': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'title': 'Voice Block Ids', 'default': None, 'description': 'Block IDs (from list_voice_blocks) to explicitly REgenerate; omit to fill gaps â\x80\x94 only blocks with no audio yet run'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides applied to every selected block; see get_section_template("voice_block")'}}}
get_credit_balance
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_credit_balanceArguments', 'properties': {}}
get_pipeline_progress
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_pipeline_progressArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
get_project
Get project
Fetch a project row â settings, voice config, default style, export URL.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_projectArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
get_script
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_scriptArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
get_section_template
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_section_templateArguments', 'required': ['job'], 'properties': {'job': {'type': 'string', 'title': 'Job', 'description': 'Generation job name, e.g. "script", "script_scan", "storyboard", "segment_image", "segment_video", "voice_block"'}}}
get_segment_assets
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_segment_assetsArguments', 'required': ['project_id', 'segment_number'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
get_segments
List 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.
Returns {total, offset, returned, segments}; on big projects page through
with offset/limit rather than fetching all segments in one call.
Each segment reports `continues_from_segment`: when set, this shot
CONTINUES that earlier segment's frame (same composition, only the delta
changes); null is a fresh shot. Adjust with set_segment_continuation.
Each segment's segment_assets also lists its overlays (asset_type
ui_element, text under config.overlay) â the one call that audits every
lower third / title card in the project.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_segmentsArguments', 'required': ['project_id'], 'properties': {'limit': {'type': 'integer', 'title': 'Limit', 'default': 0, 'description': 'Maximum segments to return; 0 returns all. Long-form projects can hold 100+ segments â\x80\x94 page with offset/limit instead of pulling everything at once.'}, 'offset': {'type': 'integer', 'title': 'Offset', 'default': 0, 'description': '0-based index of the first segment to return (pagination)'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
get_style
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. `inputs_stale: true` means the references changed
since the last analysis run â the analyzed fields don't reflect them;
offer the user analyze_style (it rewrites those fields).
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_styleArguments', 'required': ['style_id'], 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'Style ID, as returned by create_style or list_styles'}}}
get_video_url
Get video download URL
Download URL for the most recent completed export.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_video_urlArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
get_workflow_status
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'get_workflow_statusArguments', 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'default': '', 'description': 'Style ID to scope jobs to (style analysis); pass exactly one of project_id or style_id'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'default': '', 'description': 'Project ID to scope jobs to; pass exactly one of project_id or style_id'}}}
list_assets
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".
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_assetsArguments', 'required': ['project_id'], 'properties': {'asset_type': {'type': 'string', 'title': 'Asset Type', 'default': '', 'description': 'Optional filter: "character", "environment", or "object"; empty lists all asset types'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
list_channels
List channels
List your channels. Every project lives in a channel, which owns the
reusable styles (art/narrative/director) that drive generation.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_channelsArguments', 'properties': {}}
list_models
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).
When model is omitted the server picks: the scope's saved expert-drawer
choice if one exists, else the account's default for the job (set on the
account page), else the first entry here. The list is personalized â the
account default is listed first with its saved settings as the schema
defaults. Jobs whose models split into families (voice_block by provider,
segment_video by lip_sync) are personalized only when you name the family,
since the account default is stored per family.
Voice models carry a `provider` field â a voice_block model must match the
project's voice_tts_provider or generate_voiceover rejects it.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_modelsArguments', 'required': ['job'], 'properties': {'job': {'type': 'string', 'title': 'Job', 'description': 'Generation job whose allowed models to list, e.g. "script", "storyboard", "segment_image", "segment_video", "voice_block"'}, 'lip_sync': {'anyOf': [{'type': 'boolean'}, {'type': 'null'}], 'title': 'Lip Sync', 'default': None, 'description': "segment_video only: whether the shot is lip-synced to the narration (the asset's config.lip_sync). Video models split on it, so pass it to get that family's list and the account default for it."}, 'provider': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Provider', 'default': None, 'description': 'voice_block only: the project\'s voice_tts_provider ("minimax" or "elevenlabs"). Voice models split by provider, so pass it to get that family\'s list and the account default for it.'}}}
list_music_tracks
List music tracks
List the project's background music tracks (volume, loop, timing).
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_music_tracksArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
list_projects
List projects
List projects in a channel.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_projectsArguments', 'required': ['channel_id'], 'properties': {'channel_id': {'type': 'string', 'title': 'Channel Id', 'description': 'ID of the channel whose projects to list, from list_channels or create_channel'}}}
list_provider_keys
List provider keys
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).
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_provider_keysArguments', 'properties': {}}
list_scenes
List scenes
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;
include_composition=True returns the full layer/layout JSON (bulky â
page with offset/limit on long projects). Returns {total, offset,
returned, scenes}.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_scenesArguments', 'required': ['project_id'], 'properties': {'limit': {'type': 'integer', 'title': 'Limit', 'default': 0, 'description': 'Maximum scenes to return; 0 returns all'}, 'offset': {'type': 'integer', 'title': 'Offset', 'default': 0, 'description': '0-based index of the first scene to return (pagination)'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'include_composition': {'type': 'boolean', 'title': 'Include Composition', 'default': False, 'description': "Include each scene's full composition JSON (layers, layout) â\x80\x94 kilobytes per scene, so page with offset/limit when True; the default summary rows are enough for ids and director notes"}}}
list_style_presets
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).
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_style_presetsArguments', 'properties': {}}
list_styles
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_stylesArguments', 'required': ['channel_id'], 'properties': {'channel_id': {'type': 'string', 'title': 'Channel Id', 'description': 'ID of the channel that owns the styles, from list_channels'}}}
list_voice_blocks
List voice blocks
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 (never spoken; null when
the span carries none). Word-level subtitle timings are stripped unless
include_subtitle_data=True.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_voice_blocksArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'include_subtitle_data': {'type': 'boolean', 'title': 'Include Subtitle Data', 'default': False, 'description': 'Include each block\'s word-level subtitle timings â\x80\x94 bulky and rarely needed; omitted by default (subtitle_data reports "omitted" when present but stripped)'}}}
list_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.
Returns {groups: {name: count}, voices}; the ElevenLabs catalogue is
150+ voices, so pass group (names from `groups`) rather than reading it
all at once.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'list_voicesArguments', 'properties': {'group': {'type': 'string', 'title': 'Group', 'default': '', 'description': 'Return only this catalogue group (case-insensitive; e.g. "Narration", "Characters"). Empty returns every group â\x80\x94 the ElevenLabs catalogue is 150+ voices, so filter it by group; the response\'s `groups` lists the valid names with counts.'}, 'provider': {'type': 'string', 'title': 'Provider', 'default': 'minimax', 'description': 'TTS engine to list voices for: "minimax" (default engine) or "elevenlabs"; match the project\'s voice_tts_provider'}}}
project_director_note
Director note (whole project)
Apply a project-WIDE director note ("make the intro punchier", "all
captions bigger"). A routing pass picks the scenes the note applies to
and edits each â at most 10 scenes per call, so a change touching more
needs repeat calls or per-scene director_note. Synchronous â a few
seconds per scene. Returns per-scene results (summary, mutation_count).
Input schema
{'type': 'object', 'title': 'project_director_noteArguments', 'required': ['project_id', 'message'], 'properties': {'message': {'type': 'string', 'title': 'Message', 'description': 'Project-wide director note in natural language, e.g. "make the intro punchier" or "all captions bigger"'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
regenerate_segment_asset
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}.
Input schema
{'type': 'object', 'title': 'regenerate_segment_assetArguments', 'required': ['project_id', 'segment_number', 'asset_type'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': 'Model ID to render with; empty uses the job\'s default (see list_models("segment_image") / list_models("segment_video"))'}, 'settings': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Settings', 'default': None, 'description': "Model-specific settings (e.g. image quality, video duration); valid keys come from the model's settings_schema in list_models"}, 'asset_type': {'type': 'string', 'title': 'Asset Type', 'description': '"image" or "video"; for a video segment, "image" targets its start frame'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template("segment_image") or ("segment_video")'}}}
remove_music_track
Remove music track
Remove a music track from the project.
Destructive
Input schema
{'type': 'object', 'title': 'remove_music_trackArguments', 'required': ['track_id'], 'properties': {'track_id': {'type': 'string', 'title': 'Track Id', 'description': 'ID of the music track to remove, from list_music_tracks'}}}
remove_segment_asset
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.
Destructive
Input schema
{'type': 'object', 'title': 'remove_segment_assetArguments', 'required': ['project_id', 'segment_number'], 'properties': {'asset_id': {'type': 'string', 'title': 'Asset Id', 'default': '', 'description': 'ID of the SFX or overlay asset, from get_segment_assets; needed only when the segment has more than one of them'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
rescan_voice_blocks
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. 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}.
Destructive
Input schema
{'type': 'object', 'title': 'rescan_voice_blocksArguments', 'required': ['project_id'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
revise_script
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. `[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.
Input schema
{'type': 'object', 'title': 'revise_scriptArguments', 'required': ['project_id', 'instruction'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'instruction': {'type': 'string', 'title': 'Instruction', 'description': 'Natural-language edit instruction, e.g. "make the intro punchier"'}, 'selected_text': {'type': 'string', 'title': 'Selected Text', 'default': '', 'description': 'Exact passage to rewrite; must appear verbatim in the active script. Omit to revise the whole script'}}}
rollback_segment_asset
Restore previous render
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.
Input schema
{'type': 'object', 'title': 'rollback_segment_assetArguments', 'required': ['project_id', 'segment_number', 'asset_type'], 'properties': {'index': {'type': 'integer', 'title': 'Index', 'default': 0, 'description': "Which archived render to restore, 0 = the most recent (each asset's config.history in get_segment_assets lists them)"}, 'asset_type': {'type': 'string', 'title': 'Asset Type', 'description': '"image" or "video" â\x80\x94 which primary to restore; for a video segment, "image" targets its start frame'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
save_script
Save script
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.
Input schema
{'type': 'object', 'title': 'save_scriptArguments', 'required': ['project_id', 'content'], 'properties': {'content': {'type': 'string', 'title': 'Content', 'description': 'Full script text to save as a new version; plain prose narration, optionally with `[SCENE: ...]` direction paragraphs, `<break time="0.5s" />` pauses, and `Name:` speaker prefixes'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
scan_script
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).
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}.
Destructive
Input schema
{'type': 'object', 'title': 'scan_scriptArguments', 'required': ['project_id'], 'properties': {'model': {'type': 'string', 'title': 'Model', 'default': '', 'description': 'Model ID to scan with; empty uses the default (see list_models("script_scan"))'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'editable_sections': {'anyOf': [{'type': 'object', 'additionalProperties': True}, {'type': 'null'}], 'title': 'Editable Sections', 'default': None, 'description': 'Per-call prompt section overrides, keyed by section name; see get_section_template("script_scan")'}}}
set_character_voice
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.
Idempotent
Input schema
{'type': 'object', 'title': 'set_character_voiceArguments', 'required': ['asset_id', 'voice_id'], 'properties': {'asset_id': {'type': 'string', 'title': 'Asset Id', 'description': 'Character asset ID, from list_assets'}, 'voice_id': {'type': 'string', 'title': 'Voice Id', 'description': "TTS voice ID, from list_voices (use the provider matching the project's voice_tts_provider)"}}}
set_narrator_voice
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.)
Idempotent
Input schema
{'type': 'object', 'title': 'set_narrator_voiceArguments', 'required': ['project_id', 'voice_id'], 'properties': {'voice_id': {'type': 'string', 'title': 'Voice Id', 'description': "TTS voice ID for the narrator, from list_voices (use the provider matching the project's voice_tts_provider)"}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
set_project_style
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.
Idempotent
Input schema
{'type': 'object', 'title': 'set_project_styleArguments', 'required': ['project_id', 'style_id'], 'properties': {'style_id': {'type': 'string', 'title': 'Style Id', 'description': "ID of the style to make the project's default, from create_style or list_styles"}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
set_provider_key
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.
Idempotent
Input schema
{'type': 'object', 'title': 'set_provider_keyArguments', 'required': ['provider', 'key'], 'properties': {'key': {'type': 'string', 'title': 'Key', 'description': 'The provider API key to register; stored encrypted at rest'}, 'provider': {'type': 'string', 'title': 'Provider', 'description': 'Provider the key belongs to: "openai", "gemini", "anthropic", "fal", "elevenlabs", or "minimax"'}}}
set_segment_continuation
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.
Idempotent
Input schema
{'type': 'object', 'title': 'set_segment_continuationArguments', 'required': ['project_id', 'segment_number'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'continues_from': {'type': 'integer', 'title': 'Continues From', 'default': 0, 'description': '1-based number of the EARLIER segment whose frame this one continues; pass 0 to clear the link'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based number of the segment whose image should continue an earlier frame, as reported by get_segments'}}}
split_segment
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 â
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.
Destructive
Input schema
{'type': 'object', 'title': 'split_segmentArguments', 'required': ['project_id', 'segment_number', 'offsets_ms'], 'properties': {'dry_run': {'type': 'boolean', 'title': 'Dry Run', 'default': False, 'description': 'True previews the consequences without changing anything'}, 'offsets_ms': {'type': 'array', 'items': {'type': 'integer'}, 'title': 'Offsets Ms', 'description': 'Cut points as millisecond offsets from the segment start, ascending; 1-3 cuts producing 2-4 parts'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'inherit_index': {'type': 'integer', 'title': 'Inherit Index', 'default': 0, 'description': '0-based index of the resulting part that keeps the original creative data (default: the first part)'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based number of the segment to split, as reported by get_segments'}}}
update_asset
Update asset
Rename an asset and/or rewrite its description. If the look changed,
regenerate its reference image afterwards so renders match.
Input schema
{'type': 'object', 'title': 'update_assetArguments', 'required': ['asset_id'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'default': '', 'description': 'New asset name; empty leaves the name unchanged'}, 'asset_id': {'type': 'string', 'title': 'Asset Id', 'description': 'Asset ID, as returned by list_assets or create_asset'}, 'description': {'type': 'string', 'title': 'Description', 'default': '', 'description': 'New generation-facing look description; empty leaves it unchanged'}}}
update_caption_config
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.
Idempotent
Input schema
{'type': 'object', 'title': 'update_caption_configArguments', 'required': ['project_id', 'caption_config'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'caption_config': {'type': 'object', 'title': 'Caption Config', 'description': "Partial caption config to merge (keys like enabled, plus styling); read the current value from get_project's caption_config", 'additionalProperties': True}}}
update_music_track
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.
Input schema
{'type': 'object', 'title': 'update_music_trackArguments', 'required': ['track_id', 'fields'], 'properties': {'fields': {'type': 'object', 'title': 'Fields', 'description': 'Partial dict of track fields to patch; allowed keys: name, volume (0-1), loop, start_frame, duration_frames, position, trim_start_frame, trim_end_frame', 'additionalProperties': True}, 'track_id': {'type': 'string', 'title': 'Track Id', 'description': 'Music track ID, from list_music_tracks or add_music_track'}}}
update_project
Update project
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.
Input schema
{'type': 'object', 'title': 'update_projectArguments', 'required': ['project_id', 'fields'], 'properties': {'fields': {'type': 'object', 'title': 'Fields', 'description': "Partial dict of fields to patch; allowed keys: title, description, sfx_level ('none'|'minimal'|'frequent'), video_concept, voice_mix ('narrator_only'|'narrator_led'|'balanced'|'character_led'), voice_tts_provider ('minimax'|'elevenlabs'), script_target_minutes, narrator_speed, video_format", 'additionalProperties': True}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}}}
update_segment_content
Rewrite 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). When you already know the exact prompt text,
use update_segment_prompts instead â it writes your words verbatim with no
LLM in the loop.
Destructive
Input schema
{'type': 'object', 'title': 'update_segment_contentArguments', 'required': ['project_id', 'segment_number', 'user_input'], 'properties': {'dry_run': {'type': 'boolean', 'title': 'Dry Run', 'default': False, 'description': 'True previews the consequences (assets recreated, rendered assets lost) without changing anything'}, 'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'user_input': {'type': 'string', 'title': 'User Input', 'description': 'Natural-language feedback describing the change to this shot, e.g. "make this a close-up" or "show the machine from above"'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}}}
update_segment_prompts
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.
Idempotent
Input schema
{'type': 'object', 'title': 'update_segment_promptsArguments', 'required': ['project_id', 'segment_number'], 'properties': {'project_id': {'type': 'string', 'title': 'Project Id', 'description': 'Project ID, as returned by create_project or list_projects'}, 'image_prompt': {'type': 'string', 'title': 'Image Prompt', 'default': '', 'description': 'New scene-image prompt (image segments; also the retrieval-miss fallback on real-photo segments). Empty leaves it unchanged.'}, 'video_prompt': {'type': 'string', 'title': 'Video Prompt', 'default': '', 'description': 'New motion/video prompt (video segments; also the retrieval-miss fallback on real b-roll). Empty leaves it unchanged.'}, 'media_queries': {'anyOf': [{'type': 'array', 'items': {'type': 'string'}}, {'type': 'null'}], 'title': 'Media Queries', 'default': None, 'description': 'New stock-search queries for a fetched-media segment (real b-roll / real photo). Replaces the search text verbatim; re-fetch an already-fetched clip with regenerate_segment_asset. Omit to leave the search unchanged.'}, 'segment_number': {'type': 'integer', 'title': 'Segment Number', 'description': '1-based segment number, as reported by get_segments'}, 'start_frame_prompt': {'type': 'string', 'title': 'Start Frame Prompt', 'default': '', 'description': 'New start-frame prompt (generated video segments). Empty leaves it unchanged.'}}}
update_style_fields
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 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.
Destructive
Input schema
{'type': 'object', 'title': 'update_style_fieldsArguments', 'required': ['style_id', 'fields'], 'properties': {'fields': {'type': 'object', 'title': 'Fields', 'description': 'Sparse patch of style fields, shaped {key: {"value": str, "applies_to": [...]}} â\x80\x94 send ONLY the keys you are changing; unlisted keys keep their current value', 'additionalProperties': True}, 'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'Style ID, as returned by create_style or list_styles'}}}
update_style_references
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).
Destructive
Input schema
{'type': 'object', 'title': 'update_style_referencesArguments', 'required': ['style_id', 'inputs'], 'properties': {'inputs': {'type': 'array', 'items': {'type': 'object', 'additionalProperties': True}, 'title': 'Inputs', 'description': 'The COMPLETE reference list the style should have after this call, in display order: [{"input_type": "youtube" | "text" | "image" | "video", "value": "<url or text>", "contributes_to": ["art_style", ...]?}]. Include every existing entry you are keeping (copy them from get_style verbatim â\x80\x94 public URL values are fine); anything left out is removed'}, 'style_id': {'type': 'string', 'title': 'Style Id', 'description': 'Style ID, as returned by create_style or list_styles'}}}
update_voice_block
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.
Input schema
{'type': 'object', 'title': 'update_voice_blockArguments', 'required': ['voice_block_id'], 'properties': {'volume': {'anyOf': [{'type': 'number'}, {'type': 'null'}], 'title': 'Volume', 'default': None, 'description': 'Playback volume for this block, 0-1; omit to leave unchanged'}, 'voice_id': {'type': 'string', 'title': 'Voice Id', 'default': '', 'description': 'New TTS voice ID for this block, from list_voices; empty leaves the voice unchanged'}, 'voice_block_id': {'type': 'string', 'title': 'Voice Block Id', 'description': 'Voice block ID, from list_voice_blocks'}}}
view_image
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'view_imageArguments', 'required': ['url'], 'properties': {'url': {'type': 'string', 'title': 'Url', 'description': 'Public Framesail media URL to fetch â\x80\x94 a public_url from get_segment_assets, a file_path from list_assets, or a template/preset image URL from get_style / list_style_presets; other hosts are rejected'}}}
whoami
Who am I
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.
Read only
Idempotent
Input schema
{'type': 'object', 'title': 'whoamiArguments', 'properties': {}}
History
Recent tool changes
Changed
generate_asset_reference
Oct. 1, 2026, 2:53 a.m.
Changed
list_models
Oct. 1, 2026, 2:53 a.m.
Removed
remove_segment_sfx
Sept. 19, 2026, 2:51 a.m.
Changed
project_director_note
Sept. 19, 2026, 2:51 a.m.
Changed
director_note
Sept. 19, 2026, 2:51 a.m.
Added
remove_segment_asset
Sept. 19, 2026, 2:51 a.m.
Changed
add_segment_sfx
Sept. 19, 2026, 2:51 a.m.
Changed
get_segments
Sept. 19, 2026, 2:51 a.m.
Changed
save_script
Sept. 19, 2026, 2:51 a.m.
Added
view_image
Sept. 17, 2026, 12:34 p.m.
Added
remove_music_track
Sept. 17, 2026, 12:34 p.m.
Added
update_music_track
Sept. 17, 2026, 12:34 p.m.
Added
add_music_track
Sept. 17, 2026, 12:34 p.m.
Added
list_music_tracks
Sept. 17, 2026, 12:34 p.m.
Added
browse_audio_library
Sept. 17, 2026, 12:34 p.m.
Added
get_credit_balance
Sept. 17, 2026, 12:34 p.m.
Added
whoami
Sept. 17, 2026, 12:34 p.m.
Added
list_provider_keys
Sept. 17, 2026, 12:34 p.m.
Added
set_provider_key
Sept. 17, 2026, 12:34 p.m.
Added
delete_style
Sept. 17, 2026, 12:34 p.m.
Added
generate_style_template
Sept. 17, 2026, 12:34 p.m.
Added
analyze_style
Sept. 17, 2026, 12:34 p.m.
Added
create_style
Sept. 17, 2026, 12:34 p.m.
Added
list_style_presets
Sept. 17, 2026, 12:34 p.m.
Added
update_style_references
Sept. 17, 2026, 12:34 p.m.
Added
update_style_fields
Sept. 17, 2026, 12:34 p.m.
Added
get_style
Sept. 17, 2026, 12:34 p.m.
Added
list_styles
Sept. 17, 2026, 12:34 p.m.
Added
get_video_url
Sept. 17, 2026, 12:34 p.m.
Added
export_video
Sept. 17, 2026, 12:34 p.m.
Discover
Similar MCP servers
MiOffice — AI-Powered Workspace Studio
io.github.jsvvsolsllc/mioffice
Provides browser-based tools for processing PDFs, images, video, and audio, including generation, enhancement, conversion, transc…
BlitzReels Video Editor
com.blitzreels/blitzreels
Creates and edits short-form videos, including timelines, captions, transitions, AI-generated visuals, music, voiceovers, sound e…
Morpha
ai.morphareels/morpha
Enables creating, animating, and exporting layered short-form video projects.
switch
ai.switchapp/switch
Enables management and exploration of an account-scoped library of AI-generated images and videos.
Magnific
io.github.mcp-dir/magnific-mcp
Provides image enhancement and design tools, AI image and audio generation, text-to-speech, creation management, and reusable cre…
Uwear
ai.uwear/uwear
Supports AI fashion photoshoot production with garments, outfits, avatars, locations, art direction, image generation, backdrops,…
Creative Claw
co.creativeclaw/creative-claw
Generates and edits branded images, video, audio, speech, and 3D-related creative assets, with media processing and reusable them…
RegiAI
com.regiai/regiai
Generates and edits images, videos, audio, music, speech, subtitles, avatars, and related media asynchronously.