merge()

Combine multiple media items (videos, images, audio) into a single video.

import { compose, merge } from "@synthome/sdk";

const execution = await compose(
  merge([
    "https://example.com/intro.mp4",
    "https://example.com/main.mp4",
    "https://example.com/outro.mp4",
  ]),
).execute();

Basic Usage

Merge Videos

Combine videos sequentially:

merge([
  "https://example.com/video1.mp4",
  "https://example.com/video2.mp4",
  "https://example.com/video3.mp4",
]);

Image Slideshow

Create a video from images (default 1 second per image):

merge([
  "https://example.com/photo1.jpg",
  "https://example.com/photo2.jpg",
  "https://example.com/photo3.png",
]);

Custom Image Duration

Control how long each image displays:

merge([
  { url: "https://example.com/title.jpg", duration: 3 },
  { url: "https://example.com/content.jpg", duration: 5 },
  { url: "https://example.com/credits.png", duration: 2 },
]);

Adding Audio

Background Music

Add audio that plays throughout the video:

merge([
  "https://example.com/video.mp4",
  { url: "https://example.com/music.mp3", offset: 0 },
]);

Audio with Offset

Start audio at a specific time:

merge([
  "https://example.com/intro.mp4",
  "https://example.com/main.mp4",
  { url: "https://example.com/narration.mp3", offset: 5 }, // Starts at 5 seconds
]);

Volume Control

Adjust audio levels:

merge([
  { url: "https://example.com/video.mp4", volume: 0.3 }, // Reduce video audio
  { url: "https://example.com/music.mp3", volume: 0.8 }, // Background music
]);

With Generated Content

Merge Generated Videos

Combine AI-generated videos:

import { compose, merge, generateVideo, videoModel } from "@synthome/sdk";

const execution = await compose(
  merge([
    generateVideo({
      model: videoModel("bytedance/seedance-1-pro", "replicate"),
      prompt: "A sunrise over mountains",
    }),
    generateVideo({
      model: videoModel("bytedance/seedance-1-pro", "replicate"),
      prompt: "Birds flying across the sky",
    }),
  ]),
).execute();

Videos are generated in parallel, then merged sequentially.

Mix URLs and Generated Content

merge([
  "https://example.com/intro.mp4", // Existing intro
  generateVideo({
    model: videoModel("minimax/video-01", "replicate"),
    prompt: "Product showcase",
  }),
  "https://example.com/outro.mp4", // Existing outro
]);

Generated Content with Options

merge([
  {
    url: generateVideo({
      model: videoModel("bytedance/seedance-1-pro", "replicate"),
      prompt: "Scene 1",
    }),
    duration: 5, // Trim to 5 seconds
  },
  {
    url: generateImage({
      model: imageModel("google/nano-banana", "replicate"),
      prompt: "Title card",
    }),
    duration: 3,
  },
  {
    url: generateAudio({
      model: audioModel("elevenlabs/turbo-v2.5", "elevenlabs"),
      text: "Welcome to our video",
    }),
    offset: 0,
    volume: 1,
  },
]);

Mixed Media

Video + Images + Audio

merge([
  "https://example.com/intro.mp4",
  { url: "https://example.com/title.png", duration: 2 },
  "https://example.com/main.mp4",
  { url: "https://example.com/credits.jpg", duration: 3 },
  { url: "https://example.com/soundtrack.mp3", offset: 0, volume: 0.5 },
]);

Type Detection

Media type is auto-detected from file extensions:

Type	Extensions
Video	`.mp4`, `.mov`, `.webm`, `.avi`
Image	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
Audio	`.mp3`, `.wav`, `.aac`, `.ogg`, `.m4a`

Override auto-detection when needed:

merge([{ url: "https://cdn.example.com/media/abc123", type: "video" }]);

Output Dimensions & Aspect Ratio

Custom Output Size

Specify the output dimensions:

merge(["https://example.com/video1.mp4", "https://example.com/video2.mp4"], {
  outputWidth: 1920,
  outputHeight: 1080,
});

Convert to Vertical (9:16)

Convert horizontal videos to vertical format for social media:

// Letterbox (default) - adds black bars
merge(["https://example.com/landscape-video.mp4"], {
  outputWidth: 1080,
  outputHeight: 1920,
  fillMode: "fit",
});

// Crop to fill - no black bars, crops edges
merge(["https://example.com/landscape-video.mp4"], {
  outputWidth: 1080,
  outputHeight: 1920,
  fillMode: "fill",
});

Fill Mode Comparison

Mode	Behavior	Use Case
`fit`	Scale to fit, add black bars if needed	Preserve all content, letterboxing OK
`fill`	Scale to cover, crop overflow (centered)	Full-frame video, cropping OK

API Reference

merge(items, options?)

Parameter	Type	Description
`items`	`MergeItem[]`	Array of media items
`options`	`MergeOptions?`	Optional output configuration

MergeOptions

Property	Type	Description
`outputWidth`	`number`	Output width in pixels. Defaults to first video's width
`outputHeight`	`number`	Output height in pixels. Defaults to first video's height
`fillMode`	`"fit" \| "fill"`	How to handle aspect ratio mismatches (default: `"fit"`)

Fill modes:

"fit" (default): Letterbox - scale to fit inside frame, add black bars if aspect ratio differs
"fill": Crop to cover - scale to fill entire frame, crop overflow (centered, no black bars)

MergeItem

Can be one of:

string - URL (type auto-detected)
MergeOperation - Generated content
MergeItemWithOptions - URL or operation with options

MergeItemWithOptions

Property	Type	Description
`url`	`string \| MergeOperation`	URL or generated content
`type`	`"video" \| "image" \| "audio"`	Override auto-detection
`duration`	`number`	Video: trim duration. Image: display duration
`offset`	`number`	Audio only: start position in seconds
`volume`	`number`	Volume level 0-1 (default: 1)

Merge

On this page