Add text to video using the Edit API

Text is an integral feature of any video production. Adding text to a video or image provides extra information and context to the viewer. From titles, captions, lower thirds and credits, there are hundreds of use cases.

The Shotstack editing API makes it easy to arrange text over videos and images you generate. Using familiar HTML and CSS you can control the font, color and size of text. Text bounding boxes can be set and positioned anywhere on the screen. Plus, add motion effects and transitions to bring your titles to life.

In this guide we'll show you how to generate videos with custom text via an API. To follow along with the guide you will need a Shotstack account and and API key. You can register and use the developer sandbox for free.

Add a video title using the HTML asset

To add text to your video you use the HTML asset. The HTML asset supports basic formatting and text styling using HTML and CSS. If you have experience with web development this should all be familiar.

You use JSON to prepare a video edit. You can do this using our SDKs but for this guide we will use cURL and raw JSON. It is also possible to use Postman or the JSON editor in the dashboard.

To add a basic title to a video, create a file named title.json and add the following JSON:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>HELLO WORLD</p>",
              "css": "p { font-family: 'Montserrat ExtraBold'; color: #ffffff; font-size: 72px; }",
              "width": 800,
              "height": 200
            },
            "start": 0,
            "length": 5
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

The JSON above creates a 5 second long clip with an HTML asset. THe HTML asset has a bounding box of 800px x 200px. The text is HTML, <p>HELLO WORLD</p> with simple CSS styling, p { font-family: 'Montserrat ExtraBold'; color: #ffffff; font-size: 72px; }.

Post the edit to the API

Using cURL, post the JSON to the render endpoint for processing. Add your own API key instead of YOUR_API_KEY:

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

The JSON response includes an id key that we use to check the progress of the render task:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "29ef5e40-fedf-84db-7e71-6d93b8bf633f"
  }
}

Get the edit render status

Next, make a GET cURL request to the render endpoint appending the id. Replace RESPONSE_ID with the id and run the following command:

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

The request returns details of the render task including the rendering status, response.status. Call the endpoint every couple of seconds until the value equals done. When the status equals done, rendering is complete and a response.url value points to a video file.

{
  "success":true,
  "message":"OK",
  "response":{
    "id":"29ef4d40-fedf-42db-8b81-6d90b8bf633e",
    "owner":"msgtwx8iw6",
    "plan":"sandbox",
    "status":"done",
    "error":"",
    "duration":5,
    "billable":5,
    "renderTime":1139.64,
    "url":"https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/msgtwx8iw6/29ef4d40-fedf-42db-8b81-6d90b8bf633e.mp4",
    "poster":null,
    "thumbnail":null,
    "created":"2022-03-03T01:43:38.486Z",
    "updated":"2022-03-03T01:43:44.549Z"
  }
}

Open the response.url value in a browser to see a video like below with our title.

Using custom fonts for titles

The previous example used the CSS font-family parameter to specify Montserrat ExtraBold as the font. This is one of a small handful of pre-installed fonts. To use your own font you need to import it with your render so it is available to use.

To import a font we add an array of fonts inside the timeline object like this:

"fonts": [
  {
    "src": "https://templates.shotstack.io/basic/asset/font/quicksand-bold.ttf"
  }
]

This downloads and installs the font, ready for rendering. The font name is then used with the font-family CSS parameter.

The full edit is shown below using the font Quicksand Bold.

{
  "timeline": {
    "fonts": [
      {
        "src": "https://templates.shotstack.io/basic/asset/font/quicksand-bold.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p>HELLO WORLD</p>",
              "css": "p { font-family: 'Quicksand'; font-weight: bold; color: #ffffff; font-size: 72px; }",
              "width": 800,
              "height": 200
            },
            "start": 0,
            "length": 5
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

Notice that we use the font name Quicksand and ste the font weight to bold. You need to use the correct font name and set the weight if applicable. Check our custom fonts guide for full details on importing and using fonts.

The following video is created:

Styling the video text

We can apply more advanced styling, using CSS selectors to target elements. In the next video we will use the following HTML and CSS for our asset:

"asset": {
  "type": "html",
  "html": "<p class='top'>HELLO</p><p>WORLD</p>",
  "css": "p { font-family: 'Quicksand'; font-weight: bold; color: #ffffff; font-size: 72px; line-height: 50%; } .top { font-family: 'Quicksand Light'; font-size: 32px; color: #25d3d0; }",
  "width": 800,
  "height": 200
}

In the is example we have split the words HELLO and WORLD in to their own paragraphs. The .top selector is styled using a different font, colour and text size. We also add a line height to adjust the text spacing.

Try the JSON below and check the video below for the result.

{
  "timeline": {
    "fonts": [
      {
        "src": "https://templates.shotstack.io/basic/asset/font/quicksand-bold.ttf"
      },
      {
        "src": "https://templates.shotstack.io/basic/asset/font/quicksand-light.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "html",
              "html": "<p class='top'>HELLO</p><p>WORLD</p>",
              "css": "p { font-family: 'Quicksand'; font-weight: bold; color: #ffffff; font-size: 72px; line-height: 50%; } .top { font-family: 'Quicksand Light'; font-size: 32px; color: #25d3d0; }",
              "width": 800,
              "height": 200
            },
            "start": 0,
            "length": 5
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

The JSON above generates the following video:

The HTML asset supports the basic features of CSS for text styling. It is not at parity with HTML5/CSS3 and is closer to HTML4/CSS2. A full list of supported HTML features outlines what is possible.

Adding text to an image

Shotstack supports images as well as video. To generate an image follow the steps above but change the output format to jpg, png or bmp like below:

"output": { "format": "jpg", "resolution": "sd" }

Positioning text in a video or image

You should now know the basics of adding text to a video and how to apply some simple styling. In this tutorial the text is always center aligned. Next you will want to learn how to position and align text in our HTML positioning guide.