此页面由 Cloud Translation API 翻译。

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` - 不支持字幕轨道的格式。