Create a video on Blitframe
From nothing to an MP4 link in eight steps. MCP tools are written blitframe:<tool>; the same flow in curl is at the end. The blitframe skill has the model and the safety rules.
Blitframe does not design the video. You write the composition (data.json), and Blitframe renders it.
Steps
- Check what the workspace may render.
blitframe:get_usage(GET /usage).renderSecondsRemainingis the balance.limits.maxDurationSeconds,limits.maxLongEdgeandlimits.maxShortEdgecap one render. The free trial renders up to 30 seconds at up to 1280×720.limits.maxProjectBytescaps the files of one version together (100 MB on the free trial).noTrial: trueorplanEnded: truemeans the workspace cannot render until a plan starts. Stop and tell the user; do not try.- A video costs its length in seconds × 0.5 up to 1280×720, × 1 up to 1920×1080, chosen by pixel count (so 1080×1080 is × 1), rounded up. Larger sizes cost more: the table is in the
blitframe-renderskill.
- Pick a font from the library.
blitframe:list_fontswithq(GET /fonts?q=mont). Copy the font'sdeclarationintofonts.list, and use itsfNameas the text'sf. Never invent a font name. - Write
data.json. Start from the composition below. For anything it does not show, read theblitframe-data-jsonskill first. - Create the project.
blitframe:create_projectwithname(POST /projects). The answer'sidis the project; itsheadVersionIdisnulluntil the first edit. - Add the files.
blitframe:edit_project(POST /projects/{projectId}/versions) withfiles: [{ "path": "data.json", "content": "<the whole file as text>" }]. An image goes in the same edit as{ "path": "images/logo.png", "contentBase64": "..." }; a file over about 45 MB goes through an upload (theblitframeskill'sreferences/uploads.md). - Check the version.
renderablemust betrue. Otherwise fix every item inproblems(a missing font or file, a layer with nothing to draw) and edit again withexpectedHeadVersionIdset to the version you just made. - Preview one frame.
blitframe:renderwith the new version'sidasversionId,format: "frames"andframes: { "start": 60, "end": 61 }(endis exclusive), thenblitframe:get_renderwithwaitSeconds: 50. Over MCP, look at the image it returns. Over REST, downloadoutput.frameUrls[0]and look at that file. Pick a frame where everything is on screen. One frame costs 1 render second. - Render and hand over.
blitframe:renderwith the sameversionIdandformat: "mp4", thenblitframe:get_renderwithwaitSeconds: 50untilstatusissucceeded,failedorcancelled. Once it has succeeded, give the useroutput.mp4Url. The link lasts an hour.
A starter composition
Five seconds at 1280×720 and 30 frames a second: a dark background, a headline that fades in while it slides up, and an accent bar under it.
{
"v": "5.12.2", "nm": "Hello", "fr": 30, "ip": 0, "op": 150, "w": 1280, "h": 720, "ddd": 0,
"assets": [],
"fonts": { "list": [{ "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" }] },
"layers": [
{
"ty": 5, "ind": 1, "nm": "Headline", "ip": 0, "op": 150, "st": 0, "sr": 1,
"ks": {
"a": { "a": 0, "k": [0, 0, 0] }, "s": { "a": 0, "k": [100, 100, 100] }, "r": { "a": 0, "k": 0 },
"p": { "a": 1, "k": [
{ "t": 15, "s": [640, 400, 0], "i": { "x": 0.4, "y": 1 }, "o": { "x": 0.6, "y": 0 } },
{ "t": 45, "s": [640, 370, 0] }
] },
"o": { "a": 1, "k": [
{ "t": 15, "s": [0], "i": { "x": 0.4, "y": 1 }, "o": { "x": 0.6, "y": 0 } },
{ "t": 45, "s": [100] }
] }
},
"t": { "d": { "k": [{ "t": 0, "s": { "t": "Hello", "f": "Montserrat-Bold", "s": 96, "lh": 110, "ls": 0, "tr": 0, "j": 2, "fc": [1, 1, 1] } }] }, "a": [] }
},
{
"ty": 4, "ind": 2, "nm": "Accent", "ip": 0, "op": 150, "st": 0, "sr": 1,
"ks": {
"a": { "a": 0, "k": [0, 0, 0] }, "p": { "a": 0, "k": [640, 430, 0] }, "s": { "a": 0, "k": [100, 100, 100] },
"r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 }
},
"shapes": [{ "ty": "gr", "nm": "Bar", "it": [
{ "ty": "rc", "nm": "Rectangle", "d": 1, "p": { "a": 0, "k": [0, 0] }, "s": { "a": 0, "k": [160, 8] }, "r": { "a": 0, "k": 4 } },
{ "ty": "fl", "nm": "Fill", "r": 1, "c": { "a": 0, "k": [1, 0.75, 0.2, 1] }, "o": { "a": 0, "k": 100 } },
{ "ty": "tr", "p": { "a": 0, "k": [0, 0] }, "a": { "a": 0, "k": [0, 0] }, "s": { "a": 0, "k": [100, 100] }, "r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 }, "sk": { "a": 0, "k": 0 }, "sa": { "a": 0, "k": 0 } }
] }]
},
{
"ty": 1, "ind": 3, "nm": "Background", "ip": 0, "op": 150, "st": 0, "sr": 1, "sw": 1280, "sh": 720, "sc": "#101725",
"ks": {
"a": { "a": 0, "k": [0, 0, 0] }, "p": { "a": 0, "k": [0, 0, 0] }, "s": { "a": 0, "k": [100, 100, 100] },
"r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 }
}
}
]
}
How to change it:
- Font. Replace the
fonts.listentry with thedeclarationof the font you picked, and the text'sfwith itsfName. - Copy. The text is
t.d.k[0].s.t.sis the font size,lhthe line height,jthe alignment (0left,1right,2center) andfcthe fill color as RGB from 0 to 1. - Where text sits. A text layer's position is its baseline, not the middle of the letters: the letters stand on
yand rise above it.j: 2centers each line onx. - Where a shape sits. A rectangle whose own
pis[0, 0]is centered on its layer's position. A shape group lists its paths first, then the fill or stroke, then itstrtransform. - Motion. A keyframe is
{ "t": frame, "s": value }with its easing iniando; the next keyframe'ssis where the move ends, and the last keyframe holds. Write the easing'sxandyas plain numbers, on a position as on an opacity (lists with one number per component read the same). A one-number value is written[0]in a keyframe. - Length.
opis the frame after the last one: 150 frames atfr30 is 5 seconds. Change the composition'sopand every layer'soptogether, or the layers end early. - Size. Change
wandh(even numbers for MP4), the background'sswandsh, and the positions of the other layers. - Adding or reordering layers. Read the
blitframe-data-jsonskill first: stacking followsind(smaller is in front), never the array order, and every value keeps its{ "a": ..., "k": ... }wrapper.
The same flow with curl
Needs the BLITFRAME and BLITFRAME_API_KEY variables from the blitframe skill, and data.json in the current folder. The commands use jq, but any JSON tool builds the edit's body: the one requirement is that content holds the whole file as a single JSON string. Without jq, write the body with Node.js or Python and send it with -d @body.json:
node -e 'const fs = require("fs"); fs.writeFileSync("body.json", JSON.stringify({ message: "First version", files: [{ path: "data.json", content: fs.readFileSync("data.json", "utf8") }] }))'
auth="Authorization: Bearer $BLITFRAME_API_KEY"
json="Content-Type: application/json"
curl -s $BLITFRAME/usage -H "$auth" | jq '{renderSecondsRemaining, trial, planEnded, noTrial, limits}'
PROJECT_ID=$(curl -s -X POST $BLITFRAME/projects -H "$auth" -H "$json" -d '{"name":"Hello Blitframe"}' | jq -r .id)
VERSION=$(jq -n --rawfile composition data.json \
'{message: "First version", files: [{path: "data.json", content: $composition}]}' |
curl -s -X POST $BLITFRAME/projects/$PROJECT_ID/versions -H "$auth" -H "$json" -d @-)
echo "$VERSION" | jq '{id, renderable, problems, warnings}'
VERSION_ID=$(echo "$VERSION" | jq -r .id)
FRAME_ID=$(curl -s -X POST $BLITFRAME/renders -H "$auth" -H "$json" \
-d "{\"versionId\":\"$VERSION_ID\",\"format\":\"frames\",\"frames\":{\"start\":60,\"end\":61}}" | jq -r .id)
curl -s $BLITFRAME/renders/$FRAME_ID -H "$auth" -H "Prefer: wait=50" | jq -r '.output.frameUrls[0]' | xargs curl -s -o frame.png
Look at frame.png. Queue the MP4 only when the frame is right; it uses the variables set above:
RENDER_ID=$(curl -s -X POST $BLITFRAME/renders -H "$auth" -H "$json" \
-d "{\"versionId\":\"$VERSION_ID\",\"format\":\"mp4\"}" | jq -r .id)
curl -s $BLITFRAME/renders/$RENDER_ID -H "$auth" -H "Prefer: wait=50" | jq '{status, error, output}'
Repeat a GET /renders/{renderId} until status is succeeded, failed or cancelled.
When it does not work
| What you see | What to do |
|---|---|
renderable: false | Read problems. Fix each one in data.json or add the missing file, then edit again |
A font named in problems | Use a library font (blitframe:list_fonts), or add the font file in an edit (the blitframe-data-json skill, Fonts) |
403 plan_limit | The composition is longer or larger than the plan allows. Make it smaller or shorter, or tell the user what the message says |
403 project_too_large | An upload, edit, ZIP import, copy or variation would make a version's files total more than the plan allows (limits.maxProjectBytes). A ZIP is checked at import; its upload is refused only when it is too large to import over any head. Remove or shrink files, or tell the user a larger plan allows larger projects. Do not retry |
402 insufficient_render_seconds | Tell the user what the message says. Do not retry |
422 version_not_renderable | The version has problems, its files total more than 8 GB, a video was asked of an odd width or height, or what the render writes alone needs more than 40 GB (choose a lower quality or make it shorter). The message says which |
The render failed | error.code says why (the blitframe-render skill). Fix the version and render again. After interrupted, just render again; when its message names a missing file, add that file again with an edit first |
The full walkthrough in curl, Python, Node.js, PHP, Ruby, Go, C# and Java: https://codeartworks.com/docs/blitframe/quickstart.md.