Guides
Templates & fonts
Your design system, as data. A template says where text and media go, in which fonts and colours, and how it moves. Lokki fills it per market with the localized text and renders a 1080×1920 mp4. The dashboard preview and the final render use the same drawing engine, so what you see is what gets posted.
Concepts#
- Slots are the inputs:
textslots (localized per market) andmediaslots (images/videos shared by all markets). A post fills them withfieldsandmedia. - Scenes play in order; each has a
duration(seconds), abackgroundandlayersdrawn bottom to top. - Layers are
text,imageorshape. Text layers point at a slot (slot: "hook") or have statictextwith{{slot}}interpolation. - Coordinates (
x,y,w,h) are fractions of the canvas (0..1), so a template works at any resolution. Font sizes are px at a 1080 px wide canvas. - Timing:
start/end(seconds from scene start) andanimation.in/outper layer;transitionper scene (cut,fade,slide). - Versioning: updating a template's
specbumpsversion. System templates (tpl_sys_…) are read-only — duplicate them to customise.
Brand tokens#
Reference the brand kit instead of hard-coding values, and one template serves every brand and campaign. Set the kit with PATCH /brand.
| Token | Resolves to |
|---|---|
brand.primary brand.secondary brand.accent | Brand colours |
brand.text brand.background | Default text and background colours |
brand.on-primary (also on-secondary, …) | Black or white — whichever reads best on that brand colour |
brand.primary/0.8, #000000/0.5 | Alpha suffix on tokens and hex colours |
brand.heading brand.body | Font families from the brand kit (fonts.heading / fonts.body) |
src: "brand.logo" (image layer) | The brand logo (logo_asset_id) |
Literal colours may be #RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), transparent, white or black.
Text that fits in every language#
German and French often run 30% longer than English. Three tools keep layouts intact:
font.autoFit: trueshrinks the text until it fits the layer box — never belowfont.minSize. Combine withfont.maxLines.maxCharson a text slot is a hard limit checked after localization; an over-long translation becomes a blocking text check (the localizer is told the limit too).hinton a text slot guides the localizer ("max 6 words, a question").
Extra typographic touches: wrap words in *asterisks* to draw them in highlightColor; plate draws a caption box behind the text (mode: \"lines\" = one box per line); balance evens out line lengths; uppercase is locale-aware (Turkish İ).
Safe zone#
TikTok draws its UI over the video. Keep text inside the safe area (fractions of the canvas):
| Edge | Keep clear | Why |
|---|---|---|
| top | 0.08 (8%) | Top navigation tabs, search |
| bottom | 0.2 (20%) | Caption, music ticker |
| left | 0.06 (6%) | Margin |
| right | 0.16 (16%) | Like / comment / share buttons |
So a full-width text box is roughly x: 0.06, w: 0.78, between y: 0.08 and y: 0.80.
Fonts#
Upload your own fonts — one file per weight and style — then use the family name in templates or in the brand kit. Family, weight and style are guessed from the filename (AcmeSans-SemiBoldItalic.otf → Acme Sans, 600, italic) unless you pass them.
curl -X POST "https://uselokki.com/api/v1/fonts" -H "Authorization: Bearer $LOKKI_KEY" \
-F file=@AcmeSans-Bold.otf -F family="Acme Sans" -F weight=700 -F style=normal
curl "https://uselokki.com/api/v1/fonts" -H "Authorization: Bearer $LOKKI_KEY" # built-in + yours- Formats:
.ttf,.otf,.woff,.woff2. Make sure your licence allows embedding in videos. - Upload every weight and style you reference in templates (e.g. 400 for body, 700/800 for hooks).
- Check coverage for your markets' scripts (Polish, Czech, Turkish need Latin Extended glyphs).
- Built-in families:
Inter,Anton,Bebas Neue,Montserrat,Poppins,Playfair Display,Archivo Black,Permanent Marker,Space Grotesk,DM Serif Display.
Each font has a file URL (/api/fonts/:id/file) for browser previews; built-in fonts are public, yours need your workspace's auth.
Full example#
A two-scene template: a hook over the photo/clip, then body text on caption plates with a call-to-action pill and the logo.
{
"version": 1,
"width": 1080,
"height": 1920,
"fps": 30,
"slots": [
{
"key": "hook",
"type": "text",
"label": "Hook",
"required": true,
"maxChars": 48,
"hint": "Max 6 words, a question or a bold claim"
},
{
"key": "body",
"type": "text",
"label": "Body",
"maxChars": 120,
"multiline": true
},
{
"key": "cta",
"type": "text",
"label": "Call to action",
"default": "Link in bio"
},
{
"key": "bg",
"type": "media",
"label": "Background",
"accept": [
"image",
"video"
],
"required": true
}
],
"scenes": [
{
"id": "intro",
"duration": 3,
"background": {
"type": "media",
"slot": "bg",
"fit": "cover",
"kenBurns": true,
"dim": 0.25
},
"layers": [
{
"id": "hook",
"type": "text",
"slot": "hook",
"x": 0.08,
"y": 0.3,
"w": 0.76,
"h": 0.25,
"font": {
"family": "brand.heading",
"size": 110,
"uppercase": true,
"autoFit": true,
"minSize": 64,
"maxLines": 3
},
"color": "brand.text",
"align": "center",
"valign": "middle",
"highlightColor": "brand.primary",
"animation": {
"in": "pop",
"out": "fade"
}
}
]
},
{
"id": "body",
"duration": 4,
"transition": "fade",
"background": {
"type": "media",
"slot": "bg",
"fit": "cover",
"dim": 0.45
},
"layers": [
{
"id": "body",
"type": "text",
"slot": "body",
"x": 0.08,
"y": 0.4,
"w": 0.76,
"h": 0.3,
"font": {
"family": "brand.body",
"size": 60,
"weight": 600,
"autoFit": true,
"minSize": 40
},
"color": "#FFFFFF",
"align": "center",
"plate": {
"color": "rgba(0,0,0,0.55)",
"radius": 18,
"padX": 24,
"padY": 12,
"mode": "lines"
},
"animation": {
"in": "slide-up"
}
},
{
"id": "cta",
"type": "text",
"slot": "cta",
"x": 0.15,
"y": 0.72,
"w": 0.6,
"h": 0.07,
"font": {
"family": "brand.heading",
"size": 54
},
"color": "#000000",
"align": "center",
"plate": {
"color": "brand.secondary",
"radius": 40,
"padX": 32,
"padY": 14
},
"start": 1.2,
"animation": {
"in": "zoom"
}
},
{
"id": "logo",
"type": "image",
"src": "brand.logo",
"x": 0.4,
"y": 0.1,
"w": 0.2,
"h": 0.08,
"fit": "contain"
}
]
}
]
}curl -X POST "https://uselokki.com/api/v1/templates" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Bold hook\", \"spec\": $(cat spec.json)}"A post for this template then sends fields: { hook, body, cta } and media: { bg }. Unknown slot keys are rejected with 400, so typos never silently disappear.
Validation
Invalid specs return400 with details listing each problem (unknown layer type, a layer pointing at a missing slot, …). Iterate with the dashboard's template editor: it previews any spec live.Spec reference#
Generated from the API's schema, which is type-checked against the renderer's types. Slot = TextSlot | MediaSlot; Layer = TextLayer | ImageLayer | ShapeLayer (discriminated by type). Every layer also has id, x, y, w, h, start, end, opacity, rotation and animation.
TemplateSpec
A video template. Coordinates are fractions of the canvas, font sizes are px at 1080 wide.
| Field | Type | Description |
|---|---|---|
| versionrequired | 1 | |
| widthrequired | integer | Canvas width in px, normally 1080> 0 |
| heightrequired | integer | Canvas height in px, normally 1920 (9:16)> 0 |
| fpsrequired | integer | Frames per second, normally 30> 0 |
| slotsrequired | Slot[] | Inputs a post fills in |
| scenesrequired | Scene[] | Played in order; total duration = sum of scene durationsmin 1 items |
| audioSlot | string | Media slot key for background music (must be licensed for commercial use) |
TextSlot
A text input of the template. Its value comes from the post (source) and is localized per market.
| Field | Type | Description |
|---|---|---|
| keyrequired | string | Slot key used in post fields, e.g. "hook", "line1", "cta" |
| typerequired | "text" | |
| labelrequired | string | Human label shown in the composer and in errors |
| required | boolean | Post creation fails when empty |
| maxChars | integer | Hard limit checked after localization; an over-long translation blocks approval> 0 |
| multiline | boolean | Allow line breaks |
| translate | boolean | Default true. false keeps the source text in every market (codes, brand names) |
| default | string | Used when the post leaves the slot empty |
| hint | string | Guidance for the AI localizer, e.g. "short punchy hook, max 6 words" |
| samples | map<string, string> | Example text per language code ("en", "de", …) used for previews |
MediaSlot
An image or video input of the template. Media is shared by all markets.
| Field | Type | Description |
|---|---|---|
| keyrequired | string | Slot key used in post media, e.g. "bg1", "product" |
| typerequired | "media" | |
| labelrequired | string | |
| acceptrequired | "image" | "video"[] | Which asset kinds fit this slot |
| required | boolean |
Scene
| Field | Type | Description |
|---|---|---|
| idrequired | string | |
| durationrequired | number | Seconds> 0 |
| backgroundrequired | Background | |
| layersrequired | Layer[] | Drawn in order (first = bottom) |
| transition | "cut" | "fade" | "slide" | How this scene enters from the previous one (ignored on the first). Default cut, lasts 0.35 s |
Background
Scene background: a colour, a gradient, or a media slot.
type: "color"
| Field | Type | Description |
|---|---|---|
| typerequired | "color" | |
| colorrequired | string | Literal colour (#RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), "transparent", "white", "black"), a brand token ("brand.primary", "brand.secondary", "brand.accent", "brand.text", "brand.background"), or a contrast token ("brand.on-primary" = black or white, whichever reads best). Hex colours and brand tokens accept an alpha suffix: "brand.primary/0.8", "#000000/0.5" |
type: "gradient"
| Field | Type | Description |
|---|---|---|
| typerequired | "gradient" | |
| colorsrequired | string[] | min 2 items |
| angle | number | Degrees |
type: "media"
| Field | Type | Description |
|---|---|---|
| typerequired | "media" | |
| slotrequired | string | Media slot key (image or video) |
| fit | "cover" | "contain" | |
| kenBurns | boolean | Slow zoom (images and videos) |
| dim | number | Black overlay 0..1 for legibilitymin 0 · max 1 |
| fallback | string | Literal colour (#RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), "transparent", "white", "black"), a brand token ("brand.primary", "brand.secondary", "brand.accent", "brand.text", "brand.background"), or a contrast token ("brand.on-primary" = black or white, whichever reads best). Hex colours and brand tokens accept an alpha suffix: "brand.primary/0.8", "#000000/0.5" |
TextLayer
Draws text from a slot (localized per market) or static text.
| Field | Type | Description |
|---|---|---|
| idrequired | string | Unique within the scene |
| xrequired | number | Left edge, fraction of canvas width (0..1) |
| yrequired | number | Top edge, fraction of canvas height (0..1) |
| wrequired | number | Width, fraction of canvas width |
| hrequired | number | Height, fraction of canvas height |
| start | number | Seconds from scene start (default 0)min 0 |
| end | number | Seconds from scene start (default: scene end)min 0 |
| opacity | number | min 0 · max 1 |
| rotation | number | Degrees |
| animation | LayerAnimation | |
| typerequired | "text" | |
| slot | string | Text comes from this text slot… |
| text | string | …or is static. Supports {{slot}} interpolation |
| fontrequired | FontStyle | |
| colorrequired | string | Literal colour (#RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), "transparent", "white", "black"), a brand token ("brand.primary", "brand.secondary", "brand.accent", "brand.text", "brand.background"), or a contrast token ("brand.on-primary" = black or white, whichever reads best). Hex colours and brand tokens accept an alpha suffix: "brand.primary/0.8", "#000000/0.5" |
| align | "left" | "center" | "right" | |
| valign | "top" | "middle" | "bottom" | |
| stroke | object | |
| shadow | object | |
| plate | object | Background plate behind the text (TikTok caption box). mode "lines" = one plate per line |
| highlightColor | string | Words wrapped in *asterisks* are drawn in this colour (default brand.accent) |
| balance | boolean | Balance line lengths (no lonely last word). Default true when align is center |
ImageLayer
Draws an image from a media slot or the brand logo.
| Field | Type | Description |
|---|---|---|
| idrequired | string | Unique within the scene |
| xrequired | number | Left edge, fraction of canvas width (0..1) |
| yrequired | number | Top edge, fraction of canvas height (0..1) |
| wrequired | number | Width, fraction of canvas width |
| hrequired | number | Height, fraction of canvas height |
| start | number | Seconds from scene start (default 0)min 0 |
| end | number | Seconds from scene start (default: scene end)min 0 |
| opacity | number | min 0 · max 1 |
| rotation | number | Degrees |
| animation | LayerAnimation | |
| typerequired | "image" | |
| slot | string | A media slot (image)… |
| src | "brand.logo" | …or the brand logo |
| fit | "cover" | "contain" | |
| radius | number | Corner radius, px at 1080 wide |
ShapeLayer
A rectangle, circle or star.
| Field | Type | Description |
|---|---|---|
| idrequired | string | Unique within the scene |
| xrequired | number | Left edge, fraction of canvas width (0..1) |
| yrequired | number | Top edge, fraction of canvas height (0..1) |
| wrequired | number | Width, fraction of canvas width |
| hrequired | number | Height, fraction of canvas height |
| start | number | Seconds from scene start (default 0)min 0 |
| end | number | Seconds from scene start (default: scene end)min 0 |
| opacity | number | min 0 · max 1 |
| rotation | number | Degrees |
| animation | LayerAnimation | |
| typerequired | "shape" | |
| shaperequired | "rect" | "circle" | "star" | |
| colorrequired | string | Literal colour (#RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), "transparent", "white", "black"), a brand token ("brand.primary", "brand.secondary", "brand.accent", "brand.text", "brand.background"), or a contrast token ("brand.on-primary" = black or white, whichever reads best). Hex colours and brand tokens accept an alpha suffix: "brand.primary/0.8", "#000000/0.5" |
| radius | number | |
| gradient | object | Gradient fill instead of color, e.g. a legibility scrim ["rgba(0,0,0,0)", "rgba(0,0,0,0.6)"] |
FontStyle
Typography of a text layer.
| Field | Type | Description |
|---|---|---|
| familyrequired | string | Font family (built-in or one you uploaded via POST /fonts) or a brand token: "brand.heading", "brand.body" |
| weight | integer | 100..900, default 700min 100 · max 900 |
| style | "normal" | "italic" | |
| sizerequired | number | px at a 1080 px wide canvas (scales linearly)> 0 |
| lineHeight | number | Multiplier, default 1.15> 0 |
| letterSpacing | number | px at 1080 wide |
| uppercase | boolean | |
| autoFit | boolean | Shrink the text until it fits the box (translations are often 30% longer). Never below minSize |
| minSize | number | Lower bound for autoFit, px at 1080 wide> 0 |
| maxLines | integer | > 0 |
LayerAnimation
| Field | Type | Description |
|---|---|---|
| in | AnimationName | |
| out | AnimationName | |
| inDuration | number | Seconds, default 0.4min 0 |
| outDuration | number | Seconds, default 0.3min 0 |
AnimationName
nonefadeslide-upslide-downslide-leftslide-rightpopzoomtypewriterglitchwipe