Merge videos using the Edit API

The basic principle of video editing is to organize and arrange different video clips into a sequence that forms a coherent narrative or story. With the advent of computers and video editing software this is easily achieved by merging or stitching multiple video clips together in the order you want.

While software like Adobe Premiere or Apple iMovie make this manageable for individual video edits, doing this programmatically or at any kind of scale requires an automated solution which is where the Shotstack video editing API can be used.

Merge videos with the Shotstack API

The Shotstack video editing API makes automated video merging a simple process using an easy to understand JSON specification that is compatible with most programing languages.

Merging videos using the Shotstack API is similar to the way videos are stitched in a timeline based editor with a start position on a timeline and length. To merge clips together you simply set the next clip in the sequence to start when the previous clip finishes.

Below we will explain exactly how to do this but if this is your first time using the Shotstack API you can check out the basics in our hello world tutorial. You will also need to register for an API key and access to the free to use, developer sandbox.

Merge video clips using JSON

Shotstack is a RESTful API that accepts JSON describing the sequence of clips you want to edit in to a video. To demonstrate the basics we will merge three clips together and POST the edit to the API. The API will download the video clips from the URLs provided and stitch them together.

We'll prepare a JSON edit that will merge 3 clips together one after another. The following video clips have already been uploaded to our S3 storage account ready to use in our edit:

Create a file named merge.json and add the following JSON to it:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/shore-overhead.mp4"
            },
            "start": 0,
            "length": 19
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/cliffs-sunset.mp4"
            },
            "start": 19,
            "length": 8
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/tree.mp4"
            },
            "start": 27,
            "length": 16
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

If you look at the JSON above you can see each video is added as a clip with a start and length. The start of each clip is either 0 (the beginning of the video), or the end of the previous clip.

Post the JSON to the API

To render the video we'll use a cURL command to post the JSON to the Shotstack API for processing. Replace YOUR_API_KEY with your own API key:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @concat.json \
  https://api.shotstack.io/stage/render

You'll get a response back containing JSON data that has a response.id key, as shown below:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "084f4fa1-e59c-49cb-8a60-b95eddbdc497"
  }
}

Get the video render status

Copy the id and make another cURL request, replacing RESPONSE_ID with the id and YOUR_API_KEY with your key:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.shotstack.io/stage/render/RESPONSE_ID

After making the above call, once the video has completed rendering (the status will equal done), you should get a response containing JSON data that has a response.url key:

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "084f4fa1-e59c-49cb-8a60-b95eddbdc497",
    "owner": "hwgdrr9fe2",
    "plan": "sandbox",
    "status": "done",
    "error": "",
    "duration": 43,
    "billable": 43,
    "renderTime": 31585.79,
    "url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/hwgdrr9fe2/084f4fa1-e59c-49cb-8a60-b95eddbdc497.mp4",
    "thumbnail": null,
    "created": "2021-09-25T04:01:56.360Z",
    "updated": "2021-09-25T04:02:29.486Z"
  }
}

The merged video clip

Open the url in a browser to view the video or you can download the video using wget or cURL. You should see the individual videos merged in to a single video:

Merging and trimming videos

With the ability to merge clips together you can edit videos to tell your story, market your products and update your customers. One concept missing from this tutorial is trimming video clips.

Trimming the source footage lets you extract highlights or get rid of unwanted sections. Learn how in our trim video tutorial.