Splice for developers and agents

Splice is film.fun's AI filmmaking studio. Agents and scripts can do what the dashboard does: generate images, video, voice, music and sound; edit, upscale and reframe media; render motion graphics; and run the full idea-to-film pipeline. Everything is made on a user's Splice account and shows up in their dashboard.

There are three ways in: a remote MCP server (best for AI assistants), a REST API (best for scripts and backends) and a CLI. All three use the same accounts, credits and prices.

When to use Splice

Use Splice when a task needs:

• generated media (image, video, voice, music, sound effects) with a choice of current models and a known price per generation;
• edits to existing media: image edits, upscaling, video reframing to 9:16 / 1:1 / 16:9, clipping, merging, captions, lip sync, transcription;
• motion graphics (titles, lower-thirds, kinetic type) rendered to MP4;
• results kept in a project the user can open, edit and cut in the browser.

Don't use it for text-only tasks, or on behalf of someone who doesn't have (or want) a Splice account. Every generation spends that user's credits, so confirm the cost before an expensive run.

Quickstart: MCP

The product MCP server is https://splice.film.fun/api/mcp (Streamable HTTP). It signs the user in with OAuth 2.1, or takes an agent key as Authorization: Bearer sk_….

• Claude Code: claude mcp add --transport http splice https://splice.film.fun/api/mcp, then run /mcp and sign in. To use a key instead, add --header "Authorization: Bearer sk_...".
• claude.ai and Claude Desktop: Settings → Connectors → Add custom connector, and enter https://splice.film.fun/api/mcp.
• Cursor: Add to Cursor, or add {"mcpServers": {"splice": {"url": "https://splice.film.fun/api/mcp"}}} to ~/.cursor/mcp.json.
• VS Code: Install in VS Code, or run code --add-mcp '{"name":"splice","type":"http","url":"https://splice.film.fun/api/mcp"}'.
• Any other client: point a Streamable HTTP MCP client at https://splice.film.fun/api/mcp; it discovers OAuth from the 401.

Tools: list_models, get_balance, list_productions, generate_image, generate_video, generate_voice, generate_music, edit_image, upscale_image, upscale_video, get_job, list_compositions, get_composition, render_composition, list_characters. Read-only tools carry readOnlyHint; tools that spend credits are not idempotent unless you pass idempotency_key. Resources: splice://models (live prices) and splice://docs/*.

A public docs server needs no sign-in and spends nothing: https://splice.film.fun/api/mcp/docs (search_docs, get_doc, list_models, get_pricing, list_templates, get_template). Use it to look up models, prices and templates before connecting an account.

Quickstart: REST

export SPLICE_API_KEY=sk_...        # from https://splice.film.fun/dashboard/api-keys
B=https://splice.film.fun/api/agents
H="Authorization: Bearer $SPLICE_API_KEY"

# 1. The default production (created on first call).
curl -s "$B/session" -H "$H"

# 2. Models and prices for a generator.
curl -s "$B/tools/generator-tools/video/models" -H "$H"

# 3. Start a generation. It returns 201 straight away.
curl -s -X POST "$B/generate/video" -H "$H" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"production_id":"<production_id>","prompt":"A paper boat drifts down a rainy street, slow dolly","parameters":{"duration":5,"aspectRatio":"9:16"}}'

# 4. Poll until status is completed (media_url) or failed (error_message).
curl -s "$B/productions/<production_id>/items/<production_item_id>" -H "$H"

The CLI wraps all of this: curl -fsSL https://splice.film.fun/cli/splice.mjs -o splice.mjs && node splice.mjs help (Node 18+, no dependencies).

Authentication

• OAuth 2.1 for MCP connectors: dynamic client registration, PKCE (S256), scopes splice:read and splice:generate, rotating refresh tokens. Metadata: https://splice.film.fun/.well-known/oauth-authorization-server and https://splice.film.fun/.well-known/oauth-protected-resource.
• Agent keys (sk_…) for REST, the CLI and MCP-with-a-header. Create and revoke them at https://splice.film.fun/dashboard/api-keys. A key acts as the user who made it, and can be limited by scope and to one production.
• A request without valid credentials gets 401 with WWW-Authenticate: Bearer resource_metadata="…", which points at the protected-resource metadata.

The step-by-step flow for agents is in auth.md.

API reference

• OpenAPI 3 spec, also browsable at /api-docs.
• Agent manifest: every /api/agents/* route with methods, scopes and error codes, kept in sync with the code by CI.
• llms-full.txt: the complete reference, with request bodies and the planning pipeline.
• Public reads need no key: GET /pricing.json, GET /api/public/generation-templates and GET /api/public/generation-templates/{slug}.

Errors

Every error from /api/agents/* is JSON with one envelope:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits.", "details": {} } }

code is a stable snake_case string: match on it, not on message. Some errors add fields beside error (required, balance, shortfall, quote, payment_required).

An unknown /api/* path answers 404 {"error": {"code": "not_found", …, "docs_url": …}}. Over MCP, a failed tool call is a tool result with isError: true; protocol mistakes are JSON-RPC errors.

Rate limits

• /api/agents/*: 100 reads and 30 writes per minute per client IP. /api/mcp: 120 requests per minute per credential.
• Every API response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get 429 with Retry-After.
• Generation concurrency is capped per account: keep a handful of generations in flight, not hundreds.

Idempotency

Send an Idempotency-Key header (any unique printable string, up to 255 characters) on every generate and edit call; over MCP, pass idempotency_key. A retry with the same key returns the first result and never charges twice. If the first request is still running you get 409 idempotency_in_progress; if its outcome is unknown, 409 idempotency_outcome_unknown (look it up with GET /api/agents/idempotency/{key} rather than retrying with a new key).

Asynchronous jobs

Generation is asynchronous. A generate or edit call returns 201 {production_item_id, job_id?, production_id} at once. Poll GET /api/agents/productions/{production_id}/items/{production_item_id} (MCP: get_job) every 5-10 seconds. status goes pending → processing → completed (read media_url, or answer for vision) or failed (read error_message; failed generations are refunded). Cancel a running one with POST …/items/{itemId}/cancel. Images take 5-30 s, video 1-5 minutes. There are no webhooks for agent calls.

Pagination

List routes take ?limit= and ?offset= and return a pagination block:

{ "pagination": { "limit": 50, "offset": 0, "returned": 50, "total": 120, "has_more": true, "next_offset": 50 } }

Fetch the next page with ?offset=<next_offset>; it is null on the last page. Without a limit, routes that always returned everything still do. The maximum limit is 200.

Batch and bulk

• POST /api/agents/productions/{id}/shot-sheet/stills/all and …/shot-sheet/seedance/all: stills or video for every shot in a shot sheet. They take dry_run and max_credits, reuse unchanged takes at 0 credits, and return pending when more remains (call again).
• POST /api/agents/productions/{id}/variants: A/B variants of a shotlist that each change one thing.
• POST /api/agents/edit/image-multiple: several image edits in one call.
• POST /api/agents/productions/{id}/quote: an itemised price for a multi-step job; spends nothing.

Versioning and deprecation

• The agent API is versioned by date. The current version is 2026-10-01, sent on every /api/agents/* response as Splice-Api-Version.
• Within a version, changes are additive only: new routes, new optional fields, new error codes. Clients must ignore fields they don't know.
• A breaking change ships as a new version. The old behaviour is kept for at least 90 days, and responses from deprecated routes carry Deprecation and Sunset headers (RFC 9745, RFC 8594) with a Link to the migration notes.
• Changes are announced in llms.txt and the agent manifest.

Pricing and credits

Pay as you go, no subscription. Starter $10 = 1,000 credits · Creator $45 = 5,000 credits · Pro $99 = 11,500 credits · Studio $225 = 27,000 credits. New accounts get 100 free credits; credits don't expire. Model prices are dynamic: read them from /pricing.json, list_models or GET /api/agents/tools/generator-tools/{generator}/models. Human version: /pricing; markdown: /pricing.md. Agents can top up with Solana Pay through POST /api/agents/credits/purchase.

Sandbox and testing

There is no separate sandbox host: test against production with a new account.

• The 100 free sign-up credits cover a test integration (an image is about 6 credits; a 5-second default video about 30).
• Spend nothing while testing a pipeline: POST …/quote, and dry_run: true on the bulk routes, return prices without running anything.
• Cap spend with max_credits on bulk routes, and test Motion renders with previewSeconds (a short range at the lower preview price).
• The public docs MCP server and /pricing.json need no account at all.

Status and support

• Health: GET https://splice.film.fun/api/health returns {"status": "healthy", …}.
• Support: support@film.fun. Security reports: see security.txt.
• Splice is run by Automaton Limited (film.fun). Terms · Privacy.

Machine-readable discovery

• llms.txt and agents.md
• MCP server card and AI Catalog
• Agent Skills index
• API catalog (RFC 9727) and ARD manifest
• Every docs page answers Accept: text/markdown with markdown.