Stitch Multiple Videos into One

You can combine a base video with additional video segments (also called video splicing) by defining specific insert timestamps or appending them at the end. This programmatic approach is ideal for building dynamic, automated video workflows - like generating post-game highlight reels, assembling personalized video feeds, or combining pre-roll and mid-roll content into a single video.

Endpoint for stitching

To stitch videos together, you can use both the create media from URL or  upload media from device  API endpoints.

All requests must be authenticated using HTTP Basic Auth with your FastPix Access Token and Secret Key.
See basic authentication guide to get your credentials.

Prepare your media files

Get the URLs for the following media files:

Base media: The main video URL or file (for device upload) where you want to merge other videos.
Media segments: Additional videos files already available in FastPix or in a public storage.

NOTE

The resolutions for video segments should be greater than or equal to the base video as FastPix does not support upscaling.

The frame rate of the video segments should be similar to the base video frame rate.

Create a JSON request to stitch media

To stitch a video, define the base media file in the url field and provide an array of segments inside the segments field. Each segment must be a separate media file.

Use insertAt for specific timestamps (in seconds), or insertAtEnd: true to append to the end of the base video.

FastPix processes the entire input and returns a new stitched video asset with a unique media ID and playback ID. The stitched media preserves all base media settings along with all segments added at their specified positions.

To stitch a media using a JSON request:

a. Create a new media from URL or directly upload it from the device.

b. Stitch segments in existing media

Create new media from URL

{
  "inputs": [
    {
      "type": "video",
      "url": "https://static.fastpix.io/fp-sample-video.mp4",
      "segments": [
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAt": 5
        },
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAt": 8
        },
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAtEnd": true
        }
      ]
    }
  ],
  "metadata": {
    "key1": "value1"
  },
  "accessPolicy": "public",
  "maxResolution": "1080p"
}

NOTE

You must specify either insertAt or insertAtEnd, but not both, for each segment.

Use the URL which is generated after uploading video to FastPix dashboard.

The resulting stitched media preserves all base media settings and then generates a new video with all segments added at their specified positions.

Create new media by direct upload (from device)

{
  "corsOrigin": "*",
  "pushMediaSettings": {
    "inputs": [
      {
        "segments": [
          {
            "url": "https://static.fastpix.io/fp-sample-video.mp4",
            "insertAt": 5
          },
          {
            "url": "https://static.fastpix.io/fp-sample-video.mp4",
            "insertAtEnd": true
          }
        ]
      }
    ],
    "accessPolicy": "public"
  }
}

Stitch segments in existing media

The process for stitching video segments from media uploaded from a device is similar to stitching segments from media created using a URL. The only difference is that instead of using a base video URL, you must use the mediaId of the existing media with the fp_mediaId:// prefix.

NOTE

A new media always gets created when video segments stitched to an existing media.

{
  "inputs": [
    {
      "type": "video",
      "url": "fp_mediaId://7271d4de-e83c-431c-8aea-896c55f52645",
      "segments": [
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAt": 5
        },
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAt": 8
        },
        {
          "url": "https://static.fastpix.io/fp-sample-video.mp4",
          "insertAtEnd": true
        }
      ]
    }
  ],
  "accessPolicy": "public"
}

Example response

A successful request returns a stitched media asset with its own unique media ID and a list of playback IDs. You can now stream the new stitched video using the provided playback ID.

{
  "success": true,
  "data": {
    "id": "fe3513a0-e8d0-4184-9cf6-8c5d444643a7",
    "trial": true,
    "status": "Created",
    "createdAt": "2025-11-03T05:52:51.645120Z",
    "updatedAt": "2025-11-03T05:52:51.645143Z",
    "playbackIds": [
      {
        "id": "a844c856-85ae-4edb-acf0-1e483a14f2fa",
        "accessPolicy": "public",
        "accessRestrictions": {
          "domains": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          },
          "userAgents": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          }
        }
      }
    ],
    "metadata": {
      "key1": "value1"
    },
    "sourceAccess": false,
    "maxResolution": "1080p",
    "inputs": [
      {
        "type": "video",
        "url": "https://static.fastpix.io/fp-sample-video.mp4",
        "segments": [
          {
            "url": "https://static.fastpix.io/fp-sample-video.mp4",
            "insertAt": 5
          },
          {
            "url": "https://static.fastpix.io/fp-sample-video.mp4",
            "insertAt": 8
          },
          {
            "url": "https://static.fastpix.io/fp-sample-video.mp4",
            "insertAtEnd": true
          }
        ]
      }
    ],
    "subtitles": {},
    "optimizeAudio": false
  }
}

Webhook event for status

You can register a webhook to receive an event when stitching is complete. How to setup webhooks?

Event: video.media.splicing.ready

{
  "type": "video.media.splicing.ready",
  "object": {
    "type": "media",
    "id": "3be43075-58ea-4a81-9bf2-bbed98527f8c"
  },
  "id": "ac6d1548-8fe9-4099-94ec-662865997db0",
  "workspace": {
    "name": "Development",
    "id": "fd717af6-a383-4739-8d8c-b49aa732a8c0"
  },
  "status": "ready",
  "data": {
    "thumbnail": "https://images.fastpix.io/21f05e1e-64ec-481e-b81d-93de708075ce/thumbnail.png",
    "id": "3be43075-58ea-4a81-9bf2-bbed98527f8c",
    "workspaceId": "fd717af6-a383-4739-8d8c-b49aa732a8c0",
    "metadata": {
      "key1": "value1"
    },
    "maxResolution": "480p",
    "sourceResolution": "480p",
    "playbackIds": [
      {
        "id": "21f05e1e-64ec-481e-b81d-93de708075ce",
        "accessPolicy": "public",
        "accessRestrictions": {
          "domains": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          },
          "userAgents": {
            "defaultPolicy": "allow",
            "allow": [],
            "deny": []
          }
        }
      }
    ],
    "tracks": [
      {
        "id": "adffd041-60ae-4403-8da9-42f52c0a4412",
        "type": "audio",
        "status": "available",
        "languageCode": "und",
        "languageName": "default"
      },
      {
        "id": "d76025bf-4c79-4e4f-9f8b-45365b4eb5df",
        "type": "video",
        "width": 640,
        "height": 360,
        "frameRate": "24000/1001",
        "status": "available"
      }
    ],
    "sourceAccess": false,
    "mp4Support": "none",
    "optimizeAudio": false,
    "duration": "00:10:17",
    "aspectRatio": "16:9",
    "createdAt": "2025-04-07T09:44:52.611387Z",
    "updatedAt": "2025-04-07T09:45:57.667316Z"
  },
  "createdAt": "2025-04-07T09:45:57.686231637Z",
  "attempts": []
}