Skip to main content

Generating subtitles for videos

In this guide, we will walk through the process of generating subtitles for videos using the AssemblyAI API.

Get started

Before we begin, make sure you have an AssemblyAI account and an API token. You can sign up for a free account and get your API token from your dashboard.

The entire source code of this guide can be viewed here.

Step-by-step instructions

  1. 1

    Create a new file and import the necessary libraries for making an HTTP request.

  2. 2

    Set up the API endpoint and headers. The headers should include your API token.

  3. 3

    Upload your local file to the AssemblyAI API.

  4. 4

    Use the upload_url returned by the AssemblyAI API to create a JSON payload containing the audio_url parameter.

  5. 5

    Make a POST request to the AssemblyAI API endpoint with the payload and headers.

  6. 6

    After making the request, you will receive an ID for the transcription. Use it to poll the API every few seconds to check the status of the transcript job. Once the status is completed, you can retrieve the transcript from the API response.

  7. 7

    Export your complete transcripts in SRT or VTT format, to be plugged into a video player for subtitles and closed captions.

Advanced usage

You can also customize the maximum number of characters per caption using the chars_per_caption URL parameter in your API requests to either the SRT or VTT endpoints. For example, adding ?chars_per_caption=32 to the SRT endpoint URL will ensure that each caption has no more than 32 characters.

Learn more


The AssemblyAI produces subtitles as both .srt and .vtt files. These are standard subtitle formats, and can be used with videos both on and off the web. For example, after generating your subtitle file, you can add it to a Mux video using their platform, or you can use ffmpeg to embed it in a local video file. Subtitle formats contain plain text, so you can import these formatted captions to most video editors, or fine-tune them as needed.