> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fastpix.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server. # Merge and stitch videos 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](/video-on-demand-api/upload-and-import-videos/create-media) or  [upload media from device](/video-on-demand-api/upload-and-import-videos/direct-upload-video-media)  API endpoints. All requests must be authenticated using HTTP Basic Auth with your FastPix Access Token and Secret Key.\ See [basic authentication](/getting-started/activate-your-account#get-your-access-token-id-and-secret-key) guide to get your credentials. \ ## Prepare your media files 1. 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](/video-on-demand/merge-and-stitch-videos#create-new-media-from-url) or [directly upload it from the device](/video-on-demand/merge-and-stitch-videos#create-new-media-by-direct-upload-from-device). b. [Stitch segments in existing media](/video-on-demand/merge-and-stitch-videos#stitching-segments-in-existing-media) \ ### Create new media from URL **`Request body`** ```json Request body { "inputs": [ { "type": "video", "url": "https://static.fastpix.com/fp-sample-video.mp4", "segments": [ { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 5 }, { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 8 }, { "url": "https://static.fastpix.com/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) **`Request body`** ```json Request body { "corsOrigin": "*", "pushMediaSettings": { "inputs": [ { "segments": [ { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 5 }, { "url": "https://static.fastpix.com/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. \ **`Request body`** ```json Request body { "inputs": [ { "type": "video", "url": "fp_mediaId://7271d4de-e83c-431c-8aea-896c55f52645", "segments": [ { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 5 }, { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 8 }, { "url": "https://static.fastpix.com/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. \ **`Response`** ```json Response { "success": true, "data": { "id": "c1010eb9-864b-42e8-998e-086eb5ebd5e8", "sourceMediaId": "91ac0984-97a8-44cf-b89a-48c6b7be1c67", "trial": false, "status": "Created", "createdAt": "2025-12-23T13:06:08.672278Z", "updatedAt": "2025-12-23T13:06:08.672290Z", "playbackIds": [ { "id": "dcafc942-f1b5-4278-89d8-e49cda194dd1", "accessPolicy": "public", "accessRestrictions": { "domains": { "defaultPolicy": "allow", "allow": [], "deny": [] }, "userAgents": { "defaultPolicy": "allow", "allow": [], "deny": [] } } } ], "mediaQuality": "standard", "title": "91ac0984-97a8-44cf-b89a-48c6b7be1c67", "sourceAccess": false, "maxResolution": "1080p", "inputs": [ { "type": "video", "url": "fp_mediaId://91ac0984-97a8-44cf-b89a-48c6b7be1c67", "segments": [ { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 5 }, { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAt": 8 }, { "url": "https://static.fastpix.com/fp-sample-video.mp4", "insertAtEnd": true } ] } ], "optimizeAudio": false } } ``` \ ## Webhook event for status You can register a webhook to receive an event when stitching is complete. [How to setup webhooks?](/webhooks/set-up-webhooks) Event: [`video.media.splicing.ready`](/webhooks/transform-media-events#videomediasplicingready) \ **`Sample webhook payload`** ```json Sample webhook payload { "type": "video.media.splicing.ready", "object": { "type": "media", "id": "c1010eb9-864b-42e8-998e-086eb5ebd5e8" }, "id": "b891bd97-21bd-456c-a1d3-843e2fc59a05", "workspace": { "name": "Test", "id": "b7bea348-c6b0-4c7b-b25f-1cf3ee65e5c3" }, "status": "ready", "data": { "thumbnail": "https://images.fastpix.com/dcafc942-f1b5-4278-89d8-e49cda194dd1/thumbnail.png", "id": "c1010eb9-864b-42e8-998e-086eb5ebd5e8", "workspaceId": "b7bea348-c6b0-4c7b-b25f-1cf3ee65e5c3", "mediaQuality": "standard", "maxResolution": "1080p", "sourceResolution": "1080", "sourceAccess": false, "mp4Support": "none", "optimizeAudio": false, "duration": "00:00:40", "aspectRatio": "16:9", "createdAt": "2025-12-23T13:06:08.672278Z", "updatedAt": "2025-12-23T13:07:25.045991Z" }, "createdAt": "2025-12-23T13:07:25.101336483Z", "attempts": [] } ```