Introducing Shotstack Template Endpoint

Shotstack is excited to announce the new template API endpoints. These endpoints provide developers with the ability to save video templates and easily render large volumes of video. In addition, by using merge fields you can now render thousands of video variations.

The addition of the templates API endpoints will provide developers with the ability to easily reference templates edited in the Template Editor and simplify the process of rendering video at scale.

In addition to the endpoints this functionality is also available across all of our SDKs and on our Make and Zapier apps.

Create a dynamic template

We will be creating a video where we want three elements in our template to be replaced with data from our merge field:

You can create a dynamic template in two ways:

  1. Via the Shotstack Studio
  2. Via the API

Creating a template inside of the Shotstack Studio

You can use the Shotstack Studio to manage your templates. The studio allows you to create templates and edit these inside of the Template Editor.

Shotstack Studio

Create new template

To create a new template click on the Create Template button. This will take you to the JSON Template Editor and provide you with some boilerplate code.

If you want to learn more about the Shotstack JSON specification please take a look through our Hello World guide.

For this example we will start with a simple template, but you can find more elaborate designs on the Shotstack Templates page.

Add merge fields

You can add merge fields to your video which act as variables to produce variations on your template. You add merge fields by using double handlebars {{...}} .

Copy over the following JSON into your editor, name your template and click the Save button.

This template includes three merge fields:

  1. {{street}}
  2. {{suburb}}
  3. {{image}}
{
"timeline": {
"fonts": [
{
"src": "https://templates.shotstack.io/basic/asset/font/manrope-extrabold.ttf"
},
{
"src": "https://templates.shotstack.io/basic/asset/font/manrope-light.ttf"
}
],
"background": "#000000",
"tracks": [
{
"clips": [
{
"asset": {
"type": "html",
"html": "<p>{{street}}</p>",
"css": "p { font-family: \"Manrope ExtraBold\"; color: #f0c20c; font-size: 40px; text-align: left; line-height: 78; }",
"width": 320,
"height": 200,
"position": "bottom"
},
"start": 1.2,
"length": 4.2,
"position": "left",
"offset": {
"x": 0.05,
"y": 0.25
},
"transition": {
"in": "slideRight",
"out": "slideLeft"
}
},
{
"asset": {
"type": "html",
"html": "<p>{{suburb}}</p>",
"css": "p { font-family: \"Manrope Light\"; color: #ffffff; font-size: 22px; text-align: left; line-height: 78; }",
"width": 320,
"height": 66,
"position": "top"
},
"start": 1.3,
"length": 3.9,
"position": "left",
"offset": {
"x": 0.05,
"y": 0.015
},
"transition": {
"in": "slideRight",
"out": "slideLeft"
}
}
]
},
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://templates.shotstack.io/basic/asset/video/overlay/arrow-sharp/black/content-left-in.mov"
},
"start": 0,
"length": 4.48
},
{
"asset": {
"type": "video",
"src": "https://templates.shotstack.io/basic/asset/video/overlay/arrow-sharp/black/content-left-out.mov"
},
"start": 4.52,
"length": 2
}
]
},
{
"clips": [
{
"asset": {
"type": "image",
"src": "{{image}}"
},
"start": 0,
"length": 6,
"effect": "zoomInSlow",
"transition": {
"in": "fade"
}
}
]
}
]
},
"output": {
"format": "mp4",
"resolution": "sd"
}
}

Creating a template via the Templates API Endpoint

You can also create templates via the API. You do this by saving your template to template.json and sending a POST request to https://api.shotstack.io/{version}/templates. Make sure to replace environment tp either stage or v1 depending on whether you are using the sandbox or production environment.

To save your template you need to provide the API with a name of your template and the template contents. To easily reference the JSON let's save the below JSON to template.json.

{
"name": "Real Estate Listing Video",
"template": {
"timeline": {
"fonts": [{
"src": "https://templates.shotstack.io/basic/asset/font/manrope-extrabold.ttf"
},
{
"src": "https://templates.shotstack.io/basic/asset/font/manrope-light.ttf"
}
],
"background": "#000000",
"tracks": [{
"clips": [{
"asset": {
"type": "html",
"html": "<p></p>",
"css": "p { font-family: \"Manrope ExtraBold\"; color: #f0c20c; font-size: 40px; text-align: left; line-height: 78; }",
"width": 320,
"height": 200,
"position": "bottom"
},
"start": 1.2,
"length": 4.2,
"position": "left",
"offset": {
"x": 0.05,
"y": 0.25
},
"transition": {
"in": "slideRight",
"out": "slideLeft"
}
},
{
"asset": {
"type": "html",
"html": "<p></p>",
"css": "p { font-family: \"Manrope Light\"; color: #ffffff; font-size: 22px; text-align: left; line-height: 78; }",
"width": 320,
"height": 66,
"position": "top"
},
"start": 1.3,
"length": 3.9,
"position": "left",
"offset": {
"x": 0.05,
"y": 0.015
},
"transition": {
"in": "slideRight",
"out": "slideLeft"
}
}
]
},
{
"clips": [{
"asset": {
"type": "video",
"src": "https://templates.shotstack.io/basic/asset/video/overlay/arrow-sharp/black/content-left-in.mov"
},
"start": 0,
"length": 4.48
},
{
"asset": {
"type": "video",
"src": "https://templates.shotstack.io/basic/asset/video/overlay/arrow-sharp/black/content-left-out.mov"
},
"start": 4.52,
"length": 2
}
]
},
{
"clips": [{
"asset": {
"type": "image",
"src": ""
},
"start": 0,
"length": 6,
"effect": "zoomInSlow",
"transition": {
"in": "fade"
}
}]
}
]
},
"output": {
"format": "mp4",
"resolution": "sd"
}
}
}

We can now send a POST request to https://api.shotstack.io/v1/templates. Make sure to reference your template.json file.

curl -X POST https://api.shotstack.io/v1/templates \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: PROD_API_KEY'
-d @template.json

The API will respond with a response similar to the following:

{
"success": true,
"message": "Created",
"response": {
"message": "Template Successfully Created",
"id": "f5493c17-d01f-445c-bb49-535fae65f219"
}
}

Rendering videos from your template

Now that you have saved your template you can start rendering thousands of videos by sending POST requests to the Shotstack API.

Render your template via the API

You can render your template and adjust the merge fields by referencing your template ID and adding a merge array. You can find your template ID in your template list. Now save the below JSON with your template ID to a file called merge.json.

{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"merge": [
{
"find": "street",
"replace": "19 BONNET AVENUE"
},
{
"find": "suburb",
"replace": "COMO NSW 2223"
},
{
"find": "image",
"replace": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/images/realestate1.jpg"
}
]
}

Now send a POST request to https://api.shotstack.io/{environment}/templates/render making sure to attach merge.json and replacing environment with either v1 or stage.

curl -X POST https://api.shotstack.io/v1/templates/render \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: PROD_API_KEY'
-d @merge.json

You should now receive a response similar to the below indicating that your video has been successfully queued for rendering:

{
"success": true,
"message": "Created",
"response": {
"message": "Render Successfully Queued",
"id": "3e092919-ab42-4a73-adcf-2eb728272481"
}
}

In this guide we created a template, sent it merge fields and output the final video. This guide can be used as a starting point to build a wide range of video generating apps such as through the use of forms, databases or other APIs.

We look forward seeing how you will use it.

Derk Zomer

BY DERK ZOMER
30th July, 2022

Become an Automated Video Editing Pro

Every month we share articles like this one to keep you up to speed with automated video editing.


Related articles

JSON template editor launched

JSON template editor launched

The JSON template editor lets you edit and render videos in the dashboard.

Derk Zomer
Personalize videos using merge fields

Personalize videos using merge fields

How to use merge fields to create personalized videos using JSON, PHP, Node or Ruby.

Derk Zomer
Postman Collection with 90 video templates

Postman Collection with 90 video templates

How to use the Shotstack API public Postman Collection of video editing templates.

Jeff Shillitto