Creating Templates

Build reusable video templates by defining a timeline with merge fields. Templates can be private (your account only) or published to the community gallery.

Create a Template

curl

curl -X POST https://api.vidiking.com/v1/templates \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Showcase",
    "description": "Clean product showcase with customizable headline, image, and brand colors",
    "category": "ecommerce",
    "merge_fields": [
      { "name": "product_name", "type": "text", "default": "Product Name" },
      { "name": "product_image", "type": "image_url", "required": true },
      { "name": "price", "type": "text", "default": "$99" },
      { "name": "brand_color", "type": "color", "default": "#000000" },
      { "name": "background_video", "type": "video_url", "required": false }
    ],
    "timeline": {
      "background": "{{brand_color}}",
      "tracks": [
        {
          "clips": [
            {
              "asset": {
                "type": "title",
                "text": "{{product_name}}",
                "style": "minimal",
                "size": "large",
                "color": "#ffffff"
              },
              "start": 0.5,
              "length": 4,
              "transition": { "in": "fade", "out": "fade" },
              "offset": { "x": 0, "y": -0.3 }
            },
            {
              "asset": {
                "type": "title",
                "text": "{{price}}",
                "style": "minimal",
                "size": "medium",
                "color": "#ffffff"
              },
              "start": 1.5,
              "length": 3,
              "transition": { "in": "slideUp", "out": "fade" },
              "offset": { "x": 0, "y": 0.3 }
            }
          ]
        },
        {
          "clips": [
            {
              "asset": {
                "type": "image",
                "src": "{{product_image}}"
              },
              "start": 0,
              "length": 5,
              "scale": 0.6,
              "transition": { "in": "zoom", "out": "fade" }
            }
          ]
        }
      ]
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "1:1"
    },
    "visibility": "private"
  }'

Node.js

const template = await client.templates.create({
  name: 'Product Showcase',
  description: 'Clean product showcase with customizable headline, image, and brand colors',
  category: 'ecommerce',
  mergeFields: [
    { name: 'product_name', type: 'text', default: 'Product Name' },
    { name: 'product_image', type: 'image_url', required: true },
    { name: 'price', type: 'text', default: '$99' },
    { name: 'brand_color', type: 'color', default: '#000000' },
  ],
  timeline: {
    background: '{{brand_color}}',
    tracks: [/* ... */],
  },
  output: { format: 'mp4', resolution: 'hd', aspectRatio: '1:1' },
  visibility: 'private',
});

console.log('Template ID:', template.id);

Python

template = client.templates.create({
    "name": "Product Showcase",
    "description": "Clean product showcase",
    "category": "ecommerce",
    "merge_fields": [
        {"name": "product_name", "type": "text", "default": "Product Name"},
        {"name": "product_image", "type": "image_url", "required": True},
        {"name": "price", "type": "text", "default": "$99"},
        {"name": "brand_color", "type": "color", "default": "#000000"},
    ],
    "timeline": {
        "background": "{{brand_color}}",
        "tracks": [# ... ],
    },
    "output": {"format": "mp4", "resolution": "hd", "aspectRatio": "1:1"},
    "visibility": "private",
})

print("Template ID:", template.id)

Merge Field Syntax

Use {{field_name}} anywhere in the timeline JSON to create a dynamic value. When rendering, the merge field value replaces the placeholder.

{
  "asset": {
    "type": "title",
    "text": "Hello, {{customer_name}}!",
    "color": "{{text_color}}"
  }
}

Publishing to Community

Change visibility from private to public to publish your template to the community gallery.

curl -X PUT https://api.vidiking.com/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'

Published templates are reviewed before appearing in the gallery. You earn credits when others use your templates.

Updating a Template

curl -X PUT https://api.vidiking.com/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Showcase v2",
    "description": "Updated with new transitions"
  }'

Deleting a Template

curl -X DELETE https://api.vidiking.com/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer $VIDIKING_API_KEY"

Tips

• Test your template with multiple sets of merge field values to ensure it works with different content lengths and image sizes.
• Use fit: "cover" on image clips to handle different aspect ratios gracefully.
• Provide sensible defaults for all merge fields so the template preview looks good.
• Add a thumbnail by including a thumbnail_url when creating the template.