Templates and fields

Groups and order

group puts a field in a named panel; order sorts within it; advanced: true hides it behind a disclosure. The template’s fieldGroups array sets the panel order.

Conditional visibility

Show a field only when another has a particular value.

{
  "key": "discountBadge",
  "type": "text",
  "visibleWhen": { "field": "showDiscount", "equals": true }
}

// Also supported:
// "visibleWhen": { "field": "layout", "in": ["hero", "split"] }
// "visibleWhen": { "field": "mode", "notEquals": "minimal" }

Audience

editorOnly: true shows a field in the studio but hides it from the API schema. apiOnly: true does the reverse — useful for values your systems supply that a human should never type.

The frame — every layer has these

Effects

effects applies to any layer type, not just pictures — the renderer puts it on the layer frame, above whatever the layer happens to draw. A glow follows the actual silhouette, so a glowing star is a glowing star rather than a glowing rectangle.

{
  "effects": {
    "shadow":  { "enabled": true, "x": 0, "y": 20, "blur": 48,
                 "spread": -8, "color": "#0F172A", "opacity": 30 },
    "glow":    { "enabled": true, "blur": 24, "color": "#8B3DFF", "opacity": 80 },
    "outline": { "enabled": true, "width": 3, "color": "#171C26" },
    "blur": 0,
    "backdropBlur": 18
  }
}

Shapes

shapeType names a silhouette. Rectangles and ellipses are drawn as boxes so borderRadius still applies to them; everything else is a path that stretches with the layer.

Lines and connectors

A line is a shape, but it is drawn as a strokerather than as a filled outline — which is what lets it carry a dash pattern, a cap and an arrowhead. The geometry is generated at the layer’s real size, so the thickness is even along the whole path and a dash stays the length it was asked for however long the line is.

A pinned connector stores the relationship, not the coordinates. Its box is recomputed from the two elements immediately before layout, so an arrow between two cards stays between them even when a field moves one of them on this particular render. Pinning to a layer that no longer exists is not an error — the connector keeps the box it was drawn with.

The colour comes from fillColor, not borderColor: to whoever is reading the design there is one line colour, and the arrowheads are painted in it too.

Widgets, and binding data to them

A widget draws a single number: a progress bar, a ring, a gauge or a KPI. It has three colours, because it is three things — the filled part, the unfilled track behind it, and the type on top.

Binding a field to a widget layer sends a value on every render, which is the point of putting one on a template. A plain number is enough — 72 or 72% sets widgetValue. A JSON object sets anything else on the layer, so one field can move the value and recolour it at once. A color field bound to the layer sets fillColor, the same as it does for a shape.

{ "completion": "72" }

// or, to set more than the value:
{ "completion": "{"widgetValue":72,"fillColor":"#00C853"}" }

The same applies to chart and table layers: a field carrying JSON replaces their data, and a colour field recolours them.

Type and legends on a chart layer

A chart, table or widget layer is drawn by the same renderer the video engine uses, so the same JSON produces the same pixels as a still, in a video, or in the mobile app. Its labels are derived from fontSize — a title is that plus three, an axis tick one less — which is a good default and a poor ceiling. These fields are the ceiling coming off.

{
  "type": "chart",
  "chartType": "bar",
  "chartTitle": "Enquiries by month",
  "chartData": { "labels": ["Jun","Jul","Aug"], "values": [18,34,27] },
  "chartFontScale": 1.5
}

// One number. Labels, ticks, the legend and its
// swatches all grow together, and the left gutter
// widens to fit the bigger ticks.

Shadows, glow and depth

A shadow is cast by what the layer draws, not by its box. A path shape, an icon, a QR and text with no background behind it all cast the shadow of their own outline; a rectangle, a plain photo or a text box with a background casts a box shadow, which is the only one of the two that can take a spread or an inset.

QR codes and barcodes

A code layer stores the settings, not a picture of a code — so binding a field to code.value makes one template produce a different, correct code on every render. That is the whole reason to have this rather than an uploaded image: a per-recipient link, an order number, a ticket.

Recolouring artwork that has several colours

Most shapes take one fillColor, and dimensional ones derive their lit and shaded faces from it. Some artwork is multicoloured on purpose — a confetti scatter, a bunting, a two-tone icon — and for those a single fill would only flatten the thing that makes it work.

paletteis an array of colours, positional against the element’s own palette in painting order. An entry that is nullor missing keeps the artwork’s original colour, and anything that is not a valid CSS colour is ignored rather than drawn. Repeated colours count once: a bunting with twelve flags in six colours takes six entries, and changing the second recolours every flag painted in it.

{
  "type": "shape",
  "shapeType": "bunting",
  "palette": ["#8B3DFF", null, "#00C4CC"]
}

Pictures

removeBackground is set on the LAYER, not baked into the asset, because the picture usually is not known when the template is authored — a product field supplies a different photo on every render. The cut-out therefore runs on whatever image the render was given.

Icons

An icon is stored as geometry, not as a picture. A rasterised icon cannot be recoloured to match a palette and softens the moment it is scaled past its capture size, and those are the two things people do to icons constantly.

Live screenshots

An image layer can carry screenshot settings instead of a fixed picture. When it does, the renderer captures that page on every render — so a pricing template rendered next quarter shows next quarter’s prices, with nobody reopening the design.

{
  "type": "image",
  "imageUri": "https://cdn.pixbix.app/…/preview.png",
  "screenshot": {
    "enabled": true,
    "url": "https://acme.com/pricing",
    "viewportWidth": 1440,
    "viewportHeight": 900,
    "scale": 2,
    "fullPage": false,
    "blockCookieBanners": true,
    "cacheTtlSec": 3600
  }
}

Binding a field to screenshot.url is the automation case: one template captures whichever page each caller names. imageUri stays on the layer as a preview, and is what the layer falls back to if a capture fails.

Type

Styling one word differently

Everything above sets the type for the WHOLE layer. richText overrides it for a slice of the string — one word in a brand colour, a number twice the size, a phrase in another face — without splitting the sentence across separate layers.

It is an array of runs. Each run carries its own textplus only the properties it changes; everything it does not name is inherited from the layer, so changing the layer’s font later still moves the styled words with it.

{
  "type": "text",
  "text": "Big Diwali Sale",
  "fontFamily": "Poppins",
  "fontSize": 48,
  "textColor": "#111827",
  "richText": [
    { "text": "Big " },
    { "text": "Diwali", "color": "#E11D48", "fontSize": 72, "fontWeight": "700" },
    { "text": " Sale" }
  ]
}

The canvas

backgroundColor is the floor, backgroundGradient paints over it, and backgroundImage covers both — sized by backgroundFit (cover, contain, fill or tile).

Only published templates render

status is the single gate on rendering. A draft is refused everywhere — by /v1/render, by /v1/generate, by every workflow step and by the dashboard — with TEMPLATE_NOT_PUBLISHED. Publishing is your own decision and takes effect immediately; nobody reviews it, because it only affects renders inside your own workspace.

Before a template can be published it must have a name, a main category, and:

• For image templates — at least one layer
• For video templates — a timeline with tracks and a duration
• No duplicate field keys (duplicates silently drop values at render time)

A public template is copied, never borrowed

You can only render a template your own workspace owns. Marking one public offers it to other accounts to copy — they take their own copy with POST /templates/:id/duplicateand render that. Naming somebody else’s template in a render returns TEMPLATE_NOT_OWNED with a message saying so.

The list and schema endpoints both report canRender so you never have to work this out from status and ownership yourself. When it is false, renderBlockedReason says what to do about it.

Getting into the library

Setting visibility: "public" puts the template in a staff review queue (review.state: "pending"). It appears in the shared library once approved and once it is also published. A public template additionally needs a thumbnail and at least one field — the two things somebody browsing needs in order to judge it.

Editing the design of a listed template sends the listing back for review, so the library cannot be edited into something else after approval. Your own renders keep working the whole time — status is untouched, and only the shopfront entry pauses. Going back to private delists it at once and needs no review.