Skip to main content

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 /mcp and 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/mcp as 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/mcp signs in with OAuth; see the guide for the key option.
  • Grok: add https://splice.film.fun/api/mcp at 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 an mcp tool with server_url set to the server and authorization set to an sk_ 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

ToolScopeCreditsWhat it does
list_modelsreadfreeEnabled models for a generator type, with the price of each in credits.
recommend_modelreadfreeTop 3 enabled models for an intent, needs, budget and tier, each with a reason, price and gaps (free).
get_balancereadfreeCredit balance: total, available and allocated.

Productions and Universe

ToolScopeCreditsWhat it does
list_productionsreadfreeProductions the user can edit, newest first (filter by series).
create_productiongeneratefreeCreate a production (title, or name as an alias).
get_productionreadfreeOne production's details.
update_productiongeneratefreeChange only the fields you send.
list_seriesreadfreeSeries (productions grouped as episodes).
get_universereadfreeA production's Universe: premise, canon, style, tone, and the narrator's voice.
set_universegeneratefreeCreate or update the Universe.
get_universe_bundlereadfreeUniverse plus linked characters, locations and props.
list_universe_entitiesreadfreeUniverse entities with their @slugs, the reference image a mention attaches, and each character's voice.
list_scriptsreadfreeA production's scripts, newest first.
get_scriptreadfreeOne script as Markdown, with its scene outline, cast and revision.
create_scriptgeneratefreeWrite a new script (Markdown with screenplay conventions).
update_scriptgeneratefreeChange title, logline, synopsis, status, or replace the whole body.
edit_scriptgeneratefreeEdit by scene (rewrite, insert, delete, move, reorder, replace text, rename a character) with dry_run diff.
list_script_revisionsreadfreeA script's version history (who, what, when), or one version's text.
revert_scriptgeneratefreeRestore an earlier script version (added as a new version).
match_script_castreadfreeA script's cast vs the Universe: linked, suggested, ambiguous, missing, pinned but absent.
create_cast_charactergeneratespendsCreate characters from cast names (linked, pinned), or link one; optional enhance is priced.
list_moodboardsreadfreeA production's moodboards (visual reference boards).
get_moodboardreadfreeOne moodboard: title, revision and its images, notes and frames in brief.
create_moodboardgeneratefreeCreate an empty moodboard.
add_moodboard_itemsgeneratefreeAppend up to 50 images and notes to a moodboard, laid out below what is there.
extract_moodboard_lookgeneratespendsA board's look: palette measured from its images (free), plus an aesthetic read (priced, quoted).
get_production_lookreadfreeThe production look: its moodboard, palette words, lighting, grade, mood, avoid, and a context block.
set_production_lookgeneratefreeMake a moodboard the production look (or clear it), and switch applying it by default.
update_lookgeneratefreeEdit a look's descriptors, mood, avoid list or palette by hand (a board revision).
list_lorasreadfreeA production's style LoRAs (H3 video) with status and progress, and the Universe's style.
get_lorareadfreeOne style LoRA: status, progress, dataset, credits; poll it while it trains.
train_lorageneratespendsTrain a style LoRA on 10-50 production clips: quotes first, then trains with max_credits + consent.
cancel_lorageneratefreeStop a LoRA training that is still preparing or queued; the hold is refunded.
import_arena_packgeneratefreeAdd an Arena competition's media pack to a production's Universe (merge rules, dry_run, free).
delete_resourcegeneratefreeDelete a production, board, item, script, shotlist, timeline, entity and more: previews, then confirm.

Library and uploads

ToolScopeCreditsWhat it does
list_charactersreadfreeCharacters in the library, or those linked to one production.
list_locationsreadfreeLocations in the library, or those linked to one production.
list_propsreadfreeProps in the library, or those linked to one production.
create_entitygeneratefreeAdd a character, location or prop.
list_entity_assetsreadfreeAn entity's images and their roles (sheet, avatar, reference, expression, outfit, turnaround).
add_entity_assetgeneratefreeAdd an image to a character, location or prop, with a role.
set_entity_sheetgeneratefreeSet an entity's reference sheet, the image @slug mentions attach.
set_entity_avatargeneratefreeSet an entity's display avatar (never attached to generations by default).
set_entity_voicegeneratefreeGive a character a named voice, or clone one with the user's confirmed consent.
add_entity_to_productiongeneratefreeLink a library entity into a production and give it an @slug.
copy_entity_to_productiongeneratefreeCopy a character, location or prop from another production (cloned voices and consent stay).
upload_mediageneratefreeBring your own file into a production by https url (4 MB) or base64 (3 MB).
import_mediageneratespendsImport a YouTube, TikTok, Instagram, X, Facebook or Reddit video (≤10 min, 2 credits/min, rights confirmed).

Generate and edit

ToolScopeCreditsWhat it does
generate_imagegeneratespendsText or reference to image; takes aspect_ratio and resolution (e.g. 2K).
generate_videogeneratespendsText or image to video, priced per second.
generate_keyframes_videogeneratespends2-10 images pinned to times in a 5-20 s clip, animated between (FLUX 3 Max), priced per second.
generate_voicegeneratespendsText to speech: words in text, delivery in style_instruction; voice "narrator" or character "@slug".
generate_musicgeneratespendsMusic from a style prompt and/or lyrics.
edit_imagegeneratespendsEdit an image with an instruction ("make it night").
upscale_imagegeneratespendsUpscale an image 2x, 4x or 6x.
upscale_videogeneratespendsUpscale a video, priced per second.
enhance_audiogeneratespendsEnhance speech, denoise, or upscale audio to 48 kHz (audio or a video soundtrack).
generate_mediageneratespendsAny generator by kind: sfx, lipsync, sheets, shot framing, timeline export and more.
edit_mediageneratespendsAny editor by kind: clip, crop, merge, captions, isolate voice, enhance audio, reframe and more.

Jobs

ToolScopeCreditsWhat it does
get_jobreadfreeStatus of a job, or of any asset by its copied Library id: media_url when completed, cost once charged.
list_itemsreadfreeA production's media items, filterable by type, status, name or tag.
cancel_jobgeneratefreeCancel a pending or processing job and refund it.
get_idempotency_resultreadfreeWhat happened to a paid call sent with an idempotency_key.

Motion compositions

ToolScopeCreditsWhat it does
list_compositionsreadfreeMotion compositions, newest first, without their HTML.
get_compositionreadfreeOne composition with its HTML, size and duration.
render_compositionread + generatespendsRender to MP4 or WebM, or PNG stills at times_s (optionally transparent).
create_compositioncomposefreeNew composition: an empty canvas at an aspect, or a built-in template.
edit_compositioncomposefreeUp to 50 ops, all or nothing, with version check and dry_run.
list_composition_revisionsreadfreeA composition's version history, newest first.
revert_compositioncomposefreeRestore an earlier revision (added as a new revision).

Studio timelines

ToolScopeCreditsWhat it does
list_studiosreadfreeA production's Studio (video editor) timelines.
get_studioreadfreeA timeline as an outline (tracks -> items, captions, warnings) or in full, with its revision.
get_studio_itemreadfreeOne item as the editor's inspector shows it (timing, transform, mask, audio, grade, text…).
create_studiocomposefreeNew timeline at an aspect, optionally already assembled by ops (one revision).
edit_studiocomposefreeUp to 50 timeline ops, all or nothing, with base_revision, dry_run and a change summary.
export_studioread + generatespendsRender to MP4; dry_run prices it, max_credits caps it.
get_studio_exportreadfreeAn export's status, MP4 url, cost and loudness report.
list_studio_revisionsreadfreeA Studio timeline's version history: who (person or agent), what changed, when.
revert_studiocomposefreeRestore an earlier timeline revision (added as a new revision, so it can be undone).

Shotlists and takes

ToolScopeCreditsWhat it does
list_shotlistsreadfreeA production's shotlists (scene-by-scene shot plans).
get_shotlistreadfreeScenes and shots: framing, lens, camera move, dialogue, hero asset.
list_shot_takesreadfreeTakes per shot with each shot's hero; settles finished generations.
generate_shotgeneratespendsA take of a shot from its framing, lens, move, cast refs and the previous shot's hero; dry_run quotes.
match_previous_shotgeneratespendsA take that continues the previous shot's hero: same cast, wardrobe, light, location.
coverage_packgeneratespendsWide / medium / close-up / reverse / insert takes of one moment, one itemised quote.
match_scenegeneratespendsA scene's shots without a hero, in order, each matched to the one before; one quote; runs on the server.
review_takegeneratefreeApprove or reject a take with a note (owners, editors, reviewers).
set_hero_takegeneratefreePick a shot's hero take; its media goes onto the shot.
check_facesgeneratespendsSame-person check of an image/video against the production's character references (0.25 credits).
get_face_checkreadfreeFace-check results for outputs: verdict, score, per character, regenerations.
regenerate_mismatchgeneratespendsRe-run an output that failed its face check (new seed); dry_run quotes, max_credits caps.
set_face_check_modegeneratefreeAutomatic face checks: offflagauto_regenerate (max_attempts, max_credits).

Production stages (script to cut)

ToolScopeCreditsWhat it does
get_production_stagesreadfreeEach stage's count, newest rows and links, and the next step with the tool to call.
draft_pipelinegeneratefreeOne pitch drafts a linked script, storyboard and shotlist (about a minute, free).
list_storyboardsreadfreeA production's storyboards (a script's beats with reference frames).
get_storyboardreadfreeOne storyboard with its beats and frames.
create_storyboardgeneratefreeNew storyboard, usually from a script (script_id, beats).
update_storyboardgeneratefreeChange only the fields you send; beats replaces the list.
create_shotlistgeneratefreeNew shotlist with scenes and shots, linked to its script and storyboard.
add_shotsgeneratefreeAppend shots to a scene, or a new scene holding them.
update_shotgeneratefreeChange one shot's description, framing, camera, duration, source or dialogue.
remove_shotgeneratefreeRemove one shot (its takes stay in the library).
reorder_shotsgeneratefreeReorder the shots of a scene (full order, or move one).
list_shotboardsreadfreeShot boards (optional per-shot frame planning) with editor links.
get_shotboardreadfreeOne shot board's shots: prompts, first and last frames, chosen take.
promote_shotlistgeneratefreeCopy a shotlist's shots into a new shot board (optional, free).

Craft guides and checks (free)

ToolScopeCreditsWhat it does
list_guidesreadfreeEvery craft guide (model prompting, prompt rules, writing tasks, video motion) and the free checks.
get_model_guidereadfreeHow to prompt one model: its guide, hard facts and the cross-model rules. Call before first use.
get_craft_guidereadfreeAny craft guide by id or topic (scripts, shot lists, lyrics, social copy, prompt rules …).
get_video_motion_guidereadfreeMotion craft for video prompts: H3 settings, camera language, timed beats, text, long takes.
check_video_promptreadfreeLint a video prompt for its model (labels, dropped inputs, beats vs duration) before paying.
pack_multishotreadfreePack a scene of short shots into as few MiniMax H3 multi-shot takes as fit.
lint_multishotreadfreeCheck a hand-written H3 multi-shot prompt: shot numbers, cut times, speakers, dialogue tags.
motion_design_briefreadfreeA director's brief (personality, easing, timing, quality gate) before a Motion composition.
gsap_for_use_casereadfreeThe GSAP pattern, easing and snippet for an animation described in plain words.
motion_quality_checkreadfreeReview an animation (and lint custom GSAP) against the motion-quality checklist.
production_briefreadfreeSegments, assets per beat, durations and a QA gate for a whole cut (advert, explainer …).
production_qareadfreePre-render checklist for an assembled cut: hook, audio, captions, CTA, duration.
get_tool_helpreadfreeA tool's full description and input schema (tools/list carries the short form).

Search (ChatGPT shape)

ToolScopeCreditsWhat it does
searchreadfreeSearch productions, media, compositions, public templates and docs.
fetchreadfreeThe 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 1 for 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

ScopeAllowsTools
splice:readRead your productions, compositions, characters, locations, props, models and credit balancelist_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:generateGenerate and edit media, manage your productions and library, and spend your Splice creditsgenerate_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:composeCreate, 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.

  1. Make a production. create_production({fields: {title: "Rain Ramen", aspect_ratio: "9:16"}}) returns its production_id. Pass it on every later call.
  2. Bring your own files (optional). upload_media({production_id, url: "https://…/logo.png", name: "Logo"}) returns a media_url you can use as an input or a composition asset. Public https links up to 4 MB, or data_base64 up to 3 MB.
  3. Check prices. list_models({type: "video"}) and get_balance(). Tell the user the cost before a big run.
  4. Generate. generate_image({production_id, prompt, aspect_ratio: "9:16", idempotency_key}), then generate_video({production_id, prompt, first_frame_image: <the image's media_url>, duration: 5, idempotency_key}), and generate_voice / generate_music for sound. Each returns {job_id, production_id, status: "pending"} at once.
  5. Wait for results. get_job({job_id, production_id}) every 5 to 10 seconds until status is completed (read media_url) or failed (read error_message; failed jobs are refunded). Once charged, cost shows credits_charged, credits_refunded and credits_net.
  6. Compose titles and the cut. create_composition({title: "Rain Ramen opener", aspect: "9:16"}), then edit_composition({composition_id, version, ops: [{op: "add_clips", clips: [...]}]}) with the media URLs from step 5. Try dry_run: true first; pass the last version so you never overwrite the user's edits.
  7. Check, then render. render_composition({composition_id, production_id, output_format: "png", times_s: [1, 4]}) gives cheap stills to look at. Then render_composition({composition_id, production_id, output_format: "mp4"}) and poll get_job; the result has the MP4 media_url and an audio_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 shot
  • splice://guides/recipes/product-spot-from-a-photo: a 15-30 s product spot from one product photo
  • splice://guides/recipes/look-led-teaser: a teaser whose every shot follows a moodboard look
  • splice://guides/recipes/track-led-music-video: a music video cut to the sections of a track
  • splice://guides/recipes/link-to-vertical-clip: a captioned 9:16 clip from a video the user owns
  • splice://guides/recipes/landscape-to-vertical-cutdown: a vertical cutdown of a finished 16:9 cut
  • splice://guides/recipes/title-and-lower-thirds-pack: matching titles, lower-thirds and an end card
  • splice://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 search and fetch only (read and fetch).
  • search returns {results: [{id, title, url}]} and fetch returns {id, title, text, url, metadata}, over your productions, media items and Motion compositions plus public templates and docs. Ids look like production:…, composition:… or template:….
  • 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:generate and splice:compose (plus opt-in splice:produce for REST share links and transcription), rotating refresh tokens, any-port loopback redirects for native apps. 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. When you create one you choose its access, an optional expiry (30, 90 or 365 days) and an optional default production for calls without production_id:
AccessWhat the key can do
Full accessEverything the dashboard can do: generate, edit, Motion, buy credits with Solana, publish to Studio, share links.
CreateRead, generate and edit (spends credits), manage productions, Motion and Studio timelines. No credit purchases, Studio publishing or share links.
Read onlyList 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 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).

StatusCommon codesWhat to do
400invalid_request, invalid_bodyFix the request; details names the field
401unauthorizedSend a valid key or token (see Authentication)
402insufficient_credits, payment_requiredTop up, then retry with the same Idempotency-Key
403forbiddenThe key or token lacks the scope in details.required_scope
404not_foundThe id isn't the caller's, or doesn't exist
409conflict, idempotency_in_progress, idempotency_outcome_unknown, quote_exceeds_max_credits, version_conflictSee Idempotency, or re-read and retry
415 / 422unsupported_media_type, unprocessable_entitySend the content type and shape the route expects
429rate_limitedWait Retry-After seconds
501not_implemented and feature codes (cancel_unavailable, quote_unavailable)The feature is off; see features in the manifest
502 / 503 / 504upstream_error, service_unavailable, upstream_timeoutRetry 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 example Unknown 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 a warnings list 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 (see inputs in list_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-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). 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/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