Captions

注意：2024 年 3 月 13 日，YouTube 宣布 它将会弃用 sync 参数， captions.insert和 captions.update API 端点。 YouTube 创作者工作室仍然提供字幕自动同步功能。如需了解详情，请参阅 API 修订历史记录。

caption 资源表示 YouTube 字幕轨道。一个字幕轨道只能与一个 YouTube 视频关联。

方法

对于 captions 资源，该 API 支持以下方法：

list

检索与特定视频相关联的字幕轨道列表。请注意，API 响应不包含实际字幕，并且 captions.download 方法能够检索字幕轨道。 立即试用。

insert

上传字幕轨道。

update

更新字幕轨。更新字幕轨道时，您可以更改轨道的草稿状态，也可以为轨道上传新的字幕文件，或者同时执行这两种操作。

删除

删除指定的字幕轨道。 立即试用。

下载

下载字幕轨。除非请求以原始语言指定 tfmt 参数的值，否则系统会以原始格式返回字幕轨道，除非请求指定了 tlang 参数的值。

资源表示法

以下 JSON 结构显示了 captions 资源的格式：

{
  "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
  }
}

属性

下表定义了此资源中显示的属性：

属性
kind	string 用于标识 API 资源的类型。其值将为 youtube#caption。
etag	etag 此资源的 Etag。
id	string YouTube 用来唯一标识字幕轨道的 ID。
snippet	object snippet 对象包含有关字幕的基本详细信息。
snippet.videoId	string YouTube 用来唯一标识与字幕轨道相关联的视频的 ID。
snippet.lastUpdated	datetime 上次更新字幕轨道的日期和时间。该值采用 ISO 8601 格式指定。
snippet.trackKind	string 字幕轨道的类型。 此属性的有效值包括： ASR - 使用自动语音识别生成的字幕轨道。 forced - 在播放器中未选择任何其他轨道时播放的字幕轨。例如，展示外星人用外星语言说话的视频可能会有一个强制字幕轨道，仅显示外星人语言的字幕。 standard - 常规字幕轨道。这是默认值。
snippet.language	string 字幕轨道的语言。属性值是 BCP-47 语言标记。
snippet.name	string 字幕轨道的名称。该名称在播放期间会作为一个选项向用户显示。支持的名称长度上限为 150 个字符。
snippet.audioTrackType	string 与字幕轨道相关联的音轨类型。 此属性的有效值包括： commentary - 字幕轨与包含评论的备用音轨相对应，例如目录评论。 descriptive - 字幕轨道与包含额外描述性音频的备用音轨相对应。 primary - 字幕轨道与视频的主要音轨相对应，即通常与视频相关联的音轨。 unknown - 这是默认值。
snippet.isCC	boolean 指明曲目是否包含针对失聪和听障人士的字幕。默认值为 false。
snippet.isLarge	boolean 指示字幕轨道是否针对视障人士使用大号文本。默认值为 false。
snippet.isEasyReader	boolean 指明字幕轨道的格式是否适用于“简单读者”。也就是说，该课程为三年级，面向语言学习者。默认值为 false。
snippet.isDraft	boolean 指明字幕轨道是否为草稿。如果值为 true，则字幕轨不会公开显示。默认值为 false。
snippet.isAutoSynced	boolean 指示 YouTube 是否已将字幕轨道与视频中的音频轨道同步。如果在上传字幕轨道时明确请求同步，该值将为 true。例如，调用 captions.insert 或 captions.update 方法时，您可以将 sync 参数设置为 true，指示 YouTube 将上传的曲目同步到视频。如果值为 false，YouTube 会使用上传的字幕轨道中的时间码来确定何时显示字幕。
snippet.status	string 字幕轨道的状态。 此属性的有效值包括： failed serving syncing
snippet.failureReason	string YouTube 无法处理字幕轨道的原因。仅当 state 属性的值为 failed 时，此属性才会显示。 此属性的有效值包括： processingFailed – YouTube 无法处理上传的字幕轨道。 unknownFormat - 系统无法识别字幕轨道的格式。 unsupportedFormat - 不支持字幕轨道的格式。