Captions

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

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

方法

该 API 支持对 captions 资源使用以下方法：

list
检索与指定视频关联的字幕轨道列表。请注意，API 响应不包含实际字幕，并且 captions.download 方法可用于检索字幕轨道。 立即试用。
insert
上传字幕轨。 立即试用。
update
更新字幕轨。更新字幕轨道时，您可以更改轨道的草稿状态，为轨道上传新的字幕文件，或者同时执行这两项操作。 立即试用。
下载
下载字幕轨。除非请求为 tfmt 参数指定了值，否则系统会将字幕轨道返回为其原始格式；除非请求为 tlang 参数指定了值，否则系统会将字幕轨道返回为其原始语言。立即试用。
delete
删除指定的字幕轨道。 立即试用。

资源表示法

以下 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
此 ID 用于唯一标识字幕轨道。
snippet object
snippet 对象包含字幕的基本详细信息。
snippet.videoId string
此 ID 用于唯一标识与字幕轨道相关联的视频。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 - 不支持字幕轨道的格式。