Captions

注意:2024 年 3 月 13 日,YouTube 宣布将弃用 captions.insertcaptions.update API 端点的 sync 参数。 您仍然可以在 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 - 不支持字幕轨道的格式。