☰ Menu

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: text slots (localized per market) and media slots (images/videos shared by all markets). A post fills them with fields and media.
  • Scenes play in order; each has a duration (seconds), a background and layers drawn bottom to top.
  • Layers are text, image or shape. Text layers point at a slot (slot: "hook") or have static text with {{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) and animation.in/out per layer; transition per scene (cut, fade, slide).
  • Versioning: updating a template's spec bumps version. 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.

TokenResolves to
brand.primary brand.secondary brand.accentBrand colours
brand.text brand.backgroundDefault 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.5Alpha suffix on tokens and hex colours
brand.heading brand.bodyFont 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: true shrinks the text until it fits the layer box — never below font.minSize. Combine with font.maxLines.
  • maxChars on 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).
  • hint on 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#

safe

TikTok draws its UI over the video. Keep text inside the safe area (fractions of the canvas):

EdgeKeep clearWhy
top0.08 (8%)Top navigation tabs, search
bottom0.2 (20%)Caption, music ticker
left0.06 (6%)Margin
right0.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.

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

spec
{
  "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"
        }
      ]
    }
  ]
}
bash
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 return 400 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.

FieldTypeDescription
versionrequired1
widthrequiredintegerCanvas width in px, normally 1080> 0
heightrequiredintegerCanvas height in px, normally 1920 (9:16)> 0
fpsrequiredintegerFrames per second, normally 30> 0
slotsrequiredSlot[]Inputs a post fills in
scenesrequiredScene[]Played in order; total duration = sum of scene durationsmin 1 items
audioSlotstringMedia 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.

FieldTypeDescription
keyrequiredstringSlot key used in post fields, e.g. "hook", "line1", "cta"
typerequired"text"
labelrequiredstringHuman label shown in the composer and in errors
requiredbooleanPost creation fails when empty
maxCharsintegerHard limit checked after localization; an over-long translation blocks approval> 0
multilinebooleanAllow line breaks
translatebooleanDefault true. false keeps the source text in every market (codes, brand names)
defaultstringUsed when the post leaves the slot empty
hintstringGuidance for the AI localizer, e.g. "short punchy hook, max 6 words"
samplesmap<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.

FieldTypeDescription
keyrequiredstringSlot key used in post media, e.g. "bg1", "product"
typerequired"media"
labelrequiredstring
acceptrequired"image" | "video"[]Which asset kinds fit this slot
requiredboolean

Scene

FieldTypeDescription
idrequiredstring
durationrequirednumberSeconds> 0
backgroundrequiredBackground
layersrequiredLayer[]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"

FieldTypeDescription
typerequired"color"
colorrequiredstringLiteral 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"

FieldTypeDescription
typerequired"gradient"
colorsrequiredstring[]min 2 items
anglenumberDegrees

type: "media"

FieldTypeDescription
typerequired"media"
slotrequiredstringMedia slot key (image or video)
fit"cover" | "contain"
kenBurnsbooleanSlow zoom (images and videos)
dimnumberBlack overlay 0..1 for legibilitymin 0 · max 1
fallbackstringLiteral 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.

FieldTypeDescription
idrequiredstringUnique within the scene
xrequirednumberLeft edge, fraction of canvas width (0..1)
yrequirednumberTop edge, fraction of canvas height (0..1)
wrequirednumberWidth, fraction of canvas width
hrequirednumberHeight, fraction of canvas height
startnumberSeconds from scene start (default 0)min 0
endnumberSeconds from scene start (default: scene end)min 0
opacitynumbermin 0 · max 1
rotationnumberDegrees
animationLayerAnimation
typerequired"text"
slotstringText comes from this text slot…
textstring…or is static. Supports {{slot}} interpolation
fontrequiredFontStyle
colorrequiredstringLiteral 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"
strokeobject
shadowobject
plateobjectBackground plate behind the text (TikTok caption box). mode "lines" = one plate per line
highlightColorstringWords wrapped in *asterisks* are drawn in this colour (default brand.accent)
balancebooleanBalance line lengths (no lonely last word). Default true when align is center

ImageLayer

Draws an image from a media slot or the brand logo.

FieldTypeDescription
idrequiredstringUnique within the scene
xrequirednumberLeft edge, fraction of canvas width (0..1)
yrequirednumberTop edge, fraction of canvas height (0..1)
wrequirednumberWidth, fraction of canvas width
hrequirednumberHeight, fraction of canvas height
startnumberSeconds from scene start (default 0)min 0
endnumberSeconds from scene start (default: scene end)min 0
opacitynumbermin 0 · max 1
rotationnumberDegrees
animationLayerAnimation
typerequired"image"
slotstringA media slot (image)…
src"brand.logo"…or the brand logo
fit"cover" | "contain"
radiusnumberCorner radius, px at 1080 wide

ShapeLayer

A rectangle, circle or star.

FieldTypeDescription
idrequiredstringUnique within the scene
xrequirednumberLeft edge, fraction of canvas width (0..1)
yrequirednumberTop edge, fraction of canvas height (0..1)
wrequirednumberWidth, fraction of canvas width
hrequirednumberHeight, fraction of canvas height
startnumberSeconds from scene start (default 0)min 0
endnumberSeconds from scene start (default: scene end)min 0
opacitynumbermin 0 · max 1
rotationnumberDegrees
animationLayerAnimation
typerequired"shape"
shaperequired"rect" | "circle" | "star"
colorrequiredstringLiteral 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"
radiusnumber
gradientobjectGradient 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.

FieldTypeDescription
familyrequiredstringFont family (built-in or one you uploaded via POST /fonts) or a brand token: "brand.heading", "brand.body"
weightinteger100..900, default 700min 100 · max 900
style"normal" | "italic"
sizerequirednumberpx at a 1080 px wide canvas (scales linearly)> 0
lineHeightnumberMultiplier, default 1.15> 0
letterSpacingnumberpx at 1080 wide
uppercaseboolean
autoFitbooleanShrink the text until it fits the box (translations are often 30% longer). Never below minSize
minSizenumberLower bound for autoFit, px at 1080 wide> 0
maxLinesinteger> 0

LayerAnimation

FieldTypeDescription
inAnimationName
outAnimationName
inDurationnumberSeconds, default 0.4min 0
outDurationnumberSeconds, default 0.3min 0

AnimationName

nonefadeslide-upslide-downslide-leftslide-rightpopzoomtypewriterglitchwipe