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
Create 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:
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.
See the
captions.insert
method's documentation for code samples.
Download 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:
-
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.
See the
captions.download
method's documentation for code samples.
Update 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.
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
See the
captions.update
method's documentation for code samples.
Delete a caption track
This example shows how to delete a caption track. The example has the following steps: