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

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

Quickstart

The fastest path is claude.ai — zero config, no key handling:

1. Subscribe to Pro or BYOK (API & MCP access is plan-gated; the consent screen will tell you if your plan doesn't have it). 2. In claude.ai: Settings → Connectors → Add custom connector → https://api.framesail.com/mcp — a browser login opens; sign in and click Allow. 3. Verify: ask Claude "Am I connected to Framesail?" — the whoami tool reports your account and plan.

From there, your first pipeline run is a prompt away: "Create a Framesail project about <topic> and generate the script." For Claude Code instead, it's one command with an fsk_ key from your account page:

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

Everything below is the detail: the two surfaces, every client's connect config, how auth works under the hood, and the full pipeline workflow.

Surfaces

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

Connecting

claude.ai / Claude Desktop / Claude mobile — no key needed

Settings → Connectors → Add custom connector → URL https://api.framesail.com/mcp. Claude opens a Framesail login in your browser — sign in, click Allow, done. The connection appears on your account page as an API key you can revoke anytime.

Claude Code / Agent SDK

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

Cursor

{
  "mcpServers": {
    "framesail": {
      "url": "https://api.framesail.com/mcp",
      "headers": { "Authorization": "Bearer fsk_..." }
    }
  }
}

VS Code (Copilot agent mode)

{
  "servers": {
    "framesail": {
      "type": "http",
      "url": "https://api.framesail.com/mcp",
      "headers": { "Authorization": "Bearer fsk_..." }
    }
  }
}

Clients that support MCP OAuth can also omit the header entirely and connect to the bare URL — they'll pop the same browser login as claude.ai.

REST

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

Authentication

Two ways in, one credential type underneath. OAuth login (claude.ai, Claude Desktop, any OAuth-capable MCP client): connect to the URL, sign in, approve — Framesail mints the credential for you. API keys (config-file clients, scripts, REST): create an fsk_ key on your account page (/app/account → API Keys) and 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 — OAuth connections show up in the same list, so revoking works identically. For security, key management itself requires a signed-in browser session — an API key cannot mint or revoke API keys. API & MCP access requires a Pro or BYOK subscription.

OAuth under the hood

For anyone implementing a client: it's spec-standard MCP authorization — OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE (S256 only). An unauthenticated request to /mcp gets a 401 with a WWW-Authenticate header pointing at the resource metadata (/.well-known/oauth-protected-resource/mcp), which advertises the authorization server; registration and token endpoints are in /.well-known/oauth-authorization-server. The access token the flow mints is a regular fsk_ key — same power, same revocation, visible on your account page. Anonymous initialize and tools/list are allowed so clients and directories can inspect the catalog before logging in; every tool call requires the token.

Connected but not sure it worked? The whoami tool (REST: GET /me) returns the account email and plan behind the credential — the cheapest possible sanity check.

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.

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 — or instantly from the curated preset catalog (GET /style-presets, MCP list_style_presets) with one preset per axis. 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.

Troubleshooting