Framesail for agents

Framesail is the workflow and state layer for producing long-form video with AI: it owns the project database, asset continuity, voiceover timing, storyboard planning, and the render pipeline. Your agent drives the workflow; Framesail guarantees that minute 7 of the video is consistent with minute 1.

API & MCP access is included on the Pro and BYOK plans — see pricing.

Surfaces

Two equivalent surfaces, one auth scheme. The MCP tools are thin wrappers over the same REST endpoints — pick one surface per pipeline run.

Surface	URL	Best for
REST API	api.framesail.com	Scripts, SDKs, custom backends (OpenAPI at `/openapi.json`)
MCP server	api.framesail.com/mcp	Claude Code, Claude Desktop, claude.ai, Cursor, any MCP client

Connecting

Claude Code / Agent SDK (MCP)

terminal

claude mcp add --transport http framesail \
  https://api.framesail.com/mcp \
  --header "Authorization: Bearer fsk_..."

claude.ai / Claude Desktop

Settings → Connectors → Add custom connector → URL https://api.framesail.com/mcp, and supply the same Authorization header.

REST

Any HTTP client; the machine-readable spec lives at /openapi.json.

Authentication

Create an API key on your account page (/app/account → API Keys). Send it as a Bearer token — the same header works for both REST and MCP:

Authorization: Bearer fsk_...

Keys are shown once at creation and can be revoked anytime. For security, key management itself requires a signed-in browser session — an API key cannot mint or revoke API keys. Creating keys requires a Pro or BYOK subscription.

BYOK — bring your own model keys

On the BYOK plan, any job whose model provider you supply a key for runs on your key and bills 0 credits. Two modes, usable together:

1. Stored (recommended): PUT /provider-keys/{provider} with {"key": "..."} — encrypted at rest (AES-256-GCM), never returned or logged, removable anytime.

2. Per-request: send X-Provider-Key-<provider> headers (e.g. X-Provider-Key-Openai: sk-...) on any request, including the MCP connection. For async jobs the key travels encrypted on the job row and is wiped the moment the job finishes.

Providers: openai, gemini, anthropic, fal (all video models), elevenlabs, minimax. Coverage is per-job: with only an OpenAI key, GPT script jobs are free (BYOK) while a Gemini storyboard bills credits. Each job's record notes which mode billed it.

The workflow

Every generation call returns 202 {"job_id": ...} immediately. Poll GET /jobs/status?project_id=... every 5–15s (jobs flow pending → running → complete | error). MCP clients should prefer the await_jobs tool — it long-polls server-side (~50s per call) so the agent doesn't burn turns. Long steps are normal: storyboard generation takes minutes, not seconds, and a full segment render longer — don't treat a slow job as a failed one.

Resuming / orientation: GET /projects/{id}/pipeline (MCP: get_pipeline_progress) returns every step's state plus a single next_action — call it when picking up an existing project or after any step, instead of inferring progress. State lives server-side; sessions can stop and resume freely.

Step	REST	MCP tool
0 · Pick a channel	GET /channels (create: POST /channels)	list_channels / create_channel
1 · Create project	POST /projects	create_project
2 · Script	POST /generate/script (or POST /script/save for your own); review via GET /script	generate_script / save_script / get_script / revise_script
3 · Scan script	POST /generate/script_scan — extracts characters/environments/objects + voice blocks	scan_script / rescan_voice_blocks
4 · Review assets	GET /assets, PATCH /assets/{id}, then POST /assets/{id}/generate-reference for recurring characters	list_assets / update_asset / generate_asset_reference
5 · Voiceover	Bind voices (PATCH /projects/{id}/voice, PATCH /assets/{id}/voice), then POST /generate/voice_block_batch	list_voices / set_narrator_voice / set_character_voice / generate_voiceover
6 · Style templates	POST /generate/art_style_character_template + …_environment_template (required before storyboard)	generate_style_template
7 · Storyboard	POST /generate/storyboard — needs voiceover timing	generate_storyboard
8 · Render assets	POST /segments/generate-all?dry_run=true first (check credits), then for real	generate_segments / get_credit_balance
9 · Polish (optional)	Music, SFX, captions	browse_audio_library / add_music_track / add_segment_sfx / update_caption_config
10 · Build timeline	POST /scenes/build	build_scenes
11 · Export MP4	POST /projects/{id}/export	export_video
12 · Download	GET /projects/{id}/export/download-url	get_video_url

Steps are stateful — never fire step N+1 before step N's jobs are complete. Re-running scan_script deletes and recreates assets; after editing the script once assets are curated, use rescan_voice_blocks instead. After editing segments, regenerating assets, or changing music/captions, re-run build_scenes before export_video.

Styles & prompt overrides

Styles (channel-scoped) carry the creative identity: art_style, narrative_style, director_style, script_prompt, plus custom fields referenced as @field_name in prompts and resolved at generation time. Create styles from reference media (YouTube URLs, text, uploaded files) via POST /styles, then bind one to a project with PATCH /projects/{id}/defaults.

Per-call prompt overrides: every generate endpoint accepts editable_sections: {section_id: content} — the same expert surface the web UI exposes. GET /jobs/{job}/template lists each job's sections, defaults, and which are locked. Don't rebuild prompts from scratch; override the one section you need.

Models: GET /models?job=... lists allowed models per job; the first entry is the default. Model choice matters — flash-tier models flatten storyboard pacing, so the defaults are the validated tier.

Etiquette & limits

·Poll every 5–15s; don't tight-loop. Rate limits: 50/min, 1000/hour per key on generation endpoints.
·Steps are stateful — never fire step N+1 before step N's jobs are complete.
·dry_run=true on generate-all returns asset count + credit estimate; use it before committing a large render.
·Exports render on Framesail's infrastructure and are included in the plan (fair-use capped) regardless of BYOK.

Ready to connect? Generate a key on your account page, or review the Pro and BYOK plans.