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_…. Step-by-step setup for each assistant, with plans and example prompts: Use Splice in Claude, ChatGPT, Grok, Claude Code and Codex.
- Claude Code:
claude mcp add --transport http splice https://splice.film.fun/api/mcp, then run/mcpand sign in. To use a key instead, add--header "Authorization: Bearer sk_...". - claude.ai and Claude Desktop: Customize → Connectors (on some accounts Settings → Connectors) → + Add → Add custom connector, and enter
https://splice.film.fun/api/mcp. - ChatGPT: add
https://splice.film.fun/api/mcpas a custom MCP server with OAuth (see Connect from ChatGPT). - 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"}'. - Codex:
codex mcp add splice --url https://splice.film.fun/api/mcpsigns in with OAuth; see the guide for the key option. - Grok: add
https://splice.film.fun/api/mcpat grok.com/connectors (New Connector → Custom) and sign in with OAuth; Grok Build:grok mcp add --transport http splice https://splice.film.fun/api/mcp. From the xAI API, pass anmcptool withserver_urlset to the server andauthorizationset to ansk_key (Grok setup). - Any other client: point a Streamable HTTP MCP client at
https://splice.film.fun/api/mcp; it discovers OAuth from the 401.
Read-only tools carry readOnlyHint. Tools that spend credits are not idempotent unless you pass idempotency_key. Resources: splice://models (live prices), splice://docs/*, and the craft guides as templates splice://guides/models/{id} and splice://guides/{kind}/{name}.
Craft guides and checks (free): Splice's own prompting and production craft is on the server. Call get_model_guide {model} before you prompt a model for the first time: it returns that model's guide (how the prompt names references, which differs per model and per provider, the prompt cap, ranges, what it ignores, verified examples) with the cross-model rules. list_guides / get_craft_guide read every other guide (writing tasks, video-motion craft, and any kind the media SDK adds). Before spending: check_video_prompt lints a video prompt for its model, pack_multishot puts several shots in one MiniMax H3 take, motion_design_brief and motion_quality_check bracket a Motion composition, and production_brief / production_qa plan and check a whole cut.
Signed in already? Your keys, connected apps and copy-ready setup commands are at Keys & integrations.
MCP tools
121 tools. Each one calls the matching /api/agents/* route with your credentials, so scopes, ownership, prices and billing are exactly those of the REST API. Generate and edit tools return {job_id, production_id, status: "pending"} at once; poll get_job.
Account and models
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_models | read | free | Enabled models for a generator type, with the price of each in credits. |
recommend_model | read | free | Top 3 enabled models for an intent, needs, budget and tier, each with a reason, price and gaps (free). |
get_balance | read | free | Credit balance: total, available and allocated. |
Productions and Universe
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_productions | read | free | Productions the user can edit, newest first (filter by series). |
create_production | generate | free | Create a production (title, or name as an alias). |
get_production | read | free | One production's details. |
update_production | generate | free | Change only the fields you send. |
list_series | read | free | Series (productions grouped as episodes). |
get_universe | read | free | A production's Universe: premise, canon, style, tone, and the narrator's voice. |
set_universe | generate | free | Create or update the Universe. |
get_universe_bundle | read | free | Universe plus linked characters, locations and props. |
list_universe_entities | read | free | Universe entities with their @slugs, the reference image a mention attaches, and each character's voice. |
list_scripts | read | free | A production's scripts, newest first. |
get_script | read | free | One script as Markdown, with its scene outline, cast and revision. |
create_script | generate | free | Write a new script (Markdown with screenplay conventions). |
update_script | generate | free | Change title, logline, synopsis, status, or replace the whole body. |
edit_script | generate | free | Edit by scene (rewrite, insert, delete, move, reorder, replace text, rename a character) with dry_run diff. |
list_script_revisions | read | free | A script's version history (who, what, when), or one version's text. |
revert_script | generate | free | Restore an earlier script version (added as a new version). |
match_script_cast | read | free | A script's cast vs the Universe: linked, suggested, ambiguous, missing, pinned but absent. |
create_cast_character | generate | spends | Create characters from cast names (linked, pinned), or link one; optional enhance is priced. |
list_moodboards | read | free | A production's moodboards (visual reference boards). |
get_moodboard | read | free | One moodboard: title, revision and its images, notes and frames in brief. |
create_moodboard | generate | free | Create an empty moodboard. |
add_moodboard_items | generate | free | Append up to 50 images and notes to a moodboard, laid out below what is there. |
extract_moodboard_look | generate | spends | A board's look: palette measured from its images (free), plus an aesthetic read (priced, quoted). |
get_production_look | read | free | The production look: its moodboard, palette words, lighting, grade, mood, avoid, and a context block. |
set_production_look | generate | free | Make a moodboard the production look (or clear it), and switch applying it by default. |
update_look | generate | free | Edit a look's descriptors, mood, avoid list or palette by hand (a board revision). |
list_loras | read | free | A production's style LoRAs (H3 video) with status and progress, and the Universe's style. |
get_lora | read | free | One style LoRA: status, progress, dataset, credits; poll it while it trains. |
train_lora | generate | spends | Train a style LoRA on 10-50 production clips: quotes first, then trains with max_credits + consent. |
cancel_lora | generate | free | Stop a LoRA training that is still preparing or queued; the hold is refunded. |
import_arena_pack | generate | free | Add an Arena competition's media pack to a production's Universe (merge rules, dry_run, free). |
delete_resource | generate | free | Delete a production, board, item, script, shotlist, timeline, entity and more: previews, then confirm. |
Library and uploads
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_characters | read | free | Characters in the library, or those linked to one production. |
list_locations | read | free | Locations in the library, or those linked to one production. |
list_props | read | free | Props in the library, or those linked to one production. |
create_entity | generate | free | Add a character, location or prop. |
list_entity_assets | read | free | An entity's images and their roles (sheet, avatar, reference, expression, outfit, turnaround). |
add_entity_asset | generate | free | Add an image to a character, location or prop, with a role. |
set_entity_sheet | generate | free | Set an entity's reference sheet, the image @slug mentions attach. |
set_entity_avatar | generate | free | Set an entity's display avatar (never attached to generations by default). |
set_entity_voice | generate | free | Give a character a named voice, or clone one with the user's confirmed consent. |
add_entity_to_production | generate | free | Link a library entity into a production and give it an @slug. |
copy_entity_to_production | generate | free | Copy a character, location or prop from another production (cloned voices and consent stay). |
upload_media | generate | free | Bring your own file into a production by https url (4 MB) or base64 (3 MB). |
import_media | generate | spends | Import a YouTube, TikTok, Instagram, X, Facebook or Reddit video (≤10 min, 2 credits/min, rights confirmed). |
Generate and edit
| Tool | Scope | Credits | What it does |
|---|---|---|---|
generate_image | generate | spends | Text or reference to image; takes aspect_ratio and resolution (e.g. 2K). |
generate_video | generate | spends | Text or image to video, priced per second. |
generate_keyframes_video | generate | spends | 2-10 images pinned to times in a 5-20 s clip, animated between (FLUX 3 Max), priced per second. |
generate_voice | generate | spends | Text to speech: words in text, delivery in style_instruction; voice "narrator" or character "@slug". |
generate_music | generate | spends | Music from a style prompt and/or lyrics. |
edit_image | generate | spends | Edit an image with an instruction ("make it night"). |
upscale_image | generate | spends | Upscale an image 2x, 4x or 6x. |
upscale_video | generate | spends | Upscale a video, priced per second. |
enhance_audio | generate | spends | Enhance speech, denoise, or upscale audio to 48 kHz (audio or a video soundtrack). |
generate_media | generate | spends | Any generator by kind: sfx, lipsync, sheets, shot framing, timeline export and more. |
edit_media | generate | spends | Any editor by kind: clip, crop, merge, captions, isolate voice, enhance audio, reframe and more. |
Jobs
| Tool | Scope | Credits | What it does |
|---|---|---|---|
get_job | read | free | Status of a job, or of any asset by its copied Library id: media_url when completed, cost once charged. |
list_items | read | free | A production's media items, filterable by type, status, name or tag. |
cancel_job | generate | free | Cancel a pending or processing job and refund it. |
get_idempotency_result | read | free | What happened to a paid call sent with an idempotency_key. |
Motion compositions
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_compositions | read | free | Motion compositions, newest first, without their HTML. |
get_composition | read | free | One composition with its HTML, size and duration. |
render_composition | read + generate | spends | Render to MP4 or WebM, or PNG stills at times_s (optionally transparent). |
create_composition | compose | free | New composition: an empty canvas at an aspect, or a built-in template. |
edit_composition | compose | free | Up to 50 ops, all or nothing, with version check and dry_run. |
list_composition_revisions | read | free | A composition's version history, newest first. |
revert_composition | compose | free | Restore an earlier revision (added as a new revision). |
Studio timelines
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_studios | read | free | A production's Studio (video editor) timelines. |
get_studio | read | free | A timeline as an outline (tracks -> items, captions, warnings) or in full, with its revision. |
get_studio_item | read | free | One item as the editor's inspector shows it (timing, transform, mask, audio, grade, text…). |
create_studio | compose | free | New timeline at an aspect, optionally already assembled by ops (one revision). |
edit_studio | compose | free | Up to 50 timeline ops, all or nothing, with base_revision, dry_run and a change summary. |
export_studio | read + generate | spends | Render to MP4; dry_run prices it, max_credits caps it. |
get_studio_export | read | free | An export's status, MP4 url, cost and loudness report. |
list_studio_revisions | read | free | A Studio timeline's version history: who (person or agent), what changed, when. |
revert_studio | compose | free | Restore an earlier timeline revision (added as a new revision, so it can be undone). |
Shotlists and takes
| Tool | Scope | Credits | What it does | ||
|---|---|---|---|---|---|
list_shotlists | read | free | A production's shotlists (scene-by-scene shot plans). | ||
get_shotlist | read | free | Scenes and shots: framing, lens, camera move, dialogue, hero asset. | ||
list_shot_takes | read | free | Takes per shot with each shot's hero; settles finished generations. | ||
generate_shot | generate | spends | A take of a shot from its framing, lens, move, cast refs and the previous shot's hero; dry_run quotes. | ||
match_previous_shot | generate | spends | A take that continues the previous shot's hero: same cast, wardrobe, light, location. | ||
coverage_pack | generate | spends | Wide / medium / close-up / reverse / insert takes of one moment, one itemised quote. | ||
match_scene | generate | spends | A scene's shots without a hero, in order, each matched to the one before; one quote; runs on the server. | ||
review_take | generate | free | Approve or reject a take with a note (owners, editors, reviewers). | ||
set_hero_take | generate | free | Pick a shot's hero take; its media goes onto the shot. | ||
check_faces | generate | spends | Same-person check of an image/video against the production's character references (0.25 credits). | ||
get_face_check | read | free | Face-check results for outputs: verdict, score, per character, regenerations. | ||
regenerate_mismatch | generate | spends | Re-run an output that failed its face check (new seed); dry_run quotes, max_credits caps. | ||
set_face_check_mode | generate | free | Automatic face checks: off | flag | auto_regenerate (max_attempts, max_credits). |
Production stages (script to cut)
| Tool | Scope | Credits | What it does |
|---|---|---|---|
get_production_stages | read | free | Each stage's count, newest rows and links, and the next step with the tool to call. |
draft_pipeline | generate | free | One pitch drafts a linked script, storyboard and shotlist (about a minute, free). |
list_storyboards | read | free | A production's storyboards (a script's beats with reference frames). |
get_storyboard | read | free | One storyboard with its beats and frames. |
create_storyboard | generate | free | New storyboard, usually from a script (script_id, beats). |
update_storyboard | generate | free | Change only the fields you send; beats replaces the list. |
create_shotlist | generate | free | New shotlist with scenes and shots, linked to its script and storyboard. |
add_shots | generate | free | Append shots to a scene, or a new scene holding them. |
update_shot | generate | free | Change one shot's description, framing, camera, duration, source or dialogue. |
remove_shot | generate | free | Remove one shot (its takes stay in the library). |
reorder_shots | generate | free | Reorder the shots of a scene (full order, or move one). |
list_shotboards | read | free | Shot boards (optional per-shot frame planning) with editor links. |
get_shotboard | read | free | One shot board's shots: prompts, first and last frames, chosen take. |
promote_shotlist | generate | free | Copy a shotlist's shots into a new shot board (optional, free). |
Craft guides and checks (free)
| Tool | Scope | Credits | What it does |
|---|---|---|---|
list_guides | read | free | Every craft guide (model prompting, prompt rules, writing tasks, video motion) and the free checks. |
get_model_guide | read | free | How to prompt one model: its guide, hard facts and the cross-model rules. Call before first use. |
get_craft_guide | read | free | Any craft guide by id or topic (scripts, shot lists, lyrics, social copy, prompt rules …). |
get_video_motion_guide | read | free | Motion craft for video prompts: H3 settings, camera language, timed beats, text, long takes. |
check_video_prompt | read | free | Lint a video prompt for its model (labels, dropped inputs, beats vs duration) before paying. |
pack_multishot | read | free | Pack a scene of short shots into as few MiniMax H3 multi-shot takes as fit. |
lint_multishot | read | free | Check a hand-written H3 multi-shot prompt: shot numbers, cut times, speakers, dialogue tags. |
motion_design_brief | read | free | A director's brief (personality, easing, timing, quality gate) before a Motion composition. |
gsap_for_use_case | read | free | The GSAP pattern, easing and snippet for an animation described in plain words. |
motion_quality_check | read | free | Review an animation (and lint custom GSAP) against the motion-quality checklist. |
production_brief | read | free | Segments, assets per beat, durations and a QA gate for a whole cut (advert, explainer …). |
production_qa | read | free | Pre-render checklist for an assembled cut: hook, audio, captions, CTA, duration. |
get_tool_help | read | free | A tool's full description and input schema (tools/list carries the short form). |
Search (ChatGPT shape)
| Tool | Scope | Credits | What it does |
|---|---|---|---|
search | read | free | Search productions, media, compositions, public templates and docs. |
fetch | read | free | The full document for an id from search. |
Motion compositions (free to edit): edit_composition applies up to 50 ops (the in-app agent's own tools: add_clips, update_clip, set_clip_animations, set_stage, apply_template, replace_html…) all or nothing, with version compare-and-set and dry_run. Clips are addressed by id or name; an unknown clip returns the candidates, and a clip you give your own id is updated, not duplicated, on retry. Every saved edit is a revision the user sees in the editor's History panel. render_composition renders MP4 or WebM (loudness: social by default, podcast, broadcast, a LUFS number, or off), or PNG stills at times_s (transparent: true for an alpha background). Each still gets its own URL (data.png, data-1.png, data-2.png…), listed in order as stills[{time_s, url}] on get_job, so one call can capture several frames.
Studio timeline editing (free): get_studio reads a Studio (video editor) timeline as an outline (tracks, top layer first, each with its items: id, start, end, asset, trim, volume, text, mask, transitions) plus its revision, and get_studio_item shows one item the way the editor's inspector does. edit_studio takes up to 50 ops and applies them all or nothing. If any op or the finished timeline is invalid, nothing is saved and every issue comes back with its op index. The ops cover tracks; adding items from a Library asset, composition:<id> or @slug; move, trim, split and duplicate; every inspector property (transform, fit, opacity, mask, colour grade, chroma key, freeze, volume and keyframes, fades, speed, animation keyframes, text style); transitions (connect_to for a cross-transition); captions (cues or SRT, presets); settings (aspect, length, export loudness, project grade); and two helpers, auto_assemble and add_voiceover, which ducks the music. Pass base_revision and dry_run as you would for Motion. create_studio can build the first cut in the same call, as one revision attributed to your key. export_studio renders an MP4 and spends credits: dry_run prices it and max_credits caps it. Poll get_studio_export for the result. Over REST, use POST /api/agents/productions/{id}/studio/projects/{studioId}/edit and GET …/{studioId}?view=outline. Viewers can read but not edit. The in-app agent chat has the same tools, and an open editor reloads by itself after a chat edit.
Studio timeline history (free): every saved change to a Studio (video editor) timeline, from the person in the editor, your agent or ReelKit, is a revision kept on the server. list_studio_revisions shows who made each one (person, agent, restore), its source (ui, agent-chat, mcp, api), a label and what changed (clips added, removed, moved, edited). revert_studio restores one by adding a new revision, so nothing is lost and a restore can itself be undone. Over REST, GET and PATCH /api/agents/productions/{id}/studio/projects/{studioId} return revision: send it back as base_revision and a write made after someone else saved gets 409 revision_conflict (with latest_revision: who and when) instead of overwriting them. Add summary to label your edit in the editor's History panel. An open editor shows "Updated by agent: …" within about 20 seconds.
Asset ids from the Library: every Library card and asset detail in Splice has a copy button on its short id (e.g. 8c882810). It copies the asset's full id, the production item id. Paste it into Claude or ChatGPT: get_job with that id and no production_id finds the asset in your productions and returns its production_id, type and media_url. Media inputs (reference_images, reference_videos, reference_audios, first_frame_image, last_frame_image, input_url, video_url, audio_url) take the asset id, or item:<asset id>, in place of a URL; it resolves to that asset's media_url in the same production. The in-app agent chat understands a pasted asset id too.
Universe characters, locations and props: write @slug in a generate_image or generate_video prompt, or a shot-framing input.prompt (or pass entities: ["slug"]), and Splice attaches that entity's reference image automatically: a character sheet or portrait, a location plate or a prop image. list_universe_entities lists the slugs and their reference images.
- Images and reference-capable video models get the image as a labelled reference, using each model's own syntax (
[Image1]for Seedance,Image 1for MiniMax H3,<<<image_1>>>for Kling O1). - Shot framing gets it in
characterImageUrls. - For a video model without reference inputs,
first_frame: "auto"composes a first frame from the references (shot framing, charged separately) and animates it.
Results list the references attached, and warnings name any mention that wasn't attached. require_references: true refuses those mentions before anything is charged.
Audio clean-up: enhance_audio takes an audio_url (WAV or MP3) or a video_url (its soundtrack) and a mode: enhance (default) cleans up a noisy or muffled voice, denoise removes background noise only, super-resolution upsamples low-sample-rate music and effects to 48 kHz (for speech, even phone-quality, use enhance). It returns a WAV as long as the source, priced on that length (list_models type audio-enhance).
Any generator or editor: generate_media and edit_media take a kind (sheets, sound effects, lipsync, shot framing, timeline export, clip, merge, captions, isolate voice, enhance audio …) and the route's own JSON body as input (see the agent manifest).
MCP scopes
| Scope | Allows | Tools |
|---|---|---|
splice:read | Read your productions, compositions, characters, locations, props, models and credit balance | list_models, recommend_model, get_balance, list_productions, get_job, list_compositions, get_composition, render_composition, list_characters, search, fetch, list_composition_revisions, list_items, get_idempotency_result, get_production, list_series, get_universe, get_universe_bundle, list_universe_entities, list_scripts, get_script, list_script_revisions, match_script_cast, list_moodboards, get_moodboard, get_production_look, list_loras, get_lora, list_locations, list_props, list_entity_assets, list_studios, get_studio, get_studio_item, export_studio, get_studio_export, list_studio_revisions, list_shotlists, get_shotlist, list_shot_takes, get_face_check, get_production_stages, list_storyboards, get_storyboard, list_shotboards, get_shotboard, list_guides, get_model_guide, get_craft_guide, get_video_motion_guide, check_video_prompt, pack_multishot, lint_multishot, motion_design_brief, gsap_for_use_case, motion_quality_check, production_brief, production_qa, get_tool_help |
splice:generate | Generate and edit media, manage your productions and library, and spend your Splice credits | generate_image, generate_video, generate_keyframes_video, generate_voice, generate_music, edit_image, upscale_image, upscale_video, enhance_audio, render_composition, generate_media, edit_media, cancel_job, create_production, update_production, set_universe, create_script, update_script, edit_script, revert_script, create_cast_character, create_moodboard, add_moodboard_items, extract_moodboard_look, set_production_look, update_look, train_lora, cancel_lora, create_entity, add_entity_asset, set_entity_sheet, set_entity_avatar, set_entity_voice, add_entity_to_production, copy_entity_to_production, upload_media, import_media, import_arena_pack, export_studio, generate_shot, match_previous_shot, coverage_pack, match_scene, review_take, set_hero_take, check_faces, regenerate_mismatch, set_face_check_mode, draft_pipeline, create_storyboard, update_storyboard, create_shotlist, add_shots, update_shot, remove_shot, reorder_shots, promote_shotlist, delete_resource |
splice:compose | Create, edit and remove your Motion compositions and Studio timelines (free; every edit is saved as a version you can restore) | create_composition, edit_composition, revert_composition, create_studio, edit_studio, revert_studio |
render_composition needs both splice:read and splice:generate. A call without a tool's scope gets HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="…", so the client can ask the user to approve it.
Make a film over MCP
Ask your assistant for the film in plain words and it runs these calls. Every argument name here is the tool's own.
- Make a production.
create_production({fields: {title: "Rain Ramen", aspect_ratio: "9:16"}})returns itsproduction_id. Pass it on every later call. - Bring your own files (optional).
upload_media({production_id, url: "https://…/logo.png", name: "Logo"})returns amedia_urlyou can use as an input or a composition asset. Public https links up to 4 MB, ordata_base64up to 3 MB. - Check prices.
list_models({type: "video"})andget_balance(). Tell the user the cost before a big run. - Generate.
generate_image({production_id, prompt, aspect_ratio: "9:16", idempotency_key}), thengenerate_video({production_id, prompt, first_frame_image: <the image's media_url>, duration: 5, idempotency_key}), andgenerate_voice/generate_musicfor sound. Each returns{job_id, production_id, status: "pending"}at once. - Wait for results.
get_job({job_id, production_id})every 5 to 10 seconds untilstatusiscompleted(readmedia_url) orfailed(readerror_message; failed jobs are refunded). Once charged,costshowscredits_charged,credits_refundedandcredits_net. - Compose titles and the cut.
create_composition({title: "Rain Ramen opener", aspect: "9:16"}), thenedit_composition({composition_id, version, ops: [{op: "add_clips", clips: [...]}]})with the media URLs from step 5. Trydry_run: truefirst; pass the lastversionso you never overwrite the user's edits. - Check, then render.
render_composition({composition_id, production_id, output_format: "png", times_s: [1, 4]})gives cheap stills to look at. Thenrender_composition({composition_id, production_id, output_format: "mp4"})and pollget_job; the result has the MP4media_urland anaudio_report(loudness, peaks, silence).
For a story told in scenes, let the stages lead instead: get_production_stages({production_id}) says what exists and the next tool to call, and draft_pipeline({production_id, pitch}) drafts the script, storyboard and shotlist in one free call, then shots (match_scene), the cut (create_studio) and export_studio.
Everything lands in the production in the user's dashboard, where they can open, edit and cut it. If a paid call times out, ask get_idempotency_result({idempotency_key}) before sending it again.
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.
Recipes, prompts and troubleshooting
Recipes are step-by-step tool chains for one finished job, with the price checkpoints, served as guides (get_craft_guide {topic} or the resource):
splice://guides/recipes/recurring-lead-opener: a series opener with the same lead in every shotsplice://guides/recipes/product-spot-from-a-photo: a 15-30 s product spot from one product photosplice://guides/recipes/look-led-teaser: a teaser whose every shot follows a moodboard looksplice://guides/recipes/track-led-music-video: a music video cut to the sections of a tracksplice://guides/recipes/link-to-vertical-clip: a captioned 9:16 clip from a video the user ownssplice://guides/recipes/landscape-to-vertical-cutdown: a vertical cutdown of a finished 16:9 cutsplice://guides/recipes/title-and-lower-thirds-pack: matching titles, lower-thirds and an end cardsplice://guides/recipes/scene-coverage-pass: wide, close and reverse angles of one key moment
Prompts (prompts/list on https://splice.film.fun/api/mcp) are the same kind of plan, ready to pick from your client's prompt menu: make_a_short, whats_next, title_card, storyboard_from_script, cut_and_export and fix_my_prompt.
When something fails, tool errors carry hint and next_tool for the common cases, and splice://guides/troubleshooting has the full table by status and code. Before resending any paid call, get_idempotency_result says whether it already ran. New tools are listed at splice://whats-new: if your client doesn't show one, reconnect Splice so it reloads the tool list.
Connect from ChatGPT
ChatGPT connects to https://splice.film.fun/api/mcp as a custom MCP server, and you sign in with your film.fun account; there's no key to paste. On newer accounts add it from Plugins (+ → Add custom MCP server); on others turn on Developer mode under Settings → Apps → Advanced settings and create an app. Choose OAuth and leave the client ID and secret empty: ChatGPT registers itself.
- Business, Enterprise and Edu get every tool. Pro gets
searchandfetchonly (read and fetch). searchreturns{results: [{id, title, url}]}andfetchreturns{id, title, text, url, metadata}, over your productions, media items and Motion compositions plus public templates and docs. Ids look likeproduction:…,composition:…ortemplate:….- ChatGPT asks you to confirm each write action. Revoke it under Connected apps at https://splice.film.fun/dashboard/api-keys.
Step by step: /connect#chatgpt.
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,splice:generateandsplice:compose(plus opt-insplice:producefor REST share links and transcription), rotating refresh tokens, any-port loopback redirects for native apps. Metadata:https://splice.film.fun/.well-known/oauth-authorization-serverandhttps://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. When you create one you choose its access, an optional expiry (30, 90 or 365 days) and an optional default production for calls withoutproduction_id:
| Access | What the key can do |
|---|---|
| Full access | Everything the dashboard can do: generate, edit, Motion, buy credits with Solana, publish to Studio, share links. |
| Create | Read, generate and edit (spends credits), manage productions, Motion and Studio timelines. No credit purchases, Studio publishing or share links. |
| Read only | List and read productions, media, compositions, models and the balance. Spends nothing. |
An expired or revoked key gets 401. Over MCP, a Full access or Create key holds all three MCP scopes and a Read only key holds splice:read.
- A request without valid credentials gets
401withWWW-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-templatesandGET /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).
| Status | Common codes | What to do |
|---|---|---|
| 400 | invalid_request, invalid_body | Fix the request; details names the field |
| 401 | unauthorized | Send a valid key or token (see Authentication) |
| 402 | insufficient_credits, payment_required | Top up, then retry with the same Idempotency-Key |
| 403 | forbidden | The key or token lacks the scope in details.required_scope |
| 404 | not_found | The id isn't the caller's, or doesn't exist |
| 409 | conflict, idempotency_in_progress, idempotency_outcome_unknown, quote_exceeds_max_credits, version_conflict | See Idempotency, or re-read and retry |
| 415 / 422 | unsupported_media_type, unprocessable_entity | Send the content type and shape the route expects |
| 429 | rate_limited | Wait Retry-After seconds |
| 501 | not_implemented and feature codes (cancel_unavailable, quote_unavailable) | The feature is off; see features in the manifest |
| 502 / 503 / 504 | upstream_error, service_unavailable, upstream_timeout | Retry with backoff and the same Idempotency-Key |
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.
Unknown parameters
Splice tells you when it ignores something you sent, instead of dropping it silently.
- MCP: a tool call with an argument the tool doesn't have fails with
isError: true. The message names the unknown argument and lists the accepted ones, for exampleUnknown parameter "speaker". Accepted: "text", "production_id", "model", "parameters", "idempotency_key".Nothing runs and nothing is charged. Fix the call and send it again. - REST: an
/api/agents/*request with unknown top-level body fields still runs, for now. The response adds awarningslist that says what was ignored. Read it and fix your request: a later API version may reject unknown fields. - Only the top level is checked. Model-specific settings go in
parameters, which takes any key the model supports (seeinputsinlist_models).
A REST response with a warning:
{ "production_item_id": "…", "production_id": "…", "warnings": [{ "code": "unknown_params", "message": "Ignored unknown parameter \"speaker\". Accepted: \"production_id\", \"text\", \"modelId\", \"parameters\".", "unknown": ["speaker"], "accepted": ["production_id", "text", "modelId", "parameters"] }] }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-RemainingandX-RateLimit-Reset(seconds). Over the limit you get429withRetry-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). Once the job is charged the item has cost: {credits_charged, credits_refunded, credits_net, refunded}, and a finished render has audio_report (integrated LUFS, true peak, clipping, longest silence). 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.
Uploading your own media
POST /api/agents/productions/{id}/media (scope productions:write; MCP: upload_media) takes a multipart file (up to 4.5 MB), JSON {url} (Splice fetches a public https link: image, video, audio or PDF, up to 4 MB) or JSON {data_base64, content_type, file_name?} (up to 3 MB). It returns 201 {media_item: {id, name, type, file_size, media_url}}; use media_url as an input to generate and edit calls or as a Motion asset. Uploading is free.
POST /api/agents/productions/{id}/media/import (scope productions:write; MCP: import_media) imports a video from a link: YouTube (watch, Shorts, youtu.be), TikTok, Instagram, X, Vimeo, Facebook, Reddit, or a direct https .mp4/.mov/.webm. Body {url, start_s?, end_s?, name?, meta?: {durationS?}, rights: {attested: true, statement_version: "2026-10-13"}, dry_run?}: rights says your user owns the video or has permission to use it, and is recorded with the import. It keeps at most 600 s (10 minutes; the whole video when you send no span), at most 720p, under 18 MB up to a minute and under 50 MB beyond, as H.264/AAC MP4. It returns 202 {production_item_id, production_id, import_id, status, price} at once; poll GET …/items/{production_item_id}. It costs 2 credits per minute (rounded up) of the span: up to 60 s = 2, 61-120 s = 4, 600 s = 20. Without end_s the span is up to 600 s, so send end_s or meta.durationS (the video's length) when you know it; a span over a minute is held and refunded down to the imported video's minutes, and a failed import is refunded in full. dry_run: true returns {dry_run, price: {span_s, minutes, credits, unit, upper_bound}} without importing. 10 imports an hour and 40 a day per user. Private, age-restricted, members-only, region-locked, DRM-protected and live videos fail with an IMPORT_* reason; nothing works around logins, paywalls or DRM.
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/alland…/shot-sheet/seedance/all: stills or video for every shot in a shot sheet. They takedry_runandmax_credits, reuse unchanged takes at 0 credits, and returnpendingwhen 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 asSplice-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
DeprecationandSunsetheaders (RFC 9745, RFC 8594) with aLinkto 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, anddry_run: trueon the bulk routes, return prices without running anything. - Cap spend with
max_creditson bulk routes, and test Motion renders withpreviewSeconds(a short range at the lower preview price). - The public docs MCP server and
/pricing.jsonneed no account at all.
Status and support
- Health:
GET https://splice.film.fun/api/healthreturns{"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/markdownwith markdown.