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 To retrieve a list of caption tracks that are available for a specific video, call the [`captions.list`](https://developers.google.com/youtube/data/reference/rest/v3/captions/list.md.txt) method. Set the [`videoId`](https://developers.google.com/youtube/data/reference/rest/v3/captions/list.md.txt#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 following request 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 ``` See the [`captions.list`](https://developers.google.com/youtube/data/reference/rest/v3/captions/list.md.txt#usage) method's documentation for code samples. ## Create a caption track > [!NOTE] > **Note:** 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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/insert.md.txt) 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`](https://developers.google.com/youtube/data/reference/rest/v3/captions.md.txt#snippet.videoId) - This identifies the video to which the caption track is being added. - [`snippet.language`](https://developers.google.com/youtube/data/reference/rest/v3/captions.md.txt#snippet.language) - The language of the caption track. - [`snippet.name`](https://developers.google.com/youtube/data/reference/rest/v3/captions.md.txt#snippet.name) - The name of the caption track. The following additional options are available when uploading a caption track: - If you set the [`sync`](https://developers.google.com/youtube/data/reference/rest/v3/captions/insert.md.txt#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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/insert.md.txt#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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/insert.md.txt#examples) method's documentation for code samples. ## Download a caption track > [!NOTE] > **Note:** 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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/download.md.txt) method. Set the [`id`](https://developers.google.com/youtube/data/reference/rest/v3/captions/download.md.txt#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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/download.md.txt#tfmt) parameter value to identify the selected format. The parameter definition lists supported values. - To retrieve a translation of a caption track, set the [`tlang`](https://developers.google.com/youtube/data/reference/rest/v3/captions/download.md.txt#tlang) parameter value to an [ISO 639-1 two-letter language code](https://www.loc.gov/standards/iso639-2/php/code_list.php) that identifies the selected caption language. The translation is generated by using machine translation, such as Google Translate. See the [`captions.download`](https://developers.google.com/youtube/data/reference/rest/v3/captions/download.md.txt#examples) method's documentation for code samples. ## Update a caption track The API supports the ability to change a caption track's [draft status](https://developers.google.com/youtube/data/reference/rest/v3/captions.md.txt#snippet.isDraft), 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 following request 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 won't 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`](https://developers.google.com/youtube/data/reference/rest/v3/captions/update.md.txt#usage) 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: - **Step 1: Retrieve the caption track ID** Follow the earlier steps to [retrieve a list of caption tracks](https://developers.google.com/youtube/data/guides/implementation/captions#captions-list) for a video. The list could be used to display a list of caption tracks, using each track's ID as a key. - **Step 2: Delete the track** Call the `captions.delete` method to delete a specific video. In the request, the `id` parameter specifies the caption track ID of the track that you are deleting. The request must be authorized using OAuth 2.0. If you are testing this query in the APIs Explorer, you will need to substitute a valid caption track ID for the `id` parameter value. ``` https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.delete? id=CAPTION_TRACK_ID ```