Templates

Shotstack templates provide a way to save an edit that you want to re-use at a later date. A template can also be saved with placeholders using double curly braces (handlebars), like {{ FIRST_NAME }}. These placeholders can be replaced with real values when the video is rendered.

A template can be rendered using it's ID and an array of merge fields that replace the placeholders at render time.

Create a template

To create a template you POST an edit to the templates endpoint:

POST https://api.shotstack.io/{{ENV}}/templates/

Where {{ENV}} is the environment you are working with, for example stage or v1.

The following cURL request will create a template in the stage environment. The video src and length use placeholder values {{ URL }} and {{ DURATION }}. The place holders can be replaced when rendering using merge fields.

curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "name": "Basic test template",
    "template": {
        "timeline": {
            "tracks": [
                {
                    "clips": [
                        {
                            "asset": {
                                "type": "video",
                                "src": "{{ URL }}"
                            },
                            "start": 0,
                            "length": "{{ DURATION }}"
                        }
                    ]
                }
            ]
        },
        "output": {
            "format": "mp4",
            "resolution": "sd"
        }
    }
}' \
     https://api.shotstack.io/stage/templates/

The POST request should return a JSON payload that includes the the template ID; response.id:

{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Template Successfully Created",
        "id":"ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641"
    }
}

Retrieve a template

You can retrieve a template using the following endpoint:

GET https://api.shotstack.io/{{ENV}}/templates/{{ID}}

The following cURL request retrieves the template we just created:

curl -X GET \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     https://api.shotstack.io/stage/templates/ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641

The response should look like:

{
    "success": true,
    "message": "OK",
    "response": {
        "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
        "name": "Basic test template",
        "owner": "5ca6hu7s9k",
        "template": {
            "timeline": {
                "tracks": [
                    {
                        "clips": [
                            {
                                "asset": {
                                    "type": "video",
                                    "src": "{{ URL }}"
                                },
                                "start": 0,
                                "length": "{{ DURATION }}"
                            }
                        ]
                    }
                ]
            },
            "output": {
                "format": "mp4",
                "resolution": "sd"
            }
        }
    }
}

Retrieve a list of all templates

You can retrieve a list of template using the following endpoint:

GET https://api.shotstack.io/{{ENV}}/templates/

The following cURL request returns all templates created in the stage environment:

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

The response should include a list of all templates:

{
    "success": true,
    "message": "OK",
    "response": {
        "owner": "5ca6hu7s9k",
        "templates": [
            {
                "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
                "name": "Basic test template",
                "created": "2022-12-20T12:24:44.650Z",
                "updated": "2022-12-20T12:24:44.451Z"
            },
            {
                "id": "17eff444b-b0f4-8a91-8fcc-7423ef711060",
                "name": "Another template",
                "created": "2022-12-19T22:37:39.287Z",
                "updated": "2022-12-20T03:57:59.827Z"
            },
            {
                "id": "e63874c58-3a62-3c98-8942-2bb70cad3ba9",
                "name": "Hello world template",
                "created": "2022-10-03T07:10:46.125Z",
                "updated": "2022-12-20T03:57:25.865Z"
            }
        ]
    }
}

Update an existing template

To update and overwrite an existing template use the following endpoint:

PUT https://api.shotstack.io/{{ENV}}/templates/{{ID}}

The following cURL request updates the template we created earlier and adds a {{ TRIM }} placeholder and changes the resolution to hd:

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "name": "Basic test template",
    "template": {
        "timeline": {
            "tracks": [
                {
                    "clips": [
                        {
                            "asset": {
                                "type": "video",
                                "src": "{{ URL }}",
                                "trim": "{{ TRIM }}"
                            },
                            "start": 0,
                            "length": "{{ DURATION }}"
                        }
                    ]
                }
            ]
        },
        "output": {
            "format": "mp4",
            "resolution": "hd"
        }
    }
}' \
     https://api.shotstack.io/stage/templates/ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641

The response should indicate the template was updated and return the template id:

{
    "success": true,
    "message": "OK",
    "response": {
        "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
        "message": "Template Successfully Updated"
    }
}

Render a template with merge fields

Once you have saved a template, you can render it at any time in the future. While it is possible to render the template by id only, it is more likely you will want to replace placeholders using merge fields.

To render a template call the following endpoint:

POST https://api.shotstack.io/{{ENV}}/templates/render

The following cURL request will replace the templates placeholders with the provided merge fields and render a video:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
    "merge": [
        {
            "find": "URL",
            "replace": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/city-timelapse.mp4"
        },
        {
            "find": "TRIM",
            "replace": 3
        },
        {
            "find": "DURATION",
            "replace": 10
        }
    ]
}' \
     https://api.shotstack.io/stage/templates/render

The following response will be returned including the render task id; response.id:

{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Render Successfully Queued",
        "id": "b3a3034f-8827-9e33-a6a8-ba745d36fc1"
    }
}

The video is now queued for rendering and can be polled like any other render request using the GET render endpoint or using webhooks.