Video Combining

Combine multiple video files into a single seamless output. VideoCascadeintelligently handles different codecs, resolutions, and frame rates, with smart stream-copy optimization when possible.

Basic Usage

To combine videos, set combine: true and provide an array of video URLs in the files parameter:

curl -X POST https://api.videocascade.com/v1/videos \
  -H "Authorization: Bearer vca_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "combine": true,
    "files": [
      { "url": "https://example.com/video1.mp4" },
      { "url": "https://example.com/video2.mp4" },
      { "url": "https://example.com/video3.mp4" }
    ]
  }'

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    combine: true,
    files: [
      { url: 'https://example.com/video1.mp4' },
      { url: 'https://example.com/video2.mp4' },
      { url: 'https://example.com/video3.mp4' },
    ],
  }),
});

const data = await response.json();
console.log(`Combined video ID: ${data.videoId}`);

import requests

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'combine': True,
        'files': [
            {'url': 'https://example.com/video1.mp4'},
            {'url': 'https://example.com/video2.mp4'},
            {'url': 'https://example.com/video3.mp4'},
        ],
    }
)

data = response.json()
print(f"Combined video ID: {data['videoId']}")

interface FileInput {
  url: string;
  removeSegments?: Array<{ startTime: number; endTime: number }>;
  disableAudio?: boolean;
}

const response = await fetch('https://api.videocascade.com/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer vca_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
combine: true,
files: [
{ url: 'https://example.com/video1.mp4' },
{ url: 'https://example.com/video2.mp4' },
{ url: 'https://example.com/video3.mp4' },
] as FileInput[],
}),
});

const data = await response.json();
console.log(`Combined video ID: ${data.videoId}`);

Required: When using the files parameter, combine must be set to true.

Files Array Structure

Each file in the files array can have these properties:

Property	Type	Required	Description
`url`	string	Yes	Valid URL to the video file
`removeSegments`	array	No	Segments to remove from this specific file
`disableAudio`	boolean	No	Remove audio from this specific file

Example with Per-File Controls

{
  "combine": true,
  "files": [
    {
      "url": "https://example.com/intro.mp4",
      "disableAudio": true
    },
    {
      "url": "https://example.com/main-content.mp4",
      "removeSegments": [
        { "startTime": 10.5, "endTime": 15.2 },
        { "startTime": 45.0, "endTime": 52.3 }
      ]
    },
    {
      "url": "https://example.com/outro.mp4"
    }
  ]
}

Per-File Segment Removal

You can remove specific segments from individual files before combining:

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    combine: true,
    files: [
      {
        url: 'https://example.com/video1.mp4',
        // Remove 5 seconds from the end
        removeSegments: [
          { startTime: 55, endTime: 60 }
        ]
      },
      {
        url: 'https://example.com/video2.mp4',
        // Remove awkward pause in the middle
        removeSegments: [
          { startTime: 23.5, endTime: 28.0 }
        ]
      },
      {
        url: 'https://example.com/video3.mp4',
        // No segments removed from this one
      }
    ],
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'combine': True,
        'files': [
            {
                'url': 'https://example.com/video1.mp4',
                'removeSegments': [
                    {'startTime': 55, 'endTime': 60}
                ]
            },
            {
                'url': 'https://example.com/video2.mp4',
                'removeSegments': [
                    {'startTime': 23.5, 'endTime': 28.0}
                ]
            },
            {
                'url': 'https://example.com/video3.mp4',
            }
        ],
    }
)

Per-File vs Global Segment Removal

There are two ways to remove segments when combining videos:

Per-File Segment Removal (Recommended for combining):

Specified in each file object: files[i].removeSegments
Removes segments from individual files before combining
More precise control over what gets removed from each video

Global Segment Removal:

Specified at the top level: removeSegments
Applies to the entire combined video after combination
Use when you want to remove segments from the final output

{
  "combine": true,
  "files": [
    {
      "url": "https://example.com/video1.mp4",
      "removeSegments": [{ "startTime": 10, "endTime": 15 }]
    },
    {
      "url": "https://example.com/video2.mp4"
    }
  ],
  "removeSegments": [{ "startTime": 30, "endTime": 35 }]
}

In this example:

Seconds 10-15 are removed from video1 before combining
Videos are combined
Seconds 30-35 are removed from the final combined output

Per-File Audio Control

Disable audio from specific files while keeping audio from others:

// Create a montage: silent B-roll with main content audio
const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    combine: true,
    files: [
      {
        url: 'https://example.com/b-roll-intro.mp4',
        disableAudio: true  // Silent B-roll
      },
      {
        url: 'https://example.com/main-content.mp4'
        // Audio enabled (default)
      },
      {
        url: 'https://example.com/b-roll-outro.mp4',
        disableAudio: true  // Silent B-roll
      }
    ],
  }),
});

# Create a montage: silent B-roll with main content audio
response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'combine': True,
        'files': [
            {
                'url': 'https://example.com/b-roll-intro.mp4',
                'disableAudio': True  # Silent B-roll
            },
            {
                'url': 'https://example.com/main-content.mp4'
                # Audio enabled (default)
            },
            {
                'url': 'https://example.com/b-roll-outro.mp4',
                'disableAudio': True  # Silent B-roll
            }
        ],
    }
)

Combining with Other Features

Combine videos and apply other processing in one request:

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    combine: true,
    files: [
      { url: 'https://example.com/video1.mp4' },
      { url: 'https://example.com/video2.mp4' },
      { url: 'https://example.com/video3.mp4' }
    ],
    // Apply to combined output
    aspectRatio: '16:9',
    resizeMode: 'cover',
    normalizeAudio: true,
    compressionQuality: 95,
    outputFormat: 'mp4',
  }),
});

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'combine': True,
        'files': [
            {'url': 'https://example.com/video1.mp4'},
            {'url': 'https://example.com/video2.mp4'},
            {'url': 'https://example.com/video3.mp4'},
        ],
        # Apply to combined output
        'aspectRatio': '16:9',
        'resizeMode': 'cover',
        'normalizeAudio': True,
        'compressionQuality': 95,
        'outputFormat': 'mp4',
    }
)

Complete Example: Complex Combination

Here's a comprehensive example combining multiple features:

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    combine: true,
    files: [
      {
        url: 'https://example.com/intro.mp4',
        disableAudio: true,  // Silent intro
        removeSegments: [
          { startTime: 0, endTime: 2 }  // Remove first 2 seconds
        ]
      },
      {
        url: 'https://example.com/main-content.mp4',
        removeSegments: [
          { startTime: 45, endTime: 60 },  // Remove boring section
          { startTime: 120, endTime: 135 }  // Remove another section
        ]
      },
      {
        url: 'https://example.com/outro.mp4',
        disableAudio: true  // Silent outro
      }
    ],
    // Post-combination processing
    aspectRatio: '16:9',
    resizeMode: 'cover',
    normalizeAudio: true,
    compressionQuality: 95,
    outputFormat: 'mp4',
    webhookUrl: 'https://yourapp.com/webhooks/video-complete'
  }),
});

const data = await response.json();
console.log('Processing started:', data.videoId);

interface RemoveSegment {
  startTime: number;
  endTime: number;
}

interface FileInput {
  url: string;
  removeSegments?: RemoveSegment[];
  disableAudio?: boolean;
}

interface CombineRequest {
  combine: true;
  files: FileInput[];
  aspectRatio?: string;
  resizeMode?: 'cover' | 'contain' | 'stretch';
  normalizeAudio?: boolean;
  compressionQuality?: number;
  outputFormat?: 'mp4' | 'mov' | 'avi' | 'webm';
  webhookUrl?: string;
}

const request: CombineRequest = {
  combine: true,
  files: [
    {
      url: 'https://example.com/intro.mp4',
      disableAudio: true,
      removeSegments: [
        { startTime: 0, endTime: 2 }
      ]
    },
    {
      url: 'https://example.com/main-content.mp4',
      removeSegments: [
        { startTime: 45, endTime: 60 },
        { startTime: 120, endTime: 135 }
      ]
    },
    {
      url: 'https://example.com/outro.mp4',
      disableAudio: true
    }
  ],
  aspectRatio: '16:9',
  resizeMode: 'cover',
  normalizeAudio: true,
  compressionQuality: 95,
  outputFormat: 'mp4',
  webhookUrl: 'https://yourapp.com/webhooks/video-complete'
};

const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(request),
});

const data = await response.json();
console.log('Processing started:', data.videoId);

Best Practices

1. Use Matching Codecs

For fastest processing and no quality loss:

// All MP4 H.264 videos = stream copy optimization
files: [
  { url: 'https://example.com/video1.mp4' },
  { url: 'https://example.com/video2.mp4' },
  { url: 'https://example.com/video3.mp4' },
];

2. Pre-Process Segments

Remove unwanted segments from individual files:

files: [
  {
    url: 'https://example.com/video1.mp4',
    removeSegments: [{ startTime: 0, endTime: 5 }], // Remove intro
  },
  {
    url: 'https://example.com/video2.mp4',
    removeSegments: [{ startTime: 55, endTime: 60 }], // Remove outro
  },
];

3. Handle Audio Carefully

Use disableAudio for B-roll footage:

files: [
  { url: 'https://example.com/b-roll.mp4', disableAudio: true },
  { url: 'https://example.com/main-content.mp4' }, // Keep audio
];

4. Set High Compression Quality

Avoid quality degradation from re-encoding:

{
  combine: true,
  files: [ /* ... */ ],
  compressionQuality: 100  // Maximum quality
}

5. Use Webhooks for Long Processing

Get notified when combining completes:

{
  combine: true,
  files: [ /* ... */ ],
  webhookUrl: 'https://yourapp.com/webhooks/combine-complete'
}

Common Use Cases

Video Course Creation

Combine lecture segments with intros and outros:

{
  combine: true,
  files: [
    { url: 'https://example.com/course-intro.mp4' },
    { url: 'https://example.com/lecture-1.mp4' },
    { url: 'https://example.com/lecture-2.mp4' },
    { url: 'https://example.com/lecture-3.mp4' },
    { url: 'https://example.com/course-outro.mp4' }
  ],
  aspectRatio: '16:9',
  normalizeAudio: true
}

Create highlight reels from multiple clips:

{
  combine: true,
  files: [
    { url: 'https://example.com/clip1.mp4', removeSegments: [{ startTime: 0, endTime: 2 }] },
    { url: 'https://example.com/clip2.mp4', removeSegments: [{ startTime: 8, endTime: 10 }] },
    { url: 'https://example.com/clip3.mp4' }
  ],
  aspectRatio: '9:16',  // Vertical for TikTok/Reels
  resizeMode: 'cover',
  compressionQuality: 90
}

Podcast Video Creation

Combine interview segments with silent B-roll:

{
  combine: true,
  files: [
    { url: 'https://example.com/intro-broll.mp4', disableAudio: true },
    { url: 'https://example.com/interview-part1.mp4' },
    { url: 'https://example.com/transition-broll.mp4', disableAudio: true },
    { url: 'https://example.com/interview-part2.mp4' },
    { url: 'https://example.com/outro-broll.mp4', disableAudio: true }
  ],
  normalizeAudio: true,
  removeNoise: true
}

Segment Removal

Learn more about removing segments from videos

Audio Processing

Process audio while combining videos

Aspect Ratio

Change aspect ratio of combined output

Compression

Control quality and file size

Video Combining

Segment Removal

Audio Processing

Aspect Ratio

Compression

On this page