# Splice (film.fun)

> Splice is film.fun's AI filmmaking studio. Its Agent API lets scripts and LLM agents do what the dashboard does: create productions, generate images, video, voice, music and sound, edit media, plan shots, render Motion compositions and use the public template library. Authenticate with an agent key (`sk_…`). Every generation spends credits from the same account as the web app.

Base URL: `https://splice.film.fun`. All agent routes live under `/api/agents/*`. Send the key as `Authorization: Bearer sk_…` (or `x-api-key: sk_…`). Create keys at https://splice.film.fun/dashboard/api-keys. The secret is shown once, and a key acts as the user who created it. New accounts get 100 free credits.

Generation is asynchronous. A generate call returns `201 {production_item_id, job_id?, production_id}` straight away. Poll `GET /api/agents/productions/{production_id}/items/{production_item_id}` until `status` is `completed` (read `media_url`, or `answer` for vision-language) or `failed` (read `error_message`). There are no webhooks for agent calls. Send an `Idempotency-Key` header on every generate/edit call so that a retry never charges twice.

## Quickstart

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

# 1. Get the default production. It is created the first time.
curl -s "$B/session" -H "$H"
#    → {"creation_id":"<uuid>","production_id":"<forge id>","creation":{…}}
#    Or make a new one: POST $B/productions {"title":"My short","aspect_ratio":"9:16"}

# 2. Pick a model. is_default marks the default; tool_costs is the price in credits.
curl -s "$B/tools/generator-tools/video/models" -H "$H"

# 3. Generate. Use the creation_id. Model settings go in "parameters".
curl -s -X POST "$B/generate/video" -H "$H" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"production_id":"<creation_id>","prompt":"A paper boat drifts down a rainy street, slow dolly","modelId":"minimaxH3MaxTurbo","parameters":{"duration":6,"aspectRatio":"9:16"}}'
#    → 201 {"production_item_id":"<item>","job_id":"<job>","production_id":"<creation_id>"}

# 4. Poll every 3-10 s. Video takes about 1-5 min, images about 5-30 s.
curl -s "$B/productions/<creation_id>/items/<item>" -H "$H"
#    → {"id":"<item>","status":"completed","media_url":"https://…mp4",…}
```

Or use the CLI, a single-file Node 18+ client with no dependencies. It prints JSON when piped and has documented exit codes:

```bash
curl -fsSL https://splice.film.fun/cli/splice.mjs -o splice.mjs
node splice.mjs generate video --prompt "A paper boat in the rain" --model minimaxH3MaxTurbo --param duration=6 --wait
```

## MCP server

Splice is also a remote MCP server at `https://splice.film.fun/api/mcp` (Streamable HTTP). It authenticates with the same agent key and exposes the core of this API as 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` and `list_characters`. Generate tools return `{job_id, production_id, status: "pending"}` straight away; poll `get_job`. Billing, scopes and credits are the same as the HTTP routes.

```bash
claude mcp add --transport http splice https://splice.film.fun/api/mcp --header "Authorization: Bearer sk_..."
```

Cursor (`~/.cursor/mcp.json`): `{"mcpServers": {"splice": {"url": "https://splice.film.fun/api/mcp", "headers": {"Authorization": "Bearer sk_..."}}}}`

Without a key, MCP clients that support OAuth (claude.ai connectors, Claude Desktop, Claude Code via `/mcp`, Cursor) sign the user in with their film.fun account instead: add the URL alone. The server also exposes resources: `splice://models` (every model with its live price), `splice://docs/pricing`, `splice://docs/getting-started`, `splice://docs/authentication` and `splice://docs/mcp`.

A second, public MCP server needs no sign-in and spends nothing: `https://splice.film.fun/api/mcp/docs`. Its read-only tools are `search_docs`, `get_doc`, `list_models` (live prices), `get_pricing`, `list_templates` and `get_template`.

Discovery: [MCP server card](https://splice.film.fun/.well-known/mcp/server-card.json) (tools and resources), [SEP-2127 card](https://splice.film.fun/api/mcp/server-card), [AI Catalog](https://splice.film.fun/.well-known/ai-catalog.json), [ARD manifest](https://splice.film.fun/.well-known/ard.json), [API catalog (RFC 9727)](https://splice.film.fun/.well-known/api-catalog), [Agent Skills index](https://splice.film.fun/.well-known/agent-skills/index.json).

## Docs

- [Developer portal](https://splice.film.fun/developers) ([markdown](https://splice.film.fun/developers.md)): MCP and REST quickstarts, auth, the error envelope, rate limits, idempotency, async jobs, pagination, versioning and deprecation, sandbox, status and support.
- [agents.md](https://splice.film.fun/agents.md): which interface to use, in one page. [auth.md](https://splice.film.fun/auth.md): OAuth and key flows step by step.
- Every docs page answers `Accept: text/markdown` with markdown (the homepage is also at [/index.md](https://splice.film.fun/index.md)); template pages too (`/templates/{slug}.md`). Ask questions in natural language at `POST https://splice.film.fun/ask` (NLWeb).
- [Full API reference](https://splice.film.fun/llms-full.txt): every route with full descriptions and scopes (section 17), request bodies, polling, idempotency, errors, credits, templates, Motion and shot-sheet pipelines.
- [Agent manifest (JSON)](https://splice.film.fun/api/agents/manifest.json): a machine-readable catalog of every `/api/agents/*` route, with methods, scopes, error codes and feature flags. It needs no key and is kept in sync with the code by CI.
- [CLI](https://splice.film.fun/cli/splice.mjs): the `splice` command-line client. Run `node splice.mjs help`.
- [OpenAPI spec](https://splice.film.fun/api/openapi) and [Swagger UI](https://splice.film.fun/api-docs): cover the core routes only. The manifest is the complete list.
- [Pricing (markdown)](https://splice.film.fun/pricing.md): what a credit is, the credit packs, how to pay, and the live price of every model. Model prices are dynamic: read [pricing.json](https://splice.film.fun/pricing.json) or the MCP `list_models` tool before spending. Human page: [/pricing](https://splice.film.fun/pricing).

## Key endpoints

- `GET /api/agents/session`: the default production (`creation_id`); created if missing.
- `GET /api/agents/balance`: the credit balance, `{balance: {total, available, …}}`.
- `POST /api/agents/credits/purchase`: top up with Solana (USDC, SOL or AUDD). `{pack_id: starter|creator|pro|studio}` returns 402 with a Solana Pay URL (`payment_required.solana_pay.url`) that any wallet can pay, or a person can scan as a QR code.
- `GET /api/agents/credits/packs`: the packs and what each costs right now in USDC, SOL and AUDD.
- `GET /api/agents/credits/purchase/{transaction_id}`: poll after paying; it finds the payment on chain and applies the credits (`status: pending|completed`).
- Agent wallet: the CLI can hold a Solana keypair and top up by itself: `splice wallet create`, fund it once (USDC plus ~0.01 SOL for fees), then `splice credits buy starter`. Spending is capped per purchase and per day.
- `GET|POST /api/agents/productions`: list or create productions.
- `GET /api/agents/tools/generator-tools/{generator}/models`: the models for one generator, with cost and capabilities.
- `POST /api/agents/generate/{image|video|video-animate|video-image-audio|voice|music|sfx|lipsync|shot-framing|composition-render|…}`: start a generation.
- `POST /api/agents/edit/{clip|image|image-upscale|video-reframe|caption-burner|media-merge|…}`: edit existing media.
- `POST /api/agents/productions/{id}/publish-to-studio`: publish a finished video to film.fun Studio as an episode (plus an optional clip), using the Studio account the key's owner connected in Splice. Scope `studio:write`; re-publishing updates rather than duplicates.
- `GET /api/agents/productions/{id}/items/{itemId}`: poll one result.
- `POST /api/agents/productions/{id}/media`: upload a file (multipart, max 4.5 MB).
- `GET /api/public/generation-templates`: the public template library. It needs no key; each template carries a ready-to-run generation payload.

## All endpoints

<!-- endpoint-reference:start (generated from /api/agents/manifest.json; do not edit by hand) -->

Every `/api/agents/*` route, generated from the manifest. `[id]` is the production id (`creation_id`). Scopes, body notes and flags are in [llms-full.txt](https://splice.film.fun/llms-full.txt) section 17 and in [manifest.json](https://splice.film.fun/api/agents/manifest.json).

### balance

- `GET /api/agents/balance`: Credit summary

### characters

- `GET POST /api/agents/characters`: Client library
- `GET PUT /api/agents/characters/[characterId]`: Fetch / update one client-library character

### compositions

- `GET POST /api/agents/compositions`: List (GET) or create (POST) Motion (Hyperframes) compositions
- `GET PATCH DELETE /api/agents/compositions/[compositionId]`: Fetch (GET, full payload), update (PATCH: title/description/payload/thumbnail/status) or soft-delete (DELETE) one composition
- `POST /api/agents/compositions/[compositionId]/duplicate`: Clone a composition (title gets " (copy)")
- `GET /api/agents/compositions/[compositionId]/revisions`: Newest-first version history for one composition, without payloads (a payload can be 50KB+)
- `POST /api/agents/compositions/[compositionId]/revisions/revert`: Restore a composition to an earlier revision by revision_id

### credits

- `GET /api/agents/credits/packs`: Credit packs with their price now in each Solana token: { packs: [{ id, name, credits, price_usd, credits_per_usd, quotes: { USDC|SOL|AUDD:…
- `POST /api/agents/credits/purchase`: Buy a credit pack with Solana (USDC, SOL or AUDD)
- `GET /api/agents/credits/purchase/[transactionId]`: Status of a credit purchase
- `POST /api/agents/credits/transfer`: Transfer credits

### edit

- `POST /api/agents/edit/caption-burner`: Burn captions onto video
- `POST /api/agents/edit/clip`: Clip a video to a time range (ms or seconds)
- `POST /api/agents/edit/image`: Edit image (inpaint / outpaint / variation)
- `POST /api/agents/edit/image-color-grade`: Color grade
- `POST /api/agents/edit/image-draw`: Draw on image
- `POST /api/agents/edit/image-multiple`: Batch image edits
- `POST /api/agents/edit/image-upscale`: Upscale image
- `POST /api/agents/edit/media-merge`: Concatenate videos (input_urls[], in order). parameters.outputAspectRatio (e.g. "16:9") or width/height set the output shape; every input i…
- `POST /api/agents/edit/video-extend`: Continue a video with new footage from a prompt (MiniMax H3 Max extend, minimaxH3MaxExtend). video_url (1.6–60 s, ≤50 MB) + prompt (what ha…
- `POST /api/agents/edit/video-reframe`: Reframe a video to 9:16 / 4:5 / 1:1 / 16:9
- `POST /api/agents/edit/video-upscale`: Upscale a video to a higher resolution

### generate

- `POST /api/agents/generate/auto-sfx`: Auto-SFX for video
- `POST /api/agents/generate/character-sheet`: Character reference sheet
- `POST /api/agents/generate/composition-render`: Render a Hyperframes HTML composition to MP4 (HTML + assets -> MP4 via headless Chrome + FFmpeg)
- `POST /api/agents/generate/image`: Text-to-image generation
- `POST /api/agents/generate/lipsync`: Lip sync audio to a face
- `POST /api/agents/generate/location-sheet`: Location reference sheet
- `POST /api/agents/generate/music`: Music generation
- `POST /api/agents/generate/prop-sheet`: Prop reference sheet
- `POST /api/agents/generate/set-sheet`: Set reference sheet
- `POST /api/agents/generate/sfx`: Sound effects
- `POST /api/agents/generate/shot-framing`: Compose a shot from entities + prompt (@slug + item:<uuid>)
- `POST /api/agents/generate/timeline-export`: Render timeline to video
- `POST /api/agents/generate/video`: Text/image-to-video generation
- `POST /api/agents/generate/video-animate`: Animate still image to video
- `POST /api/agents/generate/video-image-audio`: Compose video from image + audio
- `POST /api/agents/generate/vision-language`: Vision + language reasoning
- `POST /api/agents/generate/voice`: Text-to-speech
- `POST /api/agents/generate/voice-changer`: Voice conversion

### idempotency

- `GET /api/agents/idempotency/[key]`: Look up a generate/edit request by its Idempotency-Key (the caller's own keys only; another account's key is a 404)

### locations

- `GET POST /api/agents/locations`: Client library

### manifest.json

- `GET /api/agents/manifest.json`: This manifest

### productions

- `GET POST /api/agents/productions`: List / create productions
- `GET PATCH DELETE /api/agents/productions/[id]`: Single production

### productions/[id]/characters

- `GET POST /api/agents/productions/[id]/characters`: Production-scoped characters (import + list)

### productions/[id]/clips

- `GET POST /api/agents/productions/[id]/clips`: List clips or create a draft
- `GET PATCH DELETE /api/agents/productions/[id]/clips/[clipId]`: Read / partial-update / soft-delete a clip draft
- `POST /api/agents/productions/[id]/clips/[clipId]/publish-transcription`: Apply segments + corrections to source transcription, retime cues, write a new transcription
- `POST /api/agents/productions/[id]/clips/[clipId]/publish-video`: Render a new video/audio file via the cog-clip-export model

### productions/[id]/compositions

- `GET /api/agents/productions/[id]/compositions`: The key owner's Motion compositions bound to this production or unbound (owner/editor access), newest first, without payloads. ?limit (≤200…
- `GET PATCH /api/agents/productions/[id]/compositions/[compositionId]`: GET: { composition, version, summary: { stage, layers[] }, html } (?include_html=false drops html; ETag = version)

### productions/[id]/draft-pipeline

- `POST /api/agents/productions/[id]/draft-pipeline`: One pitch drafts the PLAN half of the pipeline: generates a 60-second script, creates it, then chains the stage bridges (script→storyboard…

### productions/[id]/entity-slugs

- `GET POST DELETE /api/agents/productions/[id]/entity-slugs`: @slug CRUD for production entities

### productions/[id]/items

- `GET /api/agents/productions/[id]/items`: List production items
- `GET /api/agents/productions/[id]/items/[itemId]`: Get one item by id, fetched directly (any item in the production, not just the newest 50): id, status, media_url, job_id, job_status, cance…
- `POST /api/agents/productions/[id]/items/[itemId]/cancel`: Cancel a pending/processing generation

### productions/[id]/locations

- `GET POST /api/agents/productions/[id]/locations`: Production-scoped locations

### productions/[id]/media

- `POST /api/agents/productions/[id]/media`: Upload media: multipart/form-data with the file in "file" (max 4.5 MB); optional name, type, tags (JSON array), metadata (JSON object)

### productions/[id]/moodboards

- `GET POST /api/agents/productions/[id]/moodboards`: List or create moodboards (visual reference boards)
- `GET PATCH DELETE /api/agents/productions/[id]/moodboards/[moodboardId]`: Read / update / delete a moodboard

### productions/[id]/props

- `GET POST /api/agents/productions/[id]/props`: Production-scoped props

### productions/[id]/publish-to-studio

- `POST /api/agents/productions/[id]/publish-to-studio`: Publish this production's generated video to film.fun Studio (studio.film.fun, the episodic platform) with the Studio key the agent key's o…

### productions/[id]/quote

- `POST /api/agents/productions/[id]/quote`: Itemised quote before a multi-step job; spends nothing

### productions/[id]/readiness

- `GET /api/agents/productions/[id]/readiness`: Decision-helper that wraps /stages with a suggested_next_steps array ordered by the canonical pipeline (universe → moodboard → script → sto…

### productions/[id]/reference-analysis

- `POST /api/agents/productions/[id]/reference-analysis`: Read a reference video for its STRUCTURE and get back a timed shot plan

### productions/[id]/scripts

- `GET POST /api/agents/productions/[id]/scripts`: List or create persisted scripts for a production
- `GET /api/agents/productions/[id]/scripts/[scriptId]`: Read a single script

### productions/[id]/share-links

- `GET POST /api/agents/productions/[id]/share-links`: List / create share links (frame.io-style review or present)
- `GET PATCH DELETE /api/agents/productions/[id]/share-links/[linkId]`: Read share link with comments + decisions (split-approval polling target)

### productions/[id]/shot-sheet

- `GET PATCH /api/agents/productions/[id]/shot-sheet`: Shot Sheet aggregator
- `GET /api/agents/productions/[id]/shot-sheet/cost-preview`: Count-only cost preview for the bulk shot-sheet generators
- `GET /api/agents/productions/[id]/shot-sheet/from-script`: One-shot composer for "decompose this script" agent loops
- `POST /api/agents/productions/[id]/shot-sheet/seedance`: Send one shot in a Shot Sheet to Seedance 2 video generation
- `POST /api/agents/productions/[id]/shot-sheet/seedance/all`: Bulk: generate video for every shot in a Shot Sheet (or shot_ids), one shot at a time
- `POST /api/agents/productions/[id]/shot-sheet/stills`: Generate the still frame for one shot in a Shot Sheet
- `POST /api/agents/productions/[id]/shot-sheet/stills/all`: Bulk: generate stills for every shot in a Shot Sheet in parallel

### productions/[id]/shotboards

- `GET POST /api/agents/productions/[id]/shotboards`: Shotboards (shown as "Assembly" in the UI)
- `GET PATCH DELETE /api/agents/productions/[id]/shotboards/[shotboardId]`: Read / update / delete a shotboard

### productions/[id]/shotlists

- `GET POST /api/agents/productions/[id]/shotlists`: List or create shot lists for a production
- `GET PUT /api/agents/productions/[id]/shotlists/[shotlistId]`: Read or replace fields on a shot list

### productions/[id]/stages

- `GET /api/agents/productions/[id]/stages`: Aggregated production stage state

### productions/[id]/storyboards

- `GET POST /api/agents/productions/[id]/storyboards`: List or create storyboards for a production
- `GET PUT /api/agents/productions/[id]/storyboards/[storyboardId]`: Read or replace fields on a storyboard

### productions/[id]/studio

- `GET POST /api/agents/productions/[id]/studio/projects`: Studio projects
- `GET PATCH DELETE /api/agents/productions/[id]/studio/projects/[projectId]`: Read / update / delete a Studio project linked to this production
- `POST GET /api/agents/productions/[id]/studio/projects/[projectId]/export`: Export / render status

### productions/[id]/studio-handoff

- `GET /api/agents/productions/[id]/studio-handoff`: Browser handoff URL

### productions/[id]/studio-link

- `GET PUT /api/agents/productions/[id]/studio-link`: The production's film.fun Studio setting: {link: {enabled, studio_project_id, studio_project_url, studio_project_title, linked_at, linked_b…

### productions/[id]/takes

- `GET POST /api/agents/productions/[id]/takes`: List or create takes for the shoot stage
- `GET PUT DELETE /api/agents/productions/[id]/takes/[takeId]`: Read, update, or archive a single take

### productions/[id]/tasks

- `GET POST /api/agents/productions/[id]/tasks`: Tasks
- `GET PATCH DELETE /api/agents/productions/[id]/tasks/[taskId]`: Read / update / delete a single task
- `POST /api/agents/productions/[id]/tasks/[taskId]/notes`: Append to a task notes thread (use parent task GET for the thread itself)

### productions/[id]/transcriptions

- `GET POST /api/agents/productions/[id]/transcriptions`: List or create/upsert a transcription
- `GET PATCH DELETE /api/agents/productions/[id]/transcriptions/[transcriptionId]`: Read / partial-update / soft-delete a transcription

### productions/[id]/universe

- `GET POST /api/agents/productions/[id]/universe`: Universe Bible

### productions/[id]/universe-bundle

- `GET /api/agents/productions/[id]/universe-bundle`: One-shot read: Universe Bible + all production characters/locations/sets/props

### productions/[id]/variants

- `POST /api/agents/productions/[id]/variants`: Make variants of one shotlist that each change exactly ONE thing

### props

- `GET POST /api/agents/props`: Client library

### series

- `GET /api/agents/series`: Discovery: distinct series_id values across the agent's editable productions, with episode_count + max_episode_number + latest_created_at p…

### session

- `GET /api/agents/session`: Default session + creation/production id

### shotlists

- `POST /api/agents/shotlists/[shotlistId]/promote`: Promote a shotlist to a fresh shotboard

### skill

- `POST /api/agents/skill/brand-dna/extract`: Extract brand DNA (palette / typography / voice / values) from a URL or pasted text

### tools

- `GET /api/agents/tools/generator-tools`: List every generator tool with its enabled models embedded (?include=models, default)
- `GET /api/agents/tools/generator-tools/[generatorToolId]/models`: List models + capabilities for a generator
- `GET /api/agents/tools/generator-tools/image/models`: List image-generation models + capabilities (alias for generator-tools/[id]/models with id=image)

### transcribe

- `POST /api/agents/transcribe`: Audio/video -> text (JSON audio_url OR multipart file <=4.5MB)

### video-templates

- `GET POST /api/agents/video-templates`: List the agent client's video templates (filter by ?kind=script|storyboard|shotlist), or create one
- `POST /api/agents/video-templates/[templateId]/apply`: Apply a video template to a target production, creating a new scripts/storyboards/shotlists row seeded from the template's payload

<!-- endpoint-reference:end -->

## Optional

- [Splice](https://splice.film.fun): the web app. Everything an agent makes shows up in the user's dashboard.
- [Template library](https://splice.film.fun/templates): browse templates, with previews.
- [Studio API](https://studio.film.fun/llms.txt): publish episodes and series (a separate product and key type, `ff_sk_…`).
- [ReelKit](https://reelkit.fun): an optional agent layer on top of Splice that adds scheduling, approvals, spend caps and social posting. You don't need it to use this API.