Creatomate
API & Integration -> Quick Start

Provide your own subtitles

If you prefer more control over the subtitles, you can provide your own timing data instead of relying on auto-generated transcription.

Step 1
Start with auto-generated subtitles

This is the same setup from the auto-generated subtitles example; refer to it first if you haven't already.The 
transcript_source
property is set to the name of the video element, so Creatomate transcribes the audio and generates the subtitle timing automatically. In the next step, we'll replace this by providing our own subtitle data.
curl -X POST https://api.creatomate.com/v2/renders \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -d '{
  "output_format": "mp4",
  "width": 720,
  "height": 1280,
  "elements": [
    {
      "name": "Video-1",
      "type": "video",
      "source": "https://cdn.creatomate.com…/demo/the-daily-stoic-podcast.mp4"
    },
    {
      "name": "Subtitles-1",
      "type": "text",
      "y": "80%",
      "width": "80%",
      "height": "35%",
      "x_alignment": "50%",
      "y_alignment": "50%",
      "fill_color": "#ffffff",
      "stroke_color": "#000000",
      "stroke_width": "1.6 vmin",
      "font_family": "Montserrat",
      "font_weight": "700",
      "font_size": "9.29 vmin",
      "background_color": "rgba(216,216,216,0)",
      "background_x_padding": "31%",
      "background_y_padding": "17%",
      "background_border_radius": "31%",
      "transcript_effect": "highlight",
      "transcript_maximum_length": 14,
      "transcript_source": "Video-1"
    }
  ]
}'

Step 2
Use your own subtitle data

We'll now replace the auto-generated subtitles with our own word-level data.Instead of referencing a media element, set 
transcript_source
to an array of keyframe objects. Each object defines the 
time
(in seconds) at which the word appears, its 
duration
, and the 
value
to display.
curl -X POST https://api.creatomate.com/v2/renders \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -d '{
  "output_format": "mp4",
  "width": 720,
  "height": 1280,
  "elements": [
    {
      "name": "Video-1",
      "type": "video",
      "source": "https://cdn.creatomate.com…/demo/the-daily-stoic-podcast.mp4"
    },
    {
      "name": "Subtitles-1",
      "type": "text",
      "y": "80%",
      "width": "80%",
      "height": "35%",
      "x_alignment": "50%",
      "y_alignment": "50%",
      "fill_color": "#ffffff",
      "stroke_color": "#000000",
      "stroke_width": "1.6 vmin",
      "font_family": "Montserrat",
      "font_weight": "700",
      "font_size": "9.29 vmin",
      "background_color": "rgba(216,216,216,0)",
      "background_x_padding": "31%",
      "background_y_padding": "17%",
      "background_border_radius": "31%",
      "transcript_effect": "highlight",
      "transcript_maximum_length": 14,
      "transcript_source": [
        {
          "time": 0.64,
          "duration": 0.08,
          "value": "It"
        },
        {
          "time": 0.72,
          "duration": 0.08,
          "value": "is"
        },
        {
          "time": 0.8,
          "duration": 0.28,
          "value": "funny,"
        },
        {
          "time": 1.08,
          "duration": 0.16,
          "value": "because"
        },
        {
          "time": 1.24,
          "duration": 0.16,
          "value": "your"
        },
        {
          "time": 1.4,
          "duration": 0.2,
          "value": "course"
        },
        {
          "time": 1.6,
          "duration": 0.2,
          "value": "is"
        },
        {
          "time": 1.8,
          "duration": 0.16,
          "value": "all"
        },
        {
          "time": 1.96,
          "duration": 0.28,
          "value": "about"
        },
        {
          "time": 2.24,
          "duration": 0.32,
          "value": "more"
        },
        {
          "time": 2.56,
          "duration": 0.32,
          "value": "this,"
        },
        {
          "time": 2.88,
          "duration": 0.28,
          "value": "more"
        },
        {
          "time": 3.16,
          "duration": 0.24,
          "value": "that,"
        },
        {
          "time": 3.4,
          "duration": 0.28,
          "value": "more"
        },
        {
          "time": 3.68,
          "duration": 0.32,
          "value": "this."
        }
      ]
    }
  ]
}'

Step 3
Or use a template instead

If you're working with a template rather than RenderScript, you can provide subtitle data the same way using the 
modifications
field. Click 
Open in Editor
below to create an example template, or use your own.Next, target the 
Subtitles-1.transcript_source
to supply your own keyframe data. This sets the 
transcript_source
property of the element named 
Subtitles-1
inside your template with the provided word-level data.
curl -X POST https://api.creatomate.com/v2/renders \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     -d '{
  "template_id": "YOUR_TEMPLATE_ID_HERE",
  "modifications": {
    "Subtitles-1.transcript_source": [
      {
        "time": 0.64,
        "duration": 0.08,
        "value": "It"
      },
      {
        "time": 0.72,
        "duration": 0.08,
        "value": "is"
      },
      {
        "time": 0.8,
        "duration": 0.28,
        "value": "funny,"
      },
      {
        "time": 1.08,
        "duration": 0.16,
        "value": "because"
      },
      {
        "time": 1.24,
        "duration": 0.16,
        "value": "your"
      },
      {
        "time": 1.4,
        "duration": 0.2,
        "value": "course"
      },
      {
        "time": 1.6,
        "duration": 0.2,
        "value": "is"
      },
      {
        "time": 1.8,
        "duration": 0.16,
        "value": "all"
      },
      {
        "time": 1.96,
        "duration": 0.28,
        "value": "about"
      },
      {
        "time": 2.24,
        "duration": 0.32,
        "value": "more"
      },
      {
        "time": 2.56,
        "duration": 0.32,
        "value": "this,"
      },
      {
        "time": 2.88,
        "duration": 0.28,
        "value": "more"
      },
      {
        "time": 3.16,
        "duration": 0.24,
        "value": "that,"
      },
      {
        "time": 3.4,
        "duration": 0.28,
        "value": "more"
      },
      {
        "time": 3.68,
        "duration": 0.32,
        "value": "this."
      }
    ]
  }
}'

Related resources