Developers

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.

79editing operations
16render presets
0calls that delete
14days free to try

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.

  1. 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).

  2. 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.

  3. Make your first call

    Every call is a POST to http://127.0.0.1:47321/v1/<call> with a JSON body and your key.

    bash
    curl -X POST http://127.0.0.1:47321/v1/engine.status \
      -H "Authorization: Bearer $MOTIONFIZZ_KEY" \
      -H "Content-Type: application/json" -d "{}"

    The answer always has ok. With ok: true the data is in result; with ok: false it is in error. Without Pro on the computer, engine.status still answers, and every other call says how to get Pro.

    answer (shortened)
    {
      "ok": true,
      "result": {
        "engine": "0.1.0",
        "projects": 0,
        "renderer": true,
        "caller": "my-tool",
        "plan": { "tier": "pro", "account": "you@example.com" }
      }
    }
  4. 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.

    JavaScript · Node 18+
    // 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));
    }

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.

opensession.open
editsession.apply
savesession.save → v N+1
renderrender.start → jobs.get
  • Versions. Each save writes <slug>_v3.mof next to v1 and v2 in Documents\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.apply runs its operations in order. If one fails, none of them land, and the error says which step.
  • Same file as the app. A .mof file 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.apply
{
  "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 } }
  ]
}
answer
{ "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.

session.save → answer
{ "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"
} }
the same save again, from version 1
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.

CallSendDoes
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.getprojectEvery version (who, note, changes, hash) and every render
projects.createname, aspect (16:9, 9:16, 1:1, 4:5…), madeBy?A new project, saved as version 1
projects.importpath or base64, note?A .mof file from the app: version 1, or the next version of a project it already has
projects.exportproject, version?That version with its media inside, ready to open in the app anywhere
Sessions
session.openproject, version?Opens a version for editing (newest by default); returns a session id
session.describesessionThe tracks and layers, with their ids
session.applysession, ops: [{ name, input }]Runs editing operations in order, all or nothing
session.undosessionUndoes the last apply
session.validatesessionMissing media or fonts, text off the frame, broken mattes and parents
session.previewsession, atMs, widthOne frame as a PNG (base64)
session.savesession, note, baseVersion, madeBy?Writes the next version; returns its number, hash and changes
session.closesessionCloses it; unsaved changes are dropped
Media
media.importsession, 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 bodyThe same, for big files (up to 8 GB)
Versions
versions.getproject, version?A version's whole project
versions.saveproject (the whole JSON), baseVersion, noteA project changed elsewhere, saved as the next version
versions.diffproject, a, bWhat changed between two versions, in plain words
versions.restoreproject, version, baseVersionSaves an older version again as the newest
Renders
render.startproject, version?, preset?, expectedDurationMs?, loudnessTarget?, withoutPro?Queues a render; returns a job id
jobs.getjobStatus, progress 0–1 and, when done, the file, its hash, proofs and checks
jobs.listproject?The last 200 jobs
jobs.canceljobStops a job; nothing half-made is left
renders.proofproject, 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.

media.upload
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.png

Editing 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_property animates anything: give atMs to make a keyframe. Words, choices and switches hold until the next keyframe.
  • list_options lists the ready-made graphics, animation presets, effects, transitions and fonts by id.
  • delete_layers removes 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.

PresetFile
mp4-1080H.264 MP4, the project's own shape
mp4-720H.264 MP4, 720p
mp4-1080-16x9 · -9x16 · -1x1 · -4x5The same version reframed to that shape
h265-1080H.265 MP4 (where the computer can encode it)
wav · mp3Sound only
mp4-4k · h265-4k4K
webm-alpha-1080VP9 WebM with transparency
prores-4444-1080 · prores-4444-4kProRes 4444 with transparency, for editing software
png-sequenceA zip of PNG frames
gif-480Animated 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 in expectedDurationMs. A render that fails a check is held, not done: 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. Poll jobs.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.saved goes to every key with a webhook, whoever saved: the app, a chat or another program. job.finished goes to the key that started the render.
  • Addresses: https:// anywhere, or http:// to 127.0.0.1 and localhost only. Each delivery is tried 3 times (again after 2 and 4 seconds). Answer with any 2xx.
HeaderWhat it holds
X-MotionFizz-Eventversion.saved or job.finished
X-MotionFizz-DeliveryAn id for this delivery; the same id if it is sent again
X-MotionFizz-TimestampSeconds since 1970
X-MotionFizz-Signaturesha256= and the hex HMAC-SHA256 of "timestamp.body", made with your webhook secret
a delivery (values shortened)
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:

JavaScript · Node 18+
// 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');

Errors and limits

Every error has a code to act on and a message written for people.

CodeHTTPMeans
invalid422The params or an operation's input are wrong. The message names the field.
missing_media422A media file the version needs is not on this computer.
forbidden401 / 403No key or a revoked key (401); a request from a web page, or a computer without Pro (403).
not_found404No such call, project, version, session or job.
stale409A newer version exists than your baseVersion. Open it and make the change again.
limit429Too big or too many: 64 MB JSON, 8 GB upload, 50 open sessions, 2-hour projects, 2 programs per computer.
busy503Pictures, 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.

  1. In Claude or ChatGPT, add a custom connector with this address: https://mcp.motionfizz.com/mcp

  2. Sign in with your MotionFizz account (Pro, or on the free trial) and press Allow.

  3. 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.