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.

Step 1: Prepare your media files

Gather 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.

PLEASE 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.

Step 2: Create a JSON request to stitch media

To stitch a video, define the base media file using 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 will preserve all base media settings along with all segments added at their specified positions.

Creating new media from URL

{
  "inputs": [
    {
      "type": "video",
      "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
      "segments": [
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 5
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 10
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAtEnd": true
        }
      ]
    }
  ],
  "metadata": {
    "key1": "value1"
  },
  "accessPolicy": "public",
  "maxResolution": "1080p"
}

PLEASE NOTE

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

The resulting stitched media will preserve all base media settings and generate a new video with all segments added at their specified positions.

Creating new media by direct upload (from device)

{
  "corsOrigin": "*",
  "pushMediaSettings": {
    "inputs": [
      {
        "segments": [
          {
            "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
            "insertAt": 5
          },
          {
            "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
            "insertAtEnd": true
          }
        ]
      }
    ],
    "accessPolicy": "public"
  }
}

Stitching segments in existing media

You can to use only create media from URL endpoint to stitch video segments in any existing media already available in FastPix. You can follow a similar process here, just that in place of the base video URL – you have to use the mediaId of the existing media with fp_mediaId:// prefix.

PLEASE NOTE

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

{
  "inputs": [
    {
      "type": "video",
      "url": "fp_mediaId://7271d4de-e83c-431c-8aea-896c55f52645",
      "segments": [
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 5
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 10
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAtEnd": true
        }
      ]
    }
  ],
  "accessPolicy": "public"
}

Example response

A successful request will return 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.

{
  "id": "3be43075-58ea-4a81-9bf2-bbed98527f8c",
  "trial": false,
  "status": "Created",
  "createdAt": "2025-04-07T09:44:52.611387Z",
  "updatedAt": "2025-04-07T09:44:52.611395Z",
  "playbackIds": [
    {
      "id": "21f05e1e-64ec-481e-b81d-93de708075ce",
      "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://storage.fastpix.net/media/test/Lionking.mp4",
      "segments": [
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 5
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.mp4",
          "insertAt": 10
        },
        {
          "url": "https://storage.fastpix.net/media/test/Lionking.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": []
}