Merge Fields

Merge fields are dynamic placeholders in templates that get replaced with actual values at render time. This page documents all available merge field types and their behavior.

Syntax

Use double curly braces in your timeline JSON:

{{field_name}}

Merge fields can appear in any string value within the timeline, including asset properties, URLs, colors, and text content.

Field Types

text

A plain text value. Used for titles, captions, and any text content.

{
  "name": "headline",
  "type": "text",
  "default": "Your Headline Here",
  "required": false,
  "max_length": 100,
  "description": "Main headline text displayed at the top"
}

Usage in timeline:

{ "asset": { "type": "title", "text": "{{headline}}" } }

image_url

A URL pointing to an image file (JPEG, PNG, WebP, GIF).

{
  "name": "product_image",
  "type": "image_url",
  "default": null,
  "required": true,
  "description": "Product photo (recommended 1920x1080)"
}

Usage in timeline:

{ "asset": { "type": "image", "src": "{{product_image}}" } }

video_url

A URL pointing to a video file (MP4, WebM, MOV).

{
  "name": "background_video",
  "type": "video_url",
  "default": "https://example.com/default-bg.mp4",
  "required": false,
  "description": "Background video clip"
}

Usage in timeline:

{ "asset": { "type": "video", "src": "{{background_video}}" } }

color

A hex color value (e.g., #ff6b00).

{
  "name": "brand_color",
  "type": "color",
  "default": "#000000",
  "required": false,
  "description": "Primary brand color for backgrounds and accents"
}

Usage in timeline:

{
  "background": "{{brand_color}}",
  "tracks": [
    {
      "clips": [
        {
          "asset": { "type": "title", "text": "Hello", "color": "{{brand_color}}" }
        }
      ]
    }
  ]
}

number

A numeric value. Used for timing, scale, opacity, and other numeric properties.

{
  "name": "display_duration",
  "type": "number",
  "default": 5,
  "required": false,
  "min": 1,
  "max": 30,
  "description": "How long to display the main content (seconds)"
}

Usage in timeline:

{ "start": 0, "length": "{{display_duration}}" }

Field Properties

Property	Type	Required	Description
name	string	Yes	Unique field identifier (alphanumeric and underscores)
type	string	Yes	text, image_url, video_url, color, number
default	any	No	Default value if not provided at render time
required	boolean	No	Whether the field must be provided (default: false)
description	string	No	Human-readable description shown in the gallery
max_length	number	No	Maximum character length (text fields only)
min	number	No	Minimum value (number fields only)
max	number	No	Maximum value (number fields only)

Example: Complete Template Definition

{
  "name": "Social Media Ad",
  "merge_fields": [
    {
      "name": "headline",
      "type": "text",
      "default": "Big Sale!",
      "max_length": 50,
      "description": "Main headline"
    },
    {
      "name": "offer_text",
      "type": "text",
      "default": "50% off everything",
      "description": "Offer details"
    },
    {
      "name": "product_image",
      "type": "image_url",
      "required": true,
      "description": "Product photo (square, min 1024x1024)"
    },
    {
      "name": "bg_color",
      "type": "color",
      "default": "#1a1a2e",
      "description": "Background color"
    },
    {
      "name": "accent_color",
      "type": "color",
      "default": "#e94560",
      "description": "Accent color for text highlights"
    },
    {
      "name": "clip_duration",
      "type": "number",
      "default": 5,
      "min": 3,
      "max": 15,
      "description": "Video duration in seconds"
    }
  ],
  "timeline": {
    "background": "{{bg_color}}",
    "tracks": [
      {
        "clips": [
          {
            "asset": { "type": "title", "text": "{{headline}}", "color": "{{accent_color}}", "size": "large" },
            "start": 0.5,
            "length": "{{clip_duration}}",
            "transition": { "in": "slideUp" },
            "offset": { "x": 0, "y": -0.35 }
          },
          {
            "asset": { "type": "title", "text": "{{offer_text}}", "color": "#ffffff", "size": "small" },
            "start": 1.5,
            "length": "{{clip_duration}}",
            "transition": { "in": "fade" },
            "offset": { "x": 0, "y": 0.35 }
          }
        ]
      },
      {
        "clips": [
          {
            "asset": { "type": "image", "src": "{{product_image}}" },
            "start": 0,
            "length": "{{clip_duration}}",
            "scale": 0.5,
            "transition": { "in": "zoom" }
          }
        ]
      }
    ]
  }
}

Rendering with Merge Fields

curl -X POST https://api.vidiking.com/v1/templates/tpl_social_001/render \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merge_fields": {
      "headline": "Summer Sale",
      "offer_text": "Up to 70% off sunglasses",
      "product_image": "https://example.com/sunglasses.png",
      "bg_color": "#0a1628",
      "accent_color": "#ffd700",
      "clip_duration": 8
    }
  }'

Validation

When rendering a template, the API validates merge fields:

• Required fields must be provided or the request returns a 400 error.
• Type validation ensures color fields are valid hex codes, number fields are numeric, and URL fields are valid URLs.
• Range validation checks min/max for number fields and max_length for text fields.
• Missing optional fields use their default values.