Timeline

The timeline is the core data structure for composing videos in Vidiking. It uses a Shotstack-compatible JSON format built around four concepts: timeline, tracks, clips, and assets.

Structure Overview

Timeline
├── background (color)
├── soundtrack (audio URL)
└── tracks[] (ordered layers)
    └── clips[] (media segments)
        ├── asset (content: video, image, title, audio, html)
        ├── start (seconds)
        ├── length (seconds)
        ├── transition (in/out effects)
        ├── offset (x/y position)
        ├── scale (size multiplier)
        └── opacity (0-1)

Tracks

Tracks are ordered layers. Track 0 is the topmost layer (foreground), and higher-indexed tracks sit behind it. This is the same ordering as Shotstack.

{
  "timeline": {
    "tracks": [
      { "clips": [...] },
      { "clips": [...] },
      { "clips": [...] }
    ]
  }
}

In this example, tracks[0] renders on top of tracks[1], which renders on top of tracks[2].

Clips

A clip places an asset on the timeline at a specific start time for a specific duration.

Property	Type	Required	Description
asset	object	Yes	The content to render (see Asset Types)
start	number	Yes	Start time in seconds
length	number	Yes	Duration in seconds
transition	object	No	In/out transition effects
offset	object	No	{ x: number, y: number } position offset (-1 to 1)
scale	number	No	Size multiplier (default 1.0)
opacity	number	No	Transparency (0 = invisible, 1 = fully visible)
fit	string	No	cover, contain, crop, none

Asset Types

Video

{
  "type": "video",
  "src": "https://example.com/clip.mp4",
  "trim": 2,
  "volume": 0.8
}

Image

{
  "type": "image",
  "src": "https://example.com/photo.jpg"
}

Title

{
  "type": "title",
  "text": "My Title",
  "style": "minimal",
  "size": "large",
  "color": "#ffffff"
}

Audio

{
  "type": "audio",
  "src": "https://example.com/music.mp3",
  "trim": 0,
  "volume": 0.5,
  "effect": "fadeInFadeOut"
}

HTML

{
  "type": "html",
  "html": "<div style='color:white;font-size:48px'>Custom HTML</div>",
  "css": "div { text-align: center; }",
  "width": 800,
  "height": 200
}

Full Example: Two Tracks with Transitions

This example creates a video with a title overlay on top of an image background, with fade transitions.

{
  "timeline": {
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Welcome to Vidiking",
              "style": "minimal",
              "size": "large",
              "color": "#ffffff"
            },
            "start": 0.5,
            "length": 4,
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "offset": {
              "x": 0,
              "y": -0.2
            }
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "image",
              "src": "https://example.com/background1.jpg"
            },
            "start": 0,
            "length": 5,
            "transition": {
              "in": "fade",
              "out": "fade"
            }
          },
          {
            "asset": {
              "type": "image",
              "src": "https://example.com/background2.jpg"
            },
            "start": 5,
            "length": 5,
            "transition": {
              "in": "fade",
              "out": "fade"
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "hd"
  }
}

curl

curl -X POST https://api.vidiking.com/v1/render \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d @timeline.json

Node.js

const { jobId } = await client.render({
  timeline: {
    background: '#000000',
    tracks: [
      {
        clips: [
          {
            asset: { type: 'title', text: 'Welcome to Vidiking', style: 'minimal', size: 'large' },
            start: 0.5,
            length: 4,
            transition: { in: 'fade', out: 'fade' },
          },
        ],
      },
      {
        clips: [
          {
            asset: { type: 'image', src: 'https://example.com/bg1.jpg' },
            start: 0,
            length: 5,
            transition: { in: 'fade', out: 'fade' },
          },
          {
            asset: { type: 'image', src: 'https://example.com/bg2.jpg' },
            start: 5,
            length: 5,
            transition: { in: 'fade', out: 'fade' },
          },
        ],
      },
    ],
  },
  output: { format: 'mp4', resolution: 'hd' },
});

Python

result = client.render({
    "timeline": {
        "background": "#000000",
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {"type": "title", "text": "Welcome to Vidiking", "style": "minimal", "size": "large"},
                        "start": 0.5,
                        "length": 4,
                        "transition": {"in": "fade", "out": "fade"},
                    }
                ]
            },
            {
                "clips": [
                    {
                        "asset": {"type": "image", "src": "https://example.com/bg1.jpg"},
                        "start": 0,
                        "length": 5,
                        "transition": {"in": "fade", "out": "fade"},
                    },
                    {
                        "asset": {"type": "image", "src": "https://example.com/bg2.jpg"},
                        "start": 5,
                        "length": 5,
                        "transition": {"in": "fade", "out": "fade"},
                    },
                ]
            },
        ],
    },
    "output": {"format": "mp4", "resolution": "hd"},
})

Output Options

Property	Type	Options	Default
format	string	mp4, gif, webm, mov	mp4
resolution	string	preview, sd, hd, 1080, 4k	hd
fps	number	15, 24, 25, 30, 60	25
quality	string	low, medium, high	medium
aspectRatio	string	16:9, 9:16, 1:1, 4:5	16:9

Related

• Render Endpoint
• Transitions
• Overlays