Captions

注意:2024 年 3 月 13 日,YouTube 宣布 它将会弃用 sync 参数, captions.insertcaptions.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.insertcaptions.update 方法时,您可以将 sync 参数设置为 true,指示 YouTube 将上传的曲目同步到视频。如果值为 false,YouTube 会使用上传的字幕轨道中的时间码来确定何时显示字幕。
snippet.status string
字幕轨道的状态。

此属性的有效值包括:
  • failed
  • serving
  • syncing
snippet.failureReason string
YouTube 无法处理字幕轨道的原因。仅当 state 属性的值为 failed 时,此属性才会显示。

此属性的有效值包括:
  • processingFailed – YouTube 无法处理上传的字幕轨道。
  • unknownFormat - 系统无法识别字幕轨道的格式。
  • unsupportedFormat - 不支持字幕轨道的格式。