Captions

Page Summary

YouTube deprecated the sync parameter for the captions.insert and captions.update API endpoints on March 13, 2024, but auto-syncing remains available in YouTube Creator Studio.
A caption resource represents a YouTube caption track, which is associated with one specific YouTube video, and the API provides methods to list, insert, update, download, and delete these tracks.
The captions resource includes a snippet object that contains details like the associated videoId, the language, the trackKind, and whether it's a draft, among others.
The caption track's snippet.isAutoSynced boolean property indicates if YouTube synchronized the caption track to the audio, with a false value indicating that YouTube used the time codes in the uploaded track.
Caption track properties include status indicators such as serving, syncing, or failed, with failureReason providing the specific reason for any failures, such as processingFailed or unsupportedFormat.

Note: On March 13, 2024, YouTube announced that it is deprecating the sync parameter for the captions.insert and captions.update API endpoints. Captions auto-syncing is still available in YouTube Creator Studio. See the API revision history for more details.

A caption resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video.

Methods

The API supports the following methods for captions resources:

list: Retrieve a list of caption tracks that are associated with a specified video. Note that the API response does not contain the actual captions and that the captions.download method provides the ability to retrieve a caption track. Try it now.
insert: Upload a caption track. Try it now.
update: Update a caption track. When updating a caption track, you can change the track's draft status, upload a new caption file for the track, or both. Try it now.
download: Download a caption track. The caption track is returned to its original format unless the request specifies a value for the tfmt parameter and to its original language unless the request specifies a value for the tlang parameter. Try it now.
delete: Delete a specified caption track. Try it now.

Resource representation

The following JSON structure shows the format of a captions resource:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

Properties

The following table defines the properties that appear in this resource:

Properties
`kind`	`string` Identifies the API resource's type. The value will be `youtube#caption`.
`etag`	`etag` The Etag of this resource.
`id`	`string` The ID that YouTube uses to uniquely identify the caption track.
`snippet`	`object` The `snippet` object contains basic details about the caption.
`snippet.videoId`	`string` The ID that YouTube uses to uniquely identify the video associated with the caption track.
`snippet.lastUpdated`	`datetime` The date and time when the caption track was last updated. The value is specified in ISO 8601 format.
`snippet.trackKind`	`string` The caption track's type. Valid values for this property are: `ASR` – A caption track generated using automatic speech recognition. `forced` – A caption track that plays when no other track is selected in the player. For example, a video that shows aliens speaking in an alien language might have a forced caption track to only show subtitles for the alien language. `standard` – A regular caption track. This is the default value.
`snippet.language`	`string` The language of the caption track. The property value is a BCP-47 language tag.
`snippet.name`	`string` The name of the caption track. The name is intended to be visible to the user as an option during playback. The maximum name length supported is 150 characters.
`snippet.audioTrackType`	`string` The type of audio track associated with the caption track. Valid values for this property are: `commentary` – The caption track corresponds to an alternate audio track that includes commentary, such as directory commentary. `descriptive` – The caption track corresponds to an alternate audio track that includes additional descriptive audio.