Implementation and Migration: Captions

The following examples show how to use the YouTube Data API (v3) to perform functions related to captions.

Retrieve a list of caption tracks for a video

YouTube Data API (v2) functionality: Retrieving a list of available caption tracks

To retrieve a list of caption tracks that are available for a specific video, call the captions.list method. Set the videoId parameter value to the YouTube video ID that uniquely identifies the video for which you are retrieving captions. Your request must be authorized using OAuth 2.0.

The request below retrieves a list of captions for a video on the Google Stories YouTube channel:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list?
part=snippet
&videoId=PRU2ShMzQRg

Related code samples: Python

Create a caption track

YouTube Data API (v2) functionality: Creating a caption track

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload files, which is a requirement for this method.

You can use the API's captions.insert method to upload a new caption track for a video. When uploading a track, you must specify a value for the following caption resource properties:

  • snippet.videoId - This identifies the video to which the caption track is being added.
  • snippet.language - The language of the caption track. In the v2 API, the Content-Language request header specified the language of the caption track.
  • snippet.name - The name of the caption track. In the v2 API, the Slug header specified the caption track name.

The following additional options are available when uploading a caption track:

  • If you set the sync parameter to true, YouTube will disregard any time codes that are in the uploaded caption file and generate new time codes for the captions.

    You should set the sync parameter to true if you are uploading a transcript, which has no time codes, or if you suspect the time codes in your file are incorrect and want YouTube to try to fix them.

  • If you set the caption resource's snippet.isDraft property to true, the track will not be publicly visible.

    New in v3: This functionality is new in the v3 API.

Related code samples: Python

Download a caption track

YouTube Data API (v2) functionality: Retrieving a caption track

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to download files.

To download a specific caption track, call the captions.download method. Set the id parameter value to the YouTube caption track ID that uniquely identifies the caption track that you are downloading. Your request must be authorized using OAuth 2.0.

The v3 API supports the following options, which were also supported in the v2 API, albeit with different parameter names:

  • To specify that a caption track should be returned in a specific format, set the tfmt parameter value to identify the desired format. The parameter definition lists supported values.

  • To retrieve a translation of a caption track, set the tlang parameter value to an ISO 639-1 two-letter language code that identifies the desired caption language. The translation is generated by using machine translation, such as Google Translate.

    • Related code samples: Python

Update a caption track

YouTube Data API (v2) functionality: Updating a caption track

The API supports the ability to change a caption track's draft status, upload a new caption track for a file, or both. The ability to change the draft status, which determines whether the track is publicly visible, is new in the v3 API.

You can use the APIs Explorer to test the ability to change a track's draft status. However, you cannot use the APIs Explorer to update the actual caption track because tool does not support the ability to upload files.

The request below retrieves a list of captions for a video on the Google Stories YouTube channel:

The request updates the draft status of a caption track to true, which means the track will not be publicly visible. To complete the request in the APIs Explorer, you need to set the id property's value to identify a caption track.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?
part=snippet

Related code samples: Python

Delete a caption track

YouTube Data API (v2) functionality: Deleting a caption track

This example shows how to delete a caption track. The example has the following steps: