Templates and Reuse

Templates let you define a video structure once and fill it with different content repeatedly. One template plus a spreadsheet of data equals hundreds of brand-consistent videos.

Defining a Style

Reusable element settings start with define style. Define them at the top of your .ws file and apply them to any element.

text
define style heading
  size: hero
  weight: heavy
  enter: rise

Film "Demo"
  mood: confident

Scene "Intro"
  show "Welcome"
    style: heading

Styles reduce repetition. Change the style definition once and every element using it updates.

Defining a Template

Templates are reusable scene layouts with variable placeholders. Variables use {curly_braces}.

text
define template feature-card [5s]
  background: dark
  show "{headline}"
    size: display
    enter: rise
  then show "{description}"
    size: body
    color: muted

Instantiate a template with Scene from:

text
Scene "Feature 1" from feature-card
  headline: "Lightning Fast"
  description: "Render 10,000 videos without breaking a sweat."

Scene "Feature 2" from feature-card
  headline: "Brand Safe"
  description: "Every video matches your guidelines by construction."

Both scenes share the same layout, timing, and animation — only the content differs.

Registering Templates via API

For programmatic use, register templates through the API. The template envelope is a JSON object containing the .ws source and a variable schema.

bash
curl -X POST https://api.ws.video/api/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "name": "demo-card",
    "description": "Simple demo card with title and subtitle",
    "version": "1.0.0",
    "variables": [
      { "name": "title", "type": "string", "required": true, "example": "Hello World" },
      { "name": "subtitle", "type": "string", "required": false, "default": "" }
    ],
    "defaults": { "mood": "confident", "aspect": "16:9" },
    "source": "define template demo-card [5s]\n  background: dark\n  show \"{title}\"\n    size: display\n    enter: rise\n  show \"{subtitle}\"\n    size: caption"
  }'

Templates are scoped to your organization via the x-org-id header.

Rendering from Templates

Once a template is registered, render videos by supplying variables and optional overrides:

bash
curl -X POST https://api.ws.video/api/render/template \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "template": "product-launch",
    "variables": {
      "headline": "Introducing Apex",
      "tagline": "The future of productivity",
      "feature1": "10x faster workflows",
      "feature2": "AI-powered insights",
      "feature3": "Enterprise-ready security",
      "cta": "Start free at apex.dev"
    },
    "overrides": {
      "mood": "dramatic",
      "theme": "corporate-blue"
    }
  }'

The overrides object lets you change mood and theme without modifying the template itself.

Built-in Templates

Workshop includes starter templates for common use cases: product launch, quarterly report, social promo, chapter card, and testimonial. List them with:

bash
curl https://api.ws.video/api/templates \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID"

Next Steps