framesail.com

Framesail turns a script into a finished long-form video: script -> asset scan -> reference images -> voiceover -> storyboard -> segment assets (images/video/ overlays) -> scenes -> rendered MP4. Step order is ENFORCED server-side. A step called before its prerequisites are done fails with a 409 step_not_ready error whose next_action names the exact tool to run instead — do that, don't retry the same call. Double-submits are also handled server-side: single-run steps (generate_script, scan_script, generate_storyboard, export_video) refuse to start while already running (job_already_running — await_jobs and re-check), and batch steps (generate_asset_reference, generate_voiceover, generate_segments) skip items already generated or in flight, so re-calling them never duplicates work or double-bills. On a fresh connection, whoami confirms which account and plan you're on (free, instant). If ANY tool returns 401, the key is invalid or revoked — tell the user to reconnect (OAuth clients) or create a new key on the account page; don't retry. A 403 means the account's plan lacks API access. Typical end-to-end run: 1. list_channels (or create_channel), then create_project(channel_id, title, description=the video concept). Pass video_format="portrait" when the user wants a vertical video (Shorts / Reels / TikTok) — it is fixed once the storyboard exists. A brand-new channel has no style yet — create_style (+ await_jobs(style_id=...)) and set_project_style before generating anything. When asking the user what style they want, offer two real options — never invent style choices: (a) reference matching (best): YouTube URLs of their channel or any video whose look they like (create_style inputs) — analysis extracts the art/narrative/director style from the footage; (b) curated presets: list_style_presets and let the user pick one per axis (instant, no analysis). Creating a style has a second half: generate_style_template for BOTH "character" and "environment" — a style isn't finished until both template images are rendered (skip any it already has — get_style's `templates` shows the rendered ones). 2. generate_script (or save_script with your own), await_jobs, then get_script — review/iterate with your user (save_script / revise_script) before moving on. 3. scan_script — extracts characters/environments/objects + voice blocks. 4. Review assets: list_assets, fix descriptions (update_asset), then generate_asset_reference for EVERY character, environment, and object — reference images keep them visually identical across every shot, and voiceover won't start until each of these assets has one. References render AGAINST the style's template images — make sure both templates are done (step 1) before generating any. 5. Voices: set_narrator_voice binds the narrator (browse with list_voices), set_character_voice for any character with dialogue, then generate_voiceover (word-level timing drives captions). 6. BEFORE generate_storyboard, ask the user for the asset mix — what share of segments to plan as still images vs animated video clips (percents totaling 100, default {"image": 70, "video": 30}; set via update_project(fields={"asset_mix": {"image": ..., "video": ...}})). This is the biggest cost lever in the whole pipeline: video clips cost far more to render than stills, and the storyboard plans against the mix, so it must be set first. Then generate_storyboard — plans every segment + its assets, honoring the channel's director/art/narrative styles. Review with get_segments — note each segment's continues_from_segment, which chains a shot off an earlier segment's frame for visual continuity (carry the frame, change only the delta). Fix surgically via update_segment_content / split_segment / combine_segments / change_segment_type / set_segment_continuation. 7. generate_segments — the HARD checkpoint (see Pace & spending): dry_run first, show the estimate, and wait for a fresh go-ahead before running for real. Inspect renders with get_segment_assets + view_image; re-render one with regenerate_segment_asset. 8. Optional polish: add_music_track (find tracks via browse_audio_library), add_segment_sfx, update_caption_config. 9. build_scenes, then export_video; await_jobs until the video_export job completes, then get_video_url. Pace & spending: content-creating tools (generate_*, scan_script, rescan_voice_blocks, revise_script, create_style, analyze_style, update_segment_content, director notes) bill platform credits — or the user's own provider keys on the BYOK plan. Read-only tools (list_*/get_*, view_image, await_jobs) and export_video are free. DEFAULT to checkpoint pacing: run ONE pipeline step, show your user what it produced — with that step's web_url from get_pipeline_progress so they can open it in the app — and what the next step costs, then wait for their go-ahead. Run multiple steps unprompted only when the user explicitly asked for an end-to-end run ("do the whole thing"); even then, report progress after each step. generate_segments is the one HARD stop: it is by far the most expensive step (often hundreds to thousands of credits). ALWAYS dry_run it and show the estimate next to get_credit_balance, then STOP and wait for a fresh yes given after the user has seen that estimate. A prior "do the whole thing" does NOT cover this spend — do not reason your way to approval from earlier permission or from the balance looking sufficient. The only exception: the user explicitly pre-authorized the render cost in so many words ("render without asking me"). Never regenerate work that already exists (script, references, voiceover, renders) unless asked — retrying a step that ERRORED is fine, "just to be safe" re-runs waste the user's money. All generation tools return {job_id} immediately. Call await_jobs(project_id=...) after each step — it blocks server-side until the step's jobs finish (or ~50s passes; call it again while done=false). Long steps are NORMAL: a storyboard takes 3-5 minutes, a full segment render can take longer. Jobs flow pending -> running -> complete|error. Resuming or unsure what's next? get_pipeline_progress(project_id) returns every step's state + the exact next action — state lives server-side, so you can stop for hours, reconnect in a new session, and pick up where the project left off (list_channels -> list_projects -> get_pipeline_progress). Never re-run a step just because you don't remember running it. Generation runs on the channel's configured styles by default — override per-call via editable_sections (see get_section_template for what each job exposes) and model (see list_models for alternates + each model's settings schema). Style fields support @variable references resolved at generation time. New visual identities: create_style with YouTube/text reference inputs, await_jobs(style_id=...), then set_project_style to put it into effect. Pitfalls: scan_script DELETES and recreates assets on re-run — after editing the script once assets are curated, use rescan_voice_blocks instead (assets untouched); voiceover requires every speaker to resolve to a voice first; after editing segments, regenerating assets, or changing music/captions, re-run build_scenes before export_video. Billing: on the BYOK plan, jobs run on your own provider API keys (0 credits) when a key for that model's provider is registered via set_provider_key; otherwise they bill platform credits (get_credit_balance shows the balance).