Hello World - edit your first video using the Shotstack API

Shotstack is a cloud based video editing platform. A REST API is used to describe a video edit sequence and a server based rendering service is used to render hundreds of videos concurrently.

This is the obligatory 'Hello World' guide that every programming language, framework and platform requires.

In this tutorial we will walk you through creating your first video using titles, a video clip, a soundtrack plus a few tips to give your video that final polish.

The basics

Before diving in and writing any code it is a good idea to acquaint yourself with some basic video editing principles and how these relate to Shotstacks JSON video editing format.

An edit in Shotstack is essentially a JSON file describing how assets such as titles, video clips and images are arranged to create a video.

Timeline

The timeline represents the entire duration of your video in seconds. For example, a 30 second video edit would have a 30 second timeline. Clips are placed along the timeline via a track.

Tracks

A track runs for the entire duration of the timeline and is used to layer clips on top of each other, for example, layer text on top of an image or video clip. You can place multiple tracks on top of each other.

Clips

Clips are placeholders for assets (titles, images, videos) and are positioned on the timeline (via a track) at specific time intervals. For example, you could add a clip that starts playing at the 5th second until the 10th second. You can also apply transitions, filters, and motion effects to the clip.

Assets

When creating a clip, you specify the type of asset to be displayed such as a text title, image or a video clip. Each asset has options specific to its type, for example, a title will have a type style and video might have a trim point to cut the start and end of the clip.

Output

The output specifies the final render properties, the platform supports mp4 video files and gifs in a range of resolutions such as HD, SD and mobile.

If this does not all make sense yet, it will all become clearer once we create a few examples.

Getting setup

Signup for API keys

In order to use the API you will need an API key. The API is free to use by developers so that you can learn, experiment, and develop applications. Sign up or login via the Shotstack website to receive a developer key.

Curl vs Postman

This tutorial presumes a basic knowledge of interacting with API's and using the command line. The examples use Curl but if you are familiar with Postman you can use the JSON, credentials and endpoints to achieve the same results.

To check Curl is installed, type the command in your terminal or command prompt:

curl --version

If successful you should see a response like:

curl 7.64.0 (x86_64-pc-linux-gnu) libcurl/7.64.0 OpenSSL/1.1.1b zlib/1.2.11 libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) libssh/0.8.6/openssl/zlib nghttp2/1.36.0 librtmp/2.3
Release-Date: 2019-02-06
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp 
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy PSL

Curl is installed on most modern operating systems including Windows 10, Linux and OS X. If it is not available, install via your OS package manager or download from the Curl website.

Your first edit

Let's create a very simple Hello World title video.

Create a text file called hello.json with the following:

{
  "timeline": {
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future"
            },
            "start": 0,
            "length": 5
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

In the JSON above we specify a timeline with a black background, a track with a single clip which plays for 5 seconds and uses a title asset with the text 'Hello World'. The output is specified as an mp4 video with SD resolution.

Now post the edit to the API for rendering by running the command below:

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

Make sure you replace the x-api-key parameter value above with your own staging key. Make sure you use the staging key and not the production key.

You should see a response similar to:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655"
  }
}

Copy the response id returned by the API as we will need it in the next step.

To check the status of the render run the following command, replacing the id at the end of the URL:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
  https://api.shotstack.io/stage/render/d2b46ed6-998a-4d6b-9d91-b8cf0193a655

Be sure to replace d2b46ed6-998a-4d6b-9d91-b8cf0193a655 with the id returned by the API.

The video should only take a few seconds to render. Once it is ready the response will show a status of done and include a URL to the final video file:

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655",
    "owner": "hckwccw3q3",
    "plan": "sandbox",
    "status": "done",
    "url": "https://s3-ap-southeast-2.amazonaws.com/shotstack-api-stage-output/hckwccw3q3/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4",
    "data": {
      "output": {...},
      "timeline": {...}
    },
    "created": "2019-04-16T12:02:42.148Z",
    "updated": "2019-04-16T12:02:51.867Z"
  }
}

If the status is not done (it might show queued, rendering, saving, fetching, or failed), then wait a few seconds and run the command again.

Once completed you can copy the URL and open it in your browser. You should see a simple 5 second video with the words 'Hello World' on a black background.

Congratulations, you have created your first video using the Shotstack API.

It is obviously a little bit boring so let's add a soundtrack and a background video.

Adding a video clip and soundtrack

Replace the contents of hello.json so that it looks like this:

{
  "timeline": {
    "soundtrack": {
      "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/freepd/motions.mp3"
    },
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future"
            },
            "start": 0,
            "length": 15
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/earth.mp4"
            },
            "start": 0,
            "length": 15
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "1080"
  }
}

In this example you can see that a new soundtrack motions.mp3 file has been added and as a second track with a video asset and a video file earth.mp4. The title and video clip have a length of 15 seconds.

It is important to note that the track with the video is below the track with text so that the text is rendered on top of the video file and not hidden underneath it.

Go ahead and use the previous Curl commands to post the video and check the status. You should end up with a video like below:

The video is now a lot more interesting, but it could still do with a bit of refinement to give it a more professional touch.

Adding the final touches to our edit

To add some final polish, we will reposition and resize the title and fade in and out the clips and soundtrack.

Replace the hello.json file with the following and post it to the API using the Curl command and check its status.

{
  "timeline": {
    "soundtrack": {
      "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/freepd/motions.mp3",
      "effect": "fadeOut"
    },
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future",
              "position": "left",
              "size": "x-small"
            },
            "start": 4,
            "length": 11,
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "effect": "zoomIn"
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/earth.mp4",
              "trim": 5
            },
            "start": 0,
            "length": 15,
            "transition": {
              "in": "fade",
              "out": "fade"
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

In the edit above we have made several small changes including:

• fadeOut effect on the soundtrack
• fade in and fade out added to the title and video clip
• position the title to the left and resize smaller
• display the title after 4 seconds in time to the music
• add a zoomIn motion effect to the title
• trim the first 5 seconds off the start of the video clip

The result is below:

Next steps

This tutorial should give you a basic grounding in how the Shotstack API works and some of the core features used to programmatically generate videos.

Of course, using Curl on the command line is not practical when building applications but because the API uses JSON you can use the programming language of your choice.

Our API reference documentation will introduce you to all the available functionality and to help you get started we have examples
on GitHub using PHP and NodeJS.