Postman Collection with 90 JSON video templates

Postman is an invaluable tool that helps developers design, document and test API's. We use it at Shotstack for testing endpoints. We also use it for designing, developing and testing JSON video edits.

We have created a public team and shared a large collection of JSON templates to the Postman web site. You can post the JSON templates to the API to render a video. You can use the collection to learn more about Shotstack and how it works. You can also use the examples as starting points for your own template designs.

Postman in the browser

You can view the Shotstack workspace on the Postman web site. The web site allows you to view and copy/paste JSON but you can not send requests from public collections. In order to send requests you will need to fork the Edit API collection. This guide will take you step by step through the process.

In this example we used the desktop client but the steps below will also work in the browser.

Get set up

If you already use Postman and have an account, you can skip this section. Otherwise create an account, then download the desktop software. Once installed open Postman and login.

Once installed and logged in you should see a welcome screen like below:

Fork the collection

Because you can not send requests in public collections we will need to create our own copy. Copying a collection is called forking (just like a Git repo).

First, search for shotstack in the search bar in the top center of the screen. In the results, click on the Shotstack text with a team icon (two heads) next to it:

The Shotstack team page will open showing our latest collections and workspace. The workspace contains one or more collections. We currently have 2 collections but in this guide we will only use the Edit API collection.

Click on Edit API under Latest collections section:

Click the fork icon as shown in the screenshot below:

Then fill out the form by entering a new name for the collection. Under Location chose My Workspace:

Once the collection is forked you should see all the available requests, organized in folders down the left hand side:

Authenticate

To send requests to the Shotstack API you will need to have an account and an API key. Each request needs to have the API key added to a header variable called x-api-key. Below we'll step through how to use the staging key and environment with Postman.

First, click on the eye icon next to the No Environment drop down and click Add:

The environment editor tab will open. You need to give the environment a name, we use Shotstack Stage Environment and then fill in Current and Initial values for the SHOTSTACK_API_KEY variable and enter stage for the ENV variable. See below how these variables are set up, including the API key:

Save and exit the environment config tab and make sure Shotstack Stage Environment is selected from the dropdown list.

Make a request

With the collection forked and our credentials added it is time to start making requests. There is a wide range of examples and templates that you can run and learn from.

A good example to start with is in the Basic Edits folder, called Basic Edit (Title, Image, Video). Open the folder and click on the request name, a tab will open up defaulting to the Params section:

The next section is the Authorization section. Authorization is already configured to use the API key you added to the environment. It sets the x-api-key header using the SHOTSTACK_API_KEY environment variable. This section is the same for every request and does not need to be changed:

Under the Tests section you can see a snippet of JavaScript:

pm.environment.set("RENDER_ID", pm.response.json().response.id);

This simply handles the response from the Shotstack API and sets an environment variable RENDER_ID with the ID in the response. This ID will be used later when we check the render status. This is all set up for you and you do not need to make any changes:

Finally, the Body section includes the JSON video edit. This is the description of the edit, the content and sequence of clips and assets. You can play modify the JSON to create a new video if you wish:

Click on Send when you are ready to create a video. Postman will send the JSON to the API with the API key and you will receive a response from the API like below:

Check the render status

When the response is received the RENDER_ID variable is populated ready to use in the Get status request. This endpoint is all set up, ready to use. Scroll to the bottom of the list on the left hand side and click on the Get status request.

Click Send to fetch the status of the video render. The response will give you the status of the render task. If done, a video url parameter will also be shown. If the video is still rendering, wait 10 seconds and try again:

View the video

In the get status response, you should see a response.url value. You can click on the URL and a new tab will open with the URL in the Request url field. Click Send and the video will download, once downloaded, the video can be played:

The collection contains examples on how to style text with HTML, position elements in the viewport, effects, transitions and filters. There are also some complete templates that you can copy and modify for your own applications.

We test and create new templates all the time so will keep adding new examples which will update in realtime in your Postman software.