Edit video from your code.
The MotionFizz engine runs in the MotionFizz app on your computer. Your program opens a project, makes edits, saves a new version and renders it, through one small HTTP API.
Quick start
Four steps from nothing to a rendered video. You need Windows, the MotionFizz app and Pro: the API is part of Pro, and of the 14-day free trial.
Install MotionFizz for Windows and sign in
The engine comes with the desktop app. Sign in with a Pro account, or sign in to start the 14-day free trial. The app keeps running in the tray when you close the window, and the tray menu shows Engine running (127.0.0.1:47321).
Make a key
In the app, on Home, click Engine and API keys. Type a name for your program, add a webhook address if you want one, and click Make a key. Copy the key: it starts with
mfe_and is shown once. Keep it in your program's settings or.env, never in your code. A computer can have keys for 2 programs; revoke one to make another.Make your first call
Every call is a
POSTtohttp://127.0.0.1:47321/v1/<call>with a JSON body and your key.curl -X POST http://127.0.0.1:47321/v1/engine.status \ -H "Authorization: Bearer $MOTIONFIZZ_KEY" \ -H "Content-Type: application/json" -d "{}"$h = @{ Authorization = "Bearer $env:MOTIONFIZZ_KEY" } Invoke-RestMethod -Method Post -Uri http://127.0.0.1:47321/v1/engine.status ` -Headers $h -ContentType "application/json" -Body "{}"The answer always has
ok. Withok: truethe data is inresult; withok: falseit is inerror. Without Pro on the computer,engine.statusstill answers, and every other call says how to get Pro.{ "ok": true, "result": { "engine": "0.1.0", "projects": 0, "renderer": true, "caller": "my-tool", "plan": { "tier": "pro", "account": "you@example.com" } } }Edit, save and render
This script makes a 9:16 project, adds a background and an animated title, saves version 2 and renders it. Copy it, set
MOTIONFIZZ_KEY, run it.// Node 18 or newer. Run: MOTIONFIZZ_KEY=mfe_... node quickstart.mjs const KEY = process.env.MOTIONFIZZ_KEY; const BASE = process.env.MOTIONFIZZ_URL ?? 'http://127.0.0.1:47321'; async function mf(call, params = {}) { const res = await fetch(`${BASE}/v1/${call}`, { method: 'POST', headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(params), }); const body = await res.json(); if (!body.ok) throw new Error(`${call}: ${body.error.code} (${res.status}): ${body.error.message}`); return body.result; } // 1. a new 9:16 project (saved as version 1) const { project, version } = await mf('projects.create', { name: 'Summer sale', aspect: '9:16' }); // 2. open it and edit: a background and a title, as one step const { session } = await mf('session.open', { project }); const { results } = await mf('session.apply', { session, ops: [ { name: 'add_shape', input: { kind: 'rect', width: 1080, height: 1920, color: '#0d0b1a', durationMs: 6000 } }, { name: 'add_text', input: { content: 'Big summer sale', fontSize: 140, fontWeight: 800, color: '#ffffff', durationMs: 6000 } }, ], }); const title = results[1].layerId; // 3. animate the title: words pop in, then a slow push-in await mf('session.apply', { session, ops: [ { name: 'set_text_animation', input: { layerId: title, preset: 'in-pop-word' } }, { name: 'set_property', input: { layerId: title, property: 'scale', value: { x: 1, y: 1 }, atMs: 0 } }, { name: 'set_property', input: { layerId: title, property: 'scale', value: { x: 1.15, y: 1.15 }, atMs: 6000 } }, ], }); // 4. save it as version 2 (made from version 1) const saved = await mf('session.save', { session, note: 'Title and background', baseVersion: version }); console.log(`Saved v${saved.version}:`, saved.changes.join('; ')); await mf('session.close', { session }); // 5. render it and wait const { job } = await mf('render.start', { project, version: saved.version, preset: 'mp4-1080-9x16', expectedDurationMs: 6000 }); for (;;) { const j = await mf('jobs.get', { job }); if (['done', 'held', 'failed', 'cancelled'].includes(j.status)) { console.log(j.status, j.result?.file ?? j.error ?? ''); break; } console.log(`${j.status} ${Math.round(j.progress * 100)}%`); await new Promise((r) => setTimeout(r, 2000)); }# Python 3.8 or newer, no packages needed. Run: MOTIONFIZZ_KEY=mfe_... python3 quickstart.py import json, os, time, urllib.error, urllib.request KEY = os.environ["MOTIONFIZZ_KEY"] BASE = os.environ.get("MOTIONFIZZ_URL", "http://127.0.0.1:47321") def mf(call, **params): req = urllib.request.Request(f"{BASE}/v1/{call}", data=json.dumps(params).encode(), method="POST", headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}) try: with urllib.request.urlopen(req) as res: body = json.load(res) except urllib.error.HTTPError as e: body = json.load(e) if not body["ok"]: raise RuntimeError(f"{call}: {body['error']['code']}: {body['error']['message']}") return body["result"] p = mf("projects.create", name="Summer sale", aspect="9:16") s = mf("session.open", project=p["project"])["session"] r = mf("session.apply", session=s, ops=[ {"name": "add_shape", "input": {"kind": "rect", "width": 1080, "height": 1920, "color": "#0d0b1a", "durationMs": 6000}}, {"name": "add_text", "input": {"content": "Big summer sale", "fontSize": 140, "fontWeight": 800, "color": "#ffffff", "durationMs": 6000}}, ]) title = r["results"][1]["layerId"] mf("session.apply", session=s, ops=[{"name": "set_text_animation", "input": {"layerId": title, "preset": "in-pop-word"}}]) saved = mf("session.save", session=s, note="Title and background", baseVersion=p["version"]) print(f"Saved v{saved['version']}:", "; ".join(saved["changes"])) mf("session.close", session=s) job = mf("render.start", project=p["project"], version=saved["version"], preset="mp4-1080-9x16")["job"] while True: j = mf("jobs.get", job=job) if j["status"] in ("done", "held", "failed", "cancelled"): print(j["status"], (j.get("result") or {}).get("file") or j.get("error", "")) break print(j["status"], f"{round(j['progress'] * 100)}%") time.sleep(2)
How it works
Projects are kept as numbered versions. You edit a version in a session and save the result as the next version. Nothing is ever overwritten.
session.opensession.applysession.save → v N+1render.start → jobs.get- Versions. Each save writes
<slug>_v3.mofnext to v1 and v2 inDocuments\MotionFizz\projects\<slug>, with who made it, your note and the changes in plain words. Restoring v1 saves it again as v4. - baseVersion. A save names the version it was made from. If someone saved a newer one meanwhile, yours is refused with
409 stale, never merged. - All or nothing.
session.applyruns its operations in order. If one fails, none of them land, and the error says which step. - Same file as the app. A
.moffile opens in MotionFizz on any computer. Media are stored once, by content hash. - madeBy. Pass
"madeBy": "order #482"and the version shows as made by order #482 (via your key's name).
{
"session": "ses_mws3z5g5q9gu2",
"ops": [
{ "name": "add_shape", "input": { "kind": "rect", "width": 1080, "height": 1920, "color": "#0d0b1a", "durationMs": 6000 } },
{ "name": "add_text", "input": { "content": "Big summer sale", "fontSize": 140, "fontWeight": 800, "color": "#ffffff", "durationMs": 6000 } }
]
}{ "ok": true, "result": { "ok": true, "results": [ { "layerId": "lyr_mws3z8houxgm3" }, { "layerId": "lyr_mws3z8hxrq7s5" } ], "unsavedChanges": true } }Each operation's result comes back in results, in order. Use a layerId it returns in your next call.
{ "ok": true, "result": {
"version": 2,
"mofHash": "f95bc3e57fbf03e1dd89afb17e6b571843f5289128a3e213a4897a21f6d7b623",
"changes": ["Length 0:00 → 0:06", "Added shape layer \"Rect\"", "Added text layer \"Big summer sale\""],
"note": "Title and background",
"file": "launch-promo_v2.mof"
} }HTTP 409
{ "ok": false, "error": { "code": "stale", "message": "This session is on version 2, not 1." } }Every call
POST /v1/<call>, JSON in and out, Authorization: Bearer mfe_… on every call. A ? marks a param you can leave out.
| Call | Send | Does |
|---|---|---|
| Engine | ||
engine.status | — | Engine version, plan, whether renders are available, the presets, your key's name |
engine.operations | — | Every editing operation with its JSON Schema |
engine.schema | — | The JSON Schema of a project |
GET /v1/health | — | No key needed: is the engine up |
| Projects | ||
projects.list | — | Projects with their newest version |
projects.get | project | Every version (who, note, changes, hash) and every render |
projects.create | name, aspect (16:9, 9:16, 1:1, 4:5…), madeBy? | A new project, saved as version 1 |
projects.import | path or base64, note? | A .mof file from the app: version 1, or the next version of a project it already has |
projects.export | project, version? | That version with its media inside, ready to open in the app anywhere |
| Sessions | ||
session.open | project, version? | Opens a version for editing (newest by default); returns a session id |
session.describe | session | The tracks and layers, with their ids |
session.apply | session, ops: [{ name, input }] | Runs editing operations in order, all or nothing |
session.undo | session | Undoes the last apply |
session.validate | session | Missing media or fonts, text off the frame, broken mattes and parents |
session.preview | session, atMs, width | One frame as a PNG (base64) |
session.save | session, note, baseVersion, madeBy? | Writes the next version; returns its number, hash and changes |
session.close | session | Closes it; unsaved changes are dropped |
| Media | ||
media.import | session, path or base64, name?, placeOnTimeline?, atMs? | Adds a picture, video, sound, font or LUT to the project |
media.upload | ?session=&name=&atMs= with the file as the body | The same, for big files (up to 8 GB) |
| Versions | ||
versions.get | project, version? | A version's whole project |
versions.save | project (the whole JSON), baseVersion, note | A project changed elsewhere, saved as the next version |
versions.diff | project, a, b | What changed between two versions, in plain words |
versions.restore | project, version, baseVersion | Saves an older version again as the newest |
| Renders | ||
render.start | project, version?, preset?, expectedDurationMs?, loudnessTarget?, withoutPro? | Queues a render; returns a job id |
jobs.get | job | Status, progress 0–1 and, when done, the file, its hash, proofs and checks |
jobs.list | project? | The last 200 jobs |
jobs.cancel | job | Stops a job; nothing half-made is left |
renders.proof | project, version, kind (contact or poster) | A version's contact sheet or poster frame as a PNG |
Send big files with media.upload: the file is the request body, the rest goes in the address.
curl -X POST "http://127.0.0.1:47321/v1/media.upload?session=ses_mws3z5g5q9gu2&name=logo.png&atMs=1000" \
-H "Authorization: Bearer $MOTIONFIZZ_KEY" --data-binary @logo.pngEditing operations
session.apply runs the same 79 operations as the MotionFizz app and its Claude and ChatGPT connector. engine.operations returns each one with its description and JSON Schema.
Look before you change
describe_project list_animatable_properties list_options media_usage
Layers
add_text update_text add_shape update_shape add_null add_adjustment_layer update_layer duplicate_layer split_layer delete_layers set_parent make_compound_clip break_compound_clip rename_compound_clip
Animation
set_property remove_keyframes move_keyframe set_keyframe_ease apply_animation_preset set_text_animation set_expression set_speed
Shapes, paint and masks
convert_to_path set_path set_paint add_path_effect update_path_effect remove_path_effect add_mask set_mask_shape update_mask remove_mask set_track_matte
3D
make_three_d add_three_d_object add_camera
Tracking
track_motion pin_to_track corner_pin follow_track mask_follow_track remove_track
Effects, colour and transitions
add_effect update_effect remove_effect set_colour set_transition recolour_with_palette palette_from_colour apply_brand_fonts
Sound
set_sound set_sound_part normalize_sound clean_up_sound separate_voice_and_music sync_by_sound link_clips
Words and captions
get_transcript clear_transcript cut_words remove_filler_words shorten_pauses captions_from_transcript style_captions
Ready-made graphics
insert_graphic set_graphic_controls make_graphic edit_graphic_control detach_graphic
The whole project
set_composition set_guides set_track_switches add_marker auto_edit reduce_project
- Times are milliseconds from the start of the video, positions are pixels from the top-left, scale 1 means 100%.
set_propertyanimates anything: giveatMsto make a keyframe. Words, choices and switches hold until the next keyframe.list_optionslists the ready-made graphics, animation presets, effects, transitions and fonts by id.delete_layersremoves layers from the timeline of the open session. It never deletes a file or a saved version.
Renders
Renders are drawn by the app's own drawing code, on your computer's GPU, so they match what the app shows. One runs at a time; the queue survives a restart.
| Preset | File |
|---|---|
mp4-1080 | H.264 MP4, the project's own shape |
mp4-720 | H.264 MP4, 720p |
mp4-1080-16x9 · -9x16 · -1x1 · -4x5 | The same version reframed to that shape |
h265-1080 | H.265 MP4 (where the computer can encode it) |
wav · mp3 | Sound only |
mp4-4k · h265-4k | 4K |
webm-alpha-1080 | VP9 WebM with transparency |
prores-4444-1080 · prores-4444-4k | ProRes 4444 with transparency, for editing software |
png-sequence | A zip of PNG frames |
gif-480 | Animated GIF |
- Files land next to the version:
launch-promo_v2.mp4,launch-promo_v2_9x16.mp4. With each version's first render come_poster.png,_contact.png(a frame every 2 seconds) and_480p.mp4. - Every render is checked: no black frames, no frozen video, text inside title-safe, loudness at
loudnessTarget(default −14 LUFS, ±2), and the length you gave inexpectedDurationMs. A render that fails a check isheld, notdone: the file is there for someone to look at. - Renders follow the plan of the account signed in to MotionFizz on that computer. With Pro, every preset and every feature renders. When Pro ends, the API stops answering until the computer is on Pro again.
- Statuses:
queued,running,done,held,failed,cancelled. Polljobs.get, or let a webhook tell you.
Webhooks
Give your key a webhook address and the engine tells you when a version is saved or a render finishes. Each delivery is signed with a secret (mfw_…) shown once when you set the address.
version.savedgoes to every key with a webhook, whoever saved: the app, a chat or another program.job.finishedgoes to the key that started the render.- Addresses:
https://anywhere, orhttp://to127.0.0.1andlocalhostonly. Each delivery is tried 3 times (again after 2 and 4 seconds). Answer with any 2xx.
| Header | What it holds |
|---|---|
X-MotionFizz-Event | version.saved or job.finished |
X-MotionFizz-Delivery | An id for this delivery; the same id if it is sent again |
X-MotionFizz-Timestamp | Seconds since 1970 |
X-MotionFizz-Signature | sha256= and the hex HMAC-SHA256 of "timestamp.body", made with your webhook secret |
POST /your/webhook
X-MotionFizz-Event: job.finished
X-MotionFizz-Delivery: aec44017-24cb-4c94-9276-10129f6dd5d5
X-MotionFizz-Timestamp: 1795368428
X-MotionFizz-Signature: sha256=6c1f…
{ "id": "aec44017-…", "event": "job.finished", "at": "2026-11-22T17:27:08.419Z",
"job": { "id": "job_mws3zcitke817", "status": "done", "project": "prj_mws3yrto3wty0", "version": 2,
"preset": "mp4-1080-9x16",
"result": { "file": "launch-promo_v2_9x16.mp4", "path": "C:\Users\you\Documents\MotionFizz\projects\launch-promo\launch-promo_v2_9x16.mp4",
"hash": "…", "durationMs": 6000,
"width": 1080, "height": 1920, "bytes": 2481152, "proofs": { … }, "checks": [ … ] } } }Check the signature before you trust a delivery. Use the raw body, exactly as received:
// Node: check a MotionFizz webhook before trusting it. Run: MOTIONFIZZ_WEBHOOK_SECRET=mfw_... node verify-webhook.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
const SECRET = process.env.MOTIONFIZZ_WEBHOOK_SECRET;
function verify(headers, rawBody) {
const ts = headers['x-motionfizz-timestamp'];
const sig = headers['x-motionfizz-signature'] ?? '';
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes: refuse
const want = 'sha256=' + createHmac('sha256', SECRET).update(`${ts}.${rawBody}`).digest('hex');
return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}
createServer((req, res) => {
let raw = '';
req.on('data', (c) => (raw += c));
req.on('end', () => {
if (!verify(req.headers, raw)) { res.writeHead(401).end(); return; }
const event = JSON.parse(raw);
console.log(event.event, event.project?.name ?? event.job?.id, event.version?.number ?? event.job?.status);
res.writeHead(200).end(); // answer 2xx quickly; do the work afterwards
});
}).listen(9911, '127.0.0.1');# Python: the same check, for any framework. raw_body is the request body exactly as received (bytes).
import hashlib, hmac, os, time
SECRET = os.environ["MOTIONFIZZ_WEBHOOK_SECRET"].encode()
def verify(headers, raw_body: bytes) -> bool:
ts = headers.get("X-MotionFizz-Timestamp", "")
sig = headers.get("X-MotionFizz-Signature", "")
if not ts or abs(time.time() - int(ts)) > 300:
return False
want = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(sig, want)Errors and limits
Every error has a code to act on and a message written for people.
| Code | HTTP | Means |
|---|---|---|
invalid | 422 | The params or an operation's input are wrong. The message names the field. |
missing_media | 422 | A media file the version needs is not on this computer. |
forbidden | 401 / 403 | No key or a revoked key (401); a request from a web page, or a computer without Pro (403). |
not_found | 404 | No such call, project, version, session or job. |
stale | 409 | A newer version exists than your baseVersion. Open it and make the change again. |
limit | 429 | Too big or too many: 64 MB JSON, 8 GB upload, 50 open sessions, 2-hour projects, 2 programs per computer. |
busy | 503 | Pictures, renders and reading video need the MotionFizz app running as the engine. |
Safety
This computer only
The engine listens on 127.0.0.1. Programs on other computers can't reach it, and requests from web pages (with an Origin header) are refused.
A key per program
Up to 2 programs on a computer. The engine keeps only a hash of each key. Revoke one in the app and it stops at once, even mid-job.
Nothing deleted
There is no call that deletes or overwrites a project, a version or a media file. A version file changed on disk is refused.
Everything logged
Every call is logged with the key's name, the project and the version, never the key itself. The app shows it under Recent activity.
Claude and ChatGPT
People who'd rather ask than code can connect their AI app instead. No key, no setup file. Like the API, it is part of Pro and of the 14-day free trial.
In Claude or ChatGPT, add a custom connector with this address:
https://mcp.motionfizz.com/mcpSign in with your MotionFizz account (Pro, or on the free trial) and press Allow.
Ask for edits in plain words. They land live in the project you have open, on the web, Windows or your phone, and each one can be undone.
With the Windows app open, a chat can also open, edit, save and render versions on that computer. It can't delete anything or send a video anywhere.
Build something that moves.
Questions or a call you're missing? Write to support@motionfizz.com.