Template Basics

Templates turn one project into many videos: author the design once with variables, then render it with different data every time — one render at a time or thousands in bulk.

Variables and placeholders

Declare defaults under variables and reference them anywhere in the payload with {{name}}:

{
  "variables": {
    "title": "Aurora Sneakers",
    "accent": "#a78bfa",
    "price": "$129"
  },
  "visuals": [
    {
      "type": "TEXT",
      "html": "<div class=\"name\">{{title}}</div><div class=\"price\">{{price}}</div>",
      "customCode": {
        "css": ".price { color: {{accent}}; }"
      }
    }
  ]
}

• Placeholders work in text, HTML, CSS, URLs, colors, and numeric fields.
• {{name.path.to.field}} reaches into object and array variables ({{product.title}}, {{sizes.0}}).
• Variables can be strings, numbers, booleans, arrays, or objects.
• Scenes can declare their own variables block, which shadows project variables inside that scene.
• Unresolvable placeholders are rejected at submit time with a field-level validation error — you can't accidentally ship {{title}} on screen.

Rendering with data

Submit template or payload (never both) to the render endpoint. Request-time variables override the declared defaults:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_xxxxxxxxxxxxxxxxxxxx",
    "variables": { "title": "Nimbus Backpack", "accent": "#f59e0b", "price": "$89" },
    "overrides": { "name": "nimbus-backpack" }
  }'

• template — a stored template id (tpl_…). Save one from the editor (Save → Save as template) or via POST /api/templates; find ids on the dashboard's Templates page.
• variables — per-render values merged over the template's defaults.
• overrides — output knobs applied after resolution: name, width, height, outputFormat, frameRate, backgroundColor, and the image-render fields (snapshotTime, quality, transparent).

You can also send a full payload containing variables — templates don't have to be stored to use placeholders.

Same template, two datasets

The exact same payload rendered twice with different variables:

{
  "name": "docs-template-var-a",
  "width": 960,
  "height": 540,
  "duration": 5,
  "backgroundColor": "#140b2e",
  "variables": {
    "title": "Aurora Sneakers",
    "accent": "#a78bfa",
    "price": "$129"
  },
  "visuals": [
    {
      "type": "TEXT",
      "html": "<div class=\"card\"><div class=\"name\">{{title}}</div><div class=\"price\">{{price}}</div></div>",
      "position": "center-center",
      "enterBegin": 0,
      "exitEnd": 5,
      "customCode": {
        "css": ".card { display: flex; flex-direction: column; align-items: center; gap: 12px; padding: 40px 80px; background: rgba(255,255,255,0.06); border: 2px solid {{accent}}; border-radius: 24px; } .name { color: #ffffff; font-family: Montserrat; font-size: 56px; font-weight: 800; } .price { color: {{accent}}; font-family: Poppins; font-size: 44px; font-weight: 700; animation: pop 1.4s ease-in-out infinite; } @keyframes pop { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.12); } }",
        "animationDuration": 1.4
      }
    }
  ]
}

Rendered by Zvid

variables: { "title": "Aurora Sneakers", "accent": "#a78bfa", "price": "$129" }

The same template with { "title": "Nimbus Backpack", "accent": "#f59e0b", "price": "$89" }

Template API

Endpoint	Auth	Purpose
GET /api/templates	JWT	List your templates
POST /api/templates	JWT	Create a template from a project
GET /api/templates/{id}	JWT or API key	Fetch a template (inspect variables)
PUT /api/templates/{id}	JWT	Update
DELETE /api/templates/{id}	JWT	Archive
POST /api/templates/{id}/duplicate	JWT	Duplicate
POST /api/templates/{id}/preview	JWT or API key	Render a preview of the template

Next

• Dynamic content — generate scenes from arrays with iterate and show/hide content with condition.
• Bulk rendering — one request, many variable sets.
• Variables in the editor — author templates visually.