YouTube Live Streaming API - 修订历史记录

本页面列出了 YouTube Live Streaming API 变更和文档更新。订阅此更新日志。订阅

2023 年 10 月 9 日

您可以在下方CSV 文件中查看哪些贴纸 ID 与哪些超级贴纸相关（仅供参考）。 liveChatMessage 资源的 snippet.superStickerDetails.superStickerMetadata.stickerId 属性和 superChatEvent 资源的 snippet.superStickerMetadata.stickerId 属性的定义均已更新，以反映此信息。

2023 年 9 月 15 日

该 API 现在支持以新的方式将广告插入直播。除了可让您手动在直播中插入广告插播时间点的 liveCuepoints 之外，YouTube 现在还支持一项功能，可在固定时间间隔自动在直播中插入中贴片广告插播时间点。

如果直播所有者启用了自动广告，则可以查看广告行为的以下方面：

  • 中贴片广告插播时间点之间的间隔时长。
  • 广告 cuepoint 的广告投放时间策略。您可以为所有观看者同时插入 cue 点，也可以为不同观看者插入不同的 cue 点时间。采用后一种策略后，YouTube 可以更快地安排 cue 点，让观看者在符合条件时能够收到 cue 点。
  • 中贴片广告不会展示的时间段；对于此功能，直播所有者会指定中贴片广告插入会暂停到特定时间。

文档反映了为支持此功能而进行的以下 API 变更：

  • liveBroadcast 资源现在包含 monetizationDetails 对象。该对象的字段用于指示是否为直播启用了自动广告插入，并指定用于安排 cue 点的其他信息。
  • liveBroadcast.list 方法的 part 参数支持值 monetizationDetails。
  • update 方法可用于暂停在直播中插入中贴片广告的特定时间段。该文档现在还指出了更新直播创收详情时可能会出现的几种错误。

2023 年 8 月 1 日

此更新包含以下更改：

  • liveBroadcasts.update 方法不再需要为以下字段指定值：

    • snippet.title
    • status.privacyStatus

    从请求中省略这些字段将使其保持不变。

2022 年 11 月 1 日

  • 借助新的 liveBroadcasts.cuepoint 方法，任何在 YouTube 上进行直播的频道所有者都可以在直播中插入 cuepoint，从而触发广告插播。此方法取代了 liveCuepoints.insert 方法，后者仅允许 YouTube 内容合作伙伴将 cue 点插入直播中。

    我们更新了多份指南，以反映此新方法的推出。

  • 注意：这是一条废弃公告。

    liveCuepoints.insert 方法现已弃用。我们将于 2023 年 5 月 1 日当天或之后移除对 liveCuepoints.insert 方法的支持。API 用户应更新其应用，改为调用 liveBroadcasts.cuepoint 方法。

  • 移除了 liveBroadcasts.control 方法的文档。我们已于 2020 年 9 月发布了关于该方法的废弃通知。

2022 年 10 月 1 日

此更新包含以下更改：

  • liveBroadcasts.update 方法不再需要为以下字段指定值：

    • contentDetails.enableContentEncryption
    • contentDetails.enableDvr
    • contentDetails.enableEmbed
    • contentDetails.recordFromStart
    • contentDetails.startWithSlate

    从请求中省略这些字段将使其保持不变。

  • 移除了过时 liveBroadcast 字段的文档：

    • contentDetails.enableContentEncryption
    • contentDetails.startWithSlate

2022 年 4 月 1 日

此更新包含以下更改：

2021 年 9 月 15 日

此更新包含以下更改：

2020 年 12 月 1 日

API 的 liveBroadcasts.transition 方法支持新的 403 (Forbidden) 错误，该错误表示用户在给定时间范围内发送了过多请求。错误原因为 userRequestsExceedRateLimit。

2020 年 9 月 21 日

  • liveBroadcast 资源的 status.madeForKids 属性的定义已更新，以明确该属性为只读属性。这并不表示 API 功能发生了变化。

    如需将直播指定为面向儿童的内容，请在调用 liveBroadcasts.insert 方法创建直播时将 status.selfDeclaredMadeForKids 属性设置为 true。

  • 注意：此次变更包括一条弃用公告和一条对之前弃用公告的更新。

    liveBroadcasts.control 方法将于 2020 年 10 月 1 日当天或之后弃用。在此日期之后，对此方法的所有调用都将返回禁止 (403) 错误，该方法稍后将被完全移除。 客户端仍可以通过向发送到 YouTube 提取服务器的视频添加叠加层来实现自己的广告插播时间。

    2020 年 4 月 16 日发布的弃用公告的弃用日期原定为 2020 年 9 月 1 日，现已推迟，将于 2020 年 10 月 1 日当天或之后弃用。因此，该弃用公告中包含的功能和 liveBroadcasts.control 方法都将同时被弃用。

2020 年 7 月 17 日

注意：这是对之前的弃用公告的更新。

liveStream 资源的 cdn.format 字段已于 2016 年 4 月被废弃，自 2020 年 8 月 17 日起，我们将不再支持该字段。自该日期起，仍在使用该字段的请求将会失败。

如果您的代码仍在使用 cdn.format 字段，则必须更新该代码，以使用 cdn.frameRate 和 cdn.resolution 属性分别指定帧速率和分辨率。

2020 年 7 月 6 日

通过 HLS 传送 YouTube 直播内容指南已更新，其中进行了以下几项更改：

  • 媒体片段的建议时长已更新为 1 到 4 秒。
  • 新增了一个部分，介绍了如何从 YouTube 工作室获取 HLS 提取网址。
  • 有关设置 file 参数值格式的说明已移至新的完成 HLS 提取网址部分。无论 HLS 提取网址是从 YouTube API 还是 YouTube 创作者工作室获取的，这些说明都适用。

此外，新的提取协议比较列出了 YouTube 支持的提取协议、每个协议支持的编解码器，以及有关每个协议适用用例的其他信息。

2020 年 4 月 16 日

此更新包含一项新媒体资源和一条弃用公告：

  • liveBroadcast 资源现在支持 contentDetails.enableAutoStop 属性。此属性用于指示在频道所有者停止在绑定的视频串流上流式传输视频后，直播是否应在大约一分钟后自动停止。

    直播生命周期文档已更新，其中说明了如果您将 contentDetails.enableAutoStart 或 contentDetails.enableAutoStop 属性设为 true，创建和管理 YouTube 直播活动的分步流程会发生哪些变化。

  • 注意：这是一条废弃公告。这些变更将于 2020 年 9 月 1 日当天或之后生效。下文将变更生效的实际日期称为弃用日期。

    此更新介绍了一项可能破坏现有代码的更改。这会影响使用频道的默认 liveStream 和 liveBroadcast 资源在 YouTube 上流式传输直播内容的 API 客户端应用。具体而言，与永久性直播和直播相关联的直播 ID 和直播 ID 将无法再用于启动新直播。

    如果符合以下任一条件，您的应用将受到影响：

    • 它会检查 liveBroadcast 资源的 isDefaultBroadcast 属性的值。在废弃日期之后，系统将不会返回此属性。
    • 它会检查 liveStream 资源的 isDefaultStream 属性的值。在废弃日期之后，系统将不会返回此属性。
    • 它会调用 liveBroadcasts.list 方法，并将 broadcastType 参数值设置为 persistent 或 all。在进行这些更改的过程中，此参数将被弃用。自弃用日期起：
      • 如果 broadcastType 参数值为 persistent，则 liveBroadcasts.list 方法将不会返回任何结果。
      • 如果 broadcastType 参数值为 all，则 liveBroadcasts.list 方法不会返回在此时间之前存在的永久性广播。

    背景知识：在过去几年中，当频道启用直播功能后，YouTube 会自动为该频道创建默认直播和默认直播。默认数据流会无限期存在，没有关联的开始时间或结束时间，并且无法删除。同样，默认广播也被视为持久性广播。它始终存在，并且未绑定到特定事件。

    自弃用日期起：

    • YouTube 将不再创建默认直播和广播。API 客户端需要能够创建和管理 liveBroadcast 和 liveStream 资源，并将这些资源绑定在一起，而不是依赖于默认资源。
    • 如果频道的默认直播和默认在线播放正在直播中（即在弃用生效时，频道正在使用它们进行直播），则正在进行的直播不会受到影响。不过，在该直播结束后，该频道将无法再使用默认直播和默认直播流。
    • 如果频道的默认直播和默认直播流未处于有效状态，那么在弃用生效后，YouTube 会忽略尝试使用这些资源直播视频的操作。

    如果您的应用受到影响，请参阅以下文档，它们可帮助您更新应用，使其在变更生效后仍能按预期运行：

    • 新版迁移指南尝试说明开发者可能需要在目前使用默认广播和串流的 API 客户端中执行哪些步骤。
    • 直播生命周期指南将引导您完成分步流程，介绍如何在 YouTube 上创建和管理直播活动。 每个步骤都介绍了您需要执行哪些 API 调用或其他操作才能完成特定操作。当 YouTube 停止支持默认直播和广播时，您的应用将需要遵循该流程。

2020 年 3 月 31 日

注意：这是一条废弃公告。

sponsor 资源和 sponsors.list 方法已被废弃，取而代之的是 member 资源和 members.list 方法。

2020 年 9 月 30 日当天或之后，sponsors.list 方法将不再受支持。 API 客户端应更新对 sponsors.list 方法的调用，改用 members.list 方法。如需详细了解新资源，请参阅 YouTube Data API 修订历史记录。

2020 年 3 月 11 日

通过 HLS 传送 YouTube 直播内容指南的提取端点部分已更新，以阐明编码器在构成主要提取网址和备用提取网址时应遵循的完成 file= 参数值的流程。

2020 年 2 月 4 日

通过 HLS 提交 YouTube 直播内容指南已更新，其中指出 DELETE 请求是可选的，并且 YouTube 的 HLS 端点会忽略这些请求。出于性能方面的原因，YouTube 建议客户端不要发送 DELETE 请求。

2020 年 1 月 10 日

该 API 现在支持识别面向儿童的内容（YouTube 称之为“面向儿童的内容”）。如需详细了解“面向儿童的内容”，请访问 YouTube 帮助中心。

  • liveBroadcast 资源支持两项新属性，可让内容创作者和观看者标识“面向儿童”内容：
    • 借助 selfDeclaredMadeForKids 属性，内容创作者可以指定直播是否为面向儿童的内容。您可以在通过 liveBroadcasts.insert 方法创建广播时设置此属性。请注意，只有在频道所有者授权了 API 请求的情况下，此属性才会包含在包含 liveBroadcast 资源的 API 响应中。
    • 借助 madeForKids 属性，任何 API 用户都可以检索直播的“面向儿童”状态。例如，状态可能会根据 selfDeclaredMadeForKids 属性的值确定。如需详细了解如何为频道、视频或直播设置观众群，请访问 YouTube 帮助中心。
  • 在 YouTube Data API 中，channel 资源还支持新的 selfDeclaredMadeForKids 和 madeForKids 属性。

我们还更新了 YouTube API 服务的《服务条款》和《开发者政策》。如需了解详情，请参阅 YouTube API 服务条款 - 修订记录。YouTube API 服务《服务条款》和《开发者政策》的变更将于 2020 年 1 月 10 日（太平洋时间）生效。

2019 年 8 月 20 日

通过 HLS 传送 YouTube 直播内容指南的要求部分已更新，其中有两项变更：

  • 其中说明，最佳做法是在每个媒体播放列表中同时包含已确认的片段和待确认的片段。这样做可以降低在服务器端丢失媒体播放列表时跳过某个片段的可能性。例如，您可以在每个媒体播放列表中最多添加两个已确认的片段和最多五个待处理的片段。
  • 现在，您必须为每个媒体片段发送媒体播放列表。这样一来，如果媒体播放列表丢失，服务器便可快速恢复。此做法之前被列为建议。

2019 年 6 月 28 日

YouTube 现在支持 HLS 提取。因此，liveStream 资源的 ingestionType 属性支持新值 hls，用于识别使用 HLS 提取到 YouTube 的串流。

新版通过 HLS 提交 YouTube 直播内容指南提供了有关使用 HLS 从编码器向 YouTube 流式传输直播内容的准则。本指南旨在帮助编码器供应商为其产品添加 HLS 提交支持。

2019 年 4 月 4 日

此更新包含以下更改：

  • API 参考文档已更新，以便更好地说明每种方法的常见用例，并通过 API Explorer 微件提供动态的高质量代码示例。如需查看示例，请参阅 liveBroadcasts.list 方法的文档。介绍 API 方法的页面上现在有两个新元素：

    • 借助 API Explorer 微件，您可以选择授权范围、输入示例参数和属性值，然后发送实际 API 请求并查看实际 API 响应。该 widget 还提供全屏视图，用于显示完整的代码示例，这些示例会动态更新以使用您输入的镜重范围和值。

    • 常见用例部分介绍了本页中介绍的方法的一个或多个常见用例。例如，您可以调用 liveBroadcasts.list 方法来检索特定广播的数据，或检索当前用户的广播数据。

      您可以使用该部分中的链接，在 API Explorer 中填充适用于您的用例的示例值，也可以打开已填充这些值的全屏 API Explorer。这些更改旨在让您更轻松地查看直接适用于您尝试在自己的应用中实现的用例的代码示例。

    目前，代码示例支持 Java、JavaScript、PHP、Python 和 curl。

  • 代码示例页面也采用了新的界面，提供上述所有功能。借助该工具，您可以探索不同方法的用例、将值加载到 API Explorer 中，以及打开全屏 API Explorer 以获取 Java、JavaScript、PHP 和 Python 中的代码示例。

    与此同时，我们移除了之前列出了适用于 Java、PHP 和 Python 的代码示例的页面。

2019 年 2 月 25 日

更新了 liveChatMessage 和 superChatEvent 资源的文档，以反映这两个资源现在都包含有关超级贴纸的信息。超级贴纸是一种可显示图片的超级留言消息。与其他超级留言一样，超级贴纸消息是粉丝在 YouTube 直播期间购买的。

  • 在 liveChatMessage 资源中，snippet.type 属性现在设为 superStickerEvent，以指明资源包含有关超级贴纸的信息。在这种情况下，资源还包含 snippet.superStickerDetails 对象，其中包含有关超级贴纸的其他信息。
  • 在 superChatEvent 资源中，布尔值 snippet.isSuperStickerEvent 表示超级留言消息是否也是超级贴纸。如果是，则 snippet.superStickerMetadata 对象会包含有关超级贴纸的其他详细信息。

2018 年 4 月 5 日

更新了 superChatEvents.list 方法的说明，以反映 API 响应不再包含 fanFundingEvents（已于 2017 年初废弃）这一事实。

2017 年 4 月 3 日

添加了新的 Java 代码示例，其中展示了如何列出、插入和删除实时聊天消息。这些示例会调用以下方法：

2017 年 2 月 13 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • liveCuepoints.insert 方法已更新，以反映 onBehalfOfContentOwner 参数目前是必需的。此外，该方法的说明已更新，其中指出对该方法的调用必须由与 YouTube 内容所有者相关联的账号授权。

2017 年 2 月 9 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • 借助 superChatEvents.list 方法的新 hl 参数，您可以指定 snippet.displayString 属性值应采用特定语言的惯例进行格式设置。该媒体资源的定义也相应地进行了更新。

      该参数值必须是 i18nLanguages.list 方法返回的列表中包含的语言代码。默认值为 en，这意味着默认行为是按照英语的格式设置显示字符串。例如，默认情况下，字符串的格式为 $1.00，而不是 $1,00。

2017 年 2 月 1 日

此更新包含以下更改：

  • 新资源和方法

    • 新的 superChatEvent 资源代表粉丝在 YouTube 直播期间购买的超级留言。在 YouTube 实时聊天中，超级留言以两种方式让您的消息更引人注目：

      • 超级留言会以某种颜色突出显示。
      • 超级留言会在置顶栏中固定展示一段时间。

      超级留言的颜色、在置顶栏中固定展示的时长以及消息的最大长度都取决于购买金额。如需详细了解超级聊天功能，请访问 YouTube 帮助中心。

      该 API 支持一种方法，可列出频道过去 30 天内的直播的超级留言事件。该方法还会返回频道上次直播的粉丝赞助事件 (fanFundingEvents) 相关数据。

  • 对现有资源和方法的更新

    • snippet.type 属性现在支持 superChatEvent 值，表示相应资源描述的是超级聊天。

      此外，liveChatMessage 资源的新 snippet.superChatDetails 属性及其子项包含与超级留言事件相关的信息。

    • liveStream 资源的 cdn.resolution 属性现在支持值 2160p。

  • 新增和更新的错误

    • 该 API 支持以下新错误：

      错误详情
      liveBroadcasts.insert，liveBroadcasts.update liveBroadcasts.insert 和 liveBroadcasts.update 方法会返回 400 (Bad Request) 错误，以指示要插入或更新的 liveBroadcast 资源包含 contentDetails.enableEmbed 属性或 contentDetails.projection 属性的无效值。这两个新错误的错误原因分别为 invalidEmbedSetting 和 invalidProjection。

2017 年 1 月 12 日

注意：这是一条废弃公告。

随着全新超级留言功能的发布，YouTube 已弃用粉丝赞助功能，粉丝赞助 API 将于 2017 年 2 月 28 日停用。自该日期起：

2016 年 8 月 11 日

此更新包含以下更改：

  • 新发布的 YouTube API 服务《服务条款》（以下简称“新版《服务条款》”）在 YouTube 工程和开发者博客中进行了详细讨论，对当前《服务条款》进行了大量更新。除了更新后的条款（自 2017 年 2 月 10 日起生效）之外，此更新还包含一些辅助文件，旨在帮助说明开发者必须遵循的政策。

    更新版条款的修订记录中介绍了完整的新文档。此外，日后对修订版条款或这些证明文件所做的更改也会在修订记录中说明。您可以通过该文档中的链接订阅 RSS Feed，以便查看该修订记录中的更改。

2016 年 5 月 20 日

YouTube 现在支持提取 DASH 内容。因此，liveStream 资源的 ingestionType 属性支持新值 dash，用于标识使用 DASH 提取到 YouTube 的串流。

新版通过 DASH 传送 YouTube 直播内容指南提供了有关使用 DASH 传送格式从编码器在 YouTube 上流式传输直播数据的准则。该规范旨在帮助编码器供应商为其产品添加 DASH 提交支持。

2016 年 4 月 18 日

此更新包含以下更改：

  • 对现有资源和方法的更新

    • liveStream 资源更新

      • YouTube 现在支持分辨率为 1440p 且帧速率为 30 或 60 帧/秒的直播。

        此外，liveStream 资源包含用于指定传入视频数据的帧速率和分辨率的新属性：

        属性
        cdn.frameRate 传入视频数据的帧速率。有效值为 30fps 和 60fps。
        cdn.resolution 传入视频数据的分辨率。有效的属性值为：1440p、1080p、720p、480p、360p 和 240p。

      • 随着 liveStream 资源的 cdn.frameRate 和 cdn.resolution 属性的引入，该资源的 cdn.format 现已废弃。cdn.format 属性通过单个值指定分辨率和帧速率。

        我们建议您改用新受支持的字段。在此期间，cdn.format 会继续运行。此外，只要您为 cdn.format 属性或 cdn.frameRate 和 cdn.resolution 属性指定值，插入直播的请求目前就会成功。如果您为这三个属性都提供了值，并且这些值不一致，API 可能会返回错误。

        请注意，虽然 cdn.format 属性已废弃，但现在支持两个新值 1440p 和 1440p_hfr，以反映该 API 支持每秒 30 或 60 帧的 1440p 串流。

    • liveBroadcast 资源更新
    • liveChatMessage 资源更新

      • snippet.type 属性支持两个新值：messageDeletedEvent 和 userBannedEvent，分别对应于下方项目中所述的新属性。我们还更新了 snippet.authorChannelId 属性的定义，以说明这些新消息类型的属性值代表什么。

      • liveChatMessage 资源包含以下新属性：

        属性
        snippet.messageDeletedDetails 此对象包含聊天管理员删除的消息的相关信息。只有当 snippet.type 属性值为 messageDeletedEvent 时，该对象才会存在。
        snippet.userBannedDetails 此对象包含被禁止参与聊天的用户的相关信息。该对象还包含有关禁播本身的信息，即禁播是永久性还是暂时性。如果禁播是暂时性的，则对象的某个属性会指定禁播时长。

        只有当 snippet.type 属性值为 userBannedEvent 时，此对象才会存在。

  • 新增和更新的错误

    • 该 API 支持以下新错误：

      错误详情
      liveBroadcasts.bind liveBroadcasts.bind 方法会返回 403 (Forbidden) 错误，表示用户在给定时间范围内发送的请求过多。错误原因为 userRequestsExceedRateLimit。

      liveBroadcasts.insert 和 liveBroadcasts.update 方法已支持相同的错误。
      liveStreams.insert liveStreams.insert 方法支持四个新的 400 (Bad Request) 错误，用于识别请求尝试插入的 liveStream 资源中的无效属性值。以下列表列出了错误原因及其关联的属性：
      liveStreams.insert liveStreams.insert 方法支持两个新的 400 (Bad Request) 错误，每个错误都表示请求尝试插入的 liveStream 资源中不存在必需的值。以下列表列出了错误原因及其关联的属性：
      更具体地说，在插入 liveStream 资源时，您必须为 cdn.format 属性或 cdn.frameRate 和 cdn.resolution 属性指定值。
      • 如果您未为这三个属性中的任何一个指定值，该 API 会返回 formatRequired 错误。
      • 如果您为 cdn.resolution 指定了值，但未为 cdn.frameRate 指定值，则该 API 会返回 frameRateRequired 错误。
      • 如果您为 cdn.frameRate 指定了值，但未为 cdn.resolution 指定值，则该 API 会返回 resolutionRequired 错误。
      liveStreams.update 如果请求尝试修改以下任何不可变属性的值，liveStreams.update 方法都会返回 403 (Forbidden) 错误： 错误响应中的 reason 为 liveStreamModificationNotAllowed。

2015 年 12 月 18 日

根据欧盟 (EU) 法律，您必须向欧盟境内的最终用户披露相关信息并征求他们的意见。因此，对于欧盟境内的最终用户，您必须遵守《欧盟地区用户意见征求政策》。我们已在 YouTube API 服务条款中添加了关于此要求的通知。

2015 年 12 月 17 日

此更新包含以下更改：

  • 新资源和方法

    • 该 API 支持多项新资源，以支持直播的聊天功能。YouTube 支持在直播期间使用实时聊天功能，这些资源及其方法支持检索聊天消息以及执行聊天管理功能。

      资源
      liveChatMessage 此资源表示 YouTube 实时聊天中的一条消息。YouTube 支持多种类型的消息，包括短信和粉丝赞助活动。某些消息类型用于标识聊天的特定阶段，例如仅限赞助商的阶段的开始或聊天的结束。该 API 支持用于列出、插入和删除实时聊天消息的方法。
      liveChatModerators 此资源用于标识聊天管理员。管理员可以执行一些管理功能，例如禁止用户聊天或移除消息。该 API 支持用于列出、插入和删除实时聊天管理员的方法。
      liveChatBans 此资源用于标识被禁止向特定实时聊天发送消息的用户。禁播可能是暂时性的，也可能是永久性的。该 API 支持用于插入和删除实时聊天禁令的方法。
      fanFundingEvents 此资源代表 YouTube 频道上的粉丝赞助活动。粉丝赞助功能让观看者可以通过一次性付款的方式自愿支持 YouTube 创作者。

      该 API 的 fanFundingEvents.list 方法会列出频道的粉丝赞助事件。在频道拥有的直播期间通过实时聊天发起的粉丝赞助活动也会触发向直播的实时聊天发送 fanFundingEvent 消息。

      如需详细了解粉丝赞助，请访问 YouTube 帮助中心。
      sponsors sponsor 资源用于标识 YouTube 频道的赞助商。赞助商向频道支付月费。赞助商在频道实时聊天中的留言旁边会显示一个徽章，赞助商还可以参与仅限频道赞助商参与的实时聊天（如果有）。

      API 的 sponsors.list 方法可列出频道的赞助商。当用户在频道拥有的直播期间注册赞助该频道时，该 API 还会向直播的实时聊天中添加 newSponsorEvent 消息。

      如需详细了解赞助，请访问 YouTube 帮助中心。

  • 对现有资源和方法的更新

    • liveBroadcast 资源包含以下新属性：

      属性
      snippet.liveChatId 直播的 YouTube 实时聊天 ID。有了此 ID，您就可以使用 liveChatMessage 资源的方法检索、插入或删除聊天消息。您还可以添加或移除聊天管理员、禁止用户参与实时聊天，或移除现有禁令。
      contentDetails.closedCaptionsType 注意：此属性会替换 contentDetails.enableClosedCaptions 属性。

      此属性用于指明您的直播是否启用了字幕，如果启用了，您提供的是哪种类型的字幕：
      • closedCaptionsDisabled：直播的字幕已停用。
      • closedCaptionsHttpPost：您将通过 HTTP POST 将字幕发送到与您的直播关联的提取网址。
      • closedCaptionsEmbedded：字幕将使用 EIA-608 和/或 CEA-708 格式编码到视频串流中。
      contentDetails.enableClosedCaptions 自 2015 年 12 月 17 日起，此属性已被弃用。请改用 contentDetails.closedCaptionsType 属性。对于已在使用此属性的 API 客户端：
      • 将属性值设置为 true 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsHttpPost。
      • 将属性值设置为 false 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsDisabled。

    • 借助 liveBroadcasts.list 方法的新 broadcastType 参数，您可以过滤 API 响应，以包含事件广播、永久性广播或所有广播。

      永久性广播始终存在，并且不与特定事件相关联。具体而言，频道的默认直播是一种永久性直播，可通过 YouTube 创作者工作室中的直播信息中心访问。该频道的其他直播是活动直播。

  • liveStream 资源的 status.healthStatus.configurationIssues[].type 字段会报告以下新的运行状况错误：

    错误
    audioTooManyChannels 音频的声道数量超过了两个，但系统仅支持 1 个（单声道）或 2 个（立体声）声道。请更正音频的声道数量。
    frameRateHigh 当前帧速率过高。请将帧速率设为 %(framerate)s fps 或更低。

  • 更正了上次文档更新的发布日期。

  • 新增和更新的错误

    • 除了为上述新资源定义的错误之外，该 API 还支持以下新错误：

      错误详情
      liveBroadcasts.update
      HTTP 响应代码forbidden (403)
      原因closedCaptionsTypeModificationNotAllowed
      说明只有当广播处于 created 或 ready 状态时，才能修改 contentDetails.closedCaptionsType 值。
      liveBroadcasts.update
      HTTP 响应代码invalidValue (400)
      原因invalidEnableClosedCaptions
      说明在直播资源中，contentDetails.enableClosedCaptions 属性的值与 contentDetails.closedCaptionType 设置的值不兼容。请修改资源，使其仅包含这两项属性中的一项，然后重新提交请求。

2015 年 8 月 19 日

此更新包含以下更改：

  • 新资源和方法

    • 注意：liveChat 资源及其方法的文档是机密的，只有部分 YouTube 合作伙伴可以看到。

      新的 liveChat 资源包含在 YouTube 上直播期间发布的评论。该 API 针对此资源支持两种方法：

      方法
      liveChats.list 列出直播的实时聊天消息。
      liveChats.insert 创建新聊天消息。

      只有在直播期间才能检索和发布实时聊天消息。

  • 对现有资源和方法的更新

    • liveStream 资源包含以下新属性：

      属性
      snippet.isDefaultStream 指明此直播是否为频道的默认直播。频道的默认直播会无限期存在，没有关联的开始时间或结束时间，并且无法删除。如需详细了解默认数据流的运作方式，请参阅该属性的定义。
      status.healthStatus 此对象包含可用于识别、诊断和解决流式传输问题的信息。该对象包含多个子属性，可帮助您评估直播视频流的健康状况。

      具体而言，status.healthStatus.configurationIssues[] 对象会列出影响视频流的问题。新文档 LiveStream 资源的配置问题列出了该 API 报告的所有问题。
      contentDetails.isReusable 指示数据流是否可重复使用，这意味着它可以绑定到多个广播。如果直播在不同时间进行，直播者通常会重复使用同一直播。

    • liveBroadcast 资源包含以下新属性：

      属性
      snippet.isDefaultBroadcast 指明此直播是否为频道的默认直播。为 YouTube 频道启用直播功能后，YouTube 会为该频道创建一个默认直播和一个默认直播。直播定义了频道所有者将直播视频发送到 YouTube 的方式，而广播则是观看者观看默认直播的方式。如需详细了解默认广播的运作方式，请参阅该属性的定义。
      contentDetails.enableLowLatency 指明是否应对此直播进行编码以实现低延迟流式传输。低延迟直播可以缩短观看直播的用户看到视频所需的时间，但也可能会影响观看直播的观看者的分辨率。
      statistics.totalChatCount 与直播相关联的实时聊天消息总数。如果直播对用户可见且已启用实时聊天功能，则该属性及其值会显示。请注意，在广播结束后，此属性将不会指定值。因此，此属性不会识别已完成的直播的归档视频的聊天消息数。

  • 新增和更新的错误

    • 除了为新的 liveChat 资源定义的错误之外，该 API 还支持以下新错误：

      错误详情
      liveStreams.update
      HTTP 响应代码forbidden (403)
      原因liveStreamModificationNotAllowed
      说明该 API 不允许您将可重复使用的串流更改为不可重复使用，反之亦然。如需了解详情，请参阅了解广播和数据流

2015 年 5 月 21 日

此更新包含以下更改：

  • YouTube 现在支持以每秒 60 帧 (fps) 的速度进行直播视频流式传输，这意味着游戏和其他快节奏视频的播放会更加流畅。当您在 YouTube 上以 60 fps 的帧速率开始直播时，YouTube 还会在尚不支持高帧速率观看的设备上以 30 fps 的帧速率提供直播。

    liveStream 资源的 cdn.format 属性支持此功能的两个新值：720p_hfr 和 1080p_hfr。

    如需详细了解此功能，请参阅 YouTube 创作者博客。

2014 年 8 月 21 日

此更新包含以下更改：

  • 更新了 liveBroadcasts.control 方法的 walltime 参数定义，以指明属性值采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ss.sssZ) 指定。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    insufficientPermissions liveStreamingNotEnabled 如果授权 API 请求的用户未获授权在 YouTube 上直播视频，则 liveBroadcast 和 liveStream 资源的所有方法都会返回此错误。您可以在用户的频道设置（网址为 https://www.youtube.com/features）中找到详细信息，了解用户无法直播视频的原因。
    rateLimitExceeded userRequestsExceedRateLimit liveBroadcasts.insert 和 liveStreams.insert 方法都会返回此错误，以指示用户在给定时间范围内发送的请求过多。

2014 年 5 月 2 日

此更新包含以下更改：

  • 更新了 liveStream 资源和 liveBroadcasts.bind 方法的说明，指出一个直播只能绑定到一个视频流，但一个视频流可以绑定到多个直播。此次变更仅是对文档的更正；底层 API 功能没有任何变化。

  • liveBroadcast 资源的 contentDetails.monitorStream.enableMonitorStream 属性已更新，以说明如果该属性的值为 true，则您必须先将广播转换为 testing 状态，然后才能将其转换为 live 状态。（如果该属性的值为 false，则您的广播不能有 testing 阶段，因此您可以将广播直接转换为 live 状态。

  • liveCuepoint 资源的 settings.offsetTimeMs 属性已更新，以提示您，如果直播没有监控串流，则不应为该属性指定值。

  • liveBroadcast 和 liveStream 资源的所有方法现在都支持 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 参数。借助这些参数，您可以使用相同的授权凭据为与同一内容所有者关联的不同频道完成 API 请求。

  • 更新了 liveCuepoints.insert 方法的文档，其中指出您可以在调用该方法时为 settings.walltime 属性设置值。

  • 错误文档现已指定每种错误类型的 HTTP 响应代码。

  • 该 API 现在支持以下错误：

    错误类型 错误详情 说明
    insufficientPermissions livePermissionBlocked 如果授权请求的用户无法在 YouTube 上直播视频，liveBroadcasts.insert、liveBroadcasts.transition 和 liveStreams.insert 方法会返回此错误。您可以在用户的频道设置（网址为 https://www.youtube.com/features）中找到详细信息，了解用户无法直播视频的原因。

  • 更新了 liveBroadcasts.insert 方法的 invalidScheduledStartTime 错误，以明确说明安排的开始时间必须足够接近当前日期，以便能够在该时间可靠地安排广播。

2013 年 12 月 13 日

此更新包含以下更改：

  • liveBroadcast 资源的新 status.recordingStatus 属性用于标识广播的当前状态。

  • liveBroadcast 资源的新 contentDetails.enableClosedCaptions 属性用于指明是否可以为直播提取字幕。您可以在插入或更新广播时设置此属性值，但一旦广播处于 testing 或 live 状态，便无法再更新此属性值。如果您将此属性设为 true，则绑定到直播的 liveStream 资源将指定要用于直播字幕的提取网址。

  • liveBroadcast 资源的 snippet.scheduledEndTime 属性现在支持安排无限期持续的广播。经过此项更改，liveBroadcasts.insert 和 liveBroadcasts.update 请求中不再需要此属性。

    如果您检索的 liveBroadcast 资源未为此属性指定值，则系统会安排广播无限期继续。同样，如果您调用 liveBroadcasts.insert 或 liveBroadcasts.update 方法，但未为此属性指定值，系统会将广播安排为无限期继续。

  • liveBroadcast 资源的 contentDetails.recordFromStart 属性（默认值为 true）现在只能在允许广播频道停用直播录制功能的情况下设置为 false。

    如果您的频道无权停用录制功能，并且您尝试插入将 recordFromStart 属性设置为 false 的直播，则 API 会返回 Forbidden 错误。此外，如果您的频道没有该权限，并且您尝试更新直播以将 recordFromStart 属性设置为 false，则 API 会返回 modificationNotAllowed 错误。

  • liveBroadcast 资源不再包含 enableArchive 属性，该属性曾在 contentDetails.enableDvr 和 contentDetails.enableEmbed 属性的说明中提及过。

  • liveBroadcast 资源的 status.lifeCycleStatus 属性的有效值列表已更新，其中包含每种状态的说明。

  • liveCuepoint 资源的新 settings.walltime 属性用于指定应插入 cue 点的日期和时间。如果请求尝试插入用于为此属性和 settings.offsetTimeMs 属性指定值的 cuepoint，则 API 会返回错误。

  • liveStream 资源中的新 contentDetails 对象包含有关数据流的信息。目前，该对象的唯一属性是 contentDetails.closedCaptionsIngestionUrl，用于指定与视频流关联的字幕的提取网址。

  • liveStream 资源的 status.streamStatus 属性的有效值列表已更新，其中包含每种状态的说明。

  • 借助 liveBroadcasts.control 方法的新 walltime 参数，您可以指定播出信息更改的日期和时间。如果请求为此参数和 offsetTimeMs 参数指定了值，该 API 会返回错误。

  • 在对 liveBroadcasts.list 请求的 API 响应中，kind 属性的值已从 youtube#liveBroadcastList 更改为 youtube#liveBroadcastListResponse。

  • 在对 liveStreams.list 请求的 API 响应中，kind 属性的值已从 youtube#liveStreamList 更改为 youtube#liveStreamListResponse。

  • eventId 属性已从 liveBroadcastListResponse 和 liveStreamListResponse 中废弃。

  • 该 API 支持以下新错误：

    错误类型 错误详情 说明
    invalidValue conflictingTimeFields 如果您的请求为 offsetTimeMs 和 walltime 参数指定了值，liveBroadcasts.control 方法会返回此错误。请求可以同时省略这两个参数，也可以为这两个参数之一指定值。
    invalidValue invalidWalltime 如果 walltime 参数的值无效，liveBroadcasts.control 方法会返回此错误。
    forbidden enableClosedCaptionsModificationNotAllowed 如果您尝试更新 contentDetails.enableClosedCaptions 值，并且广播的状态不是 created 或 ready，liveBroadcasts.update 方法会返回此错误。
    invalidValue conflictingTimeFields 如果您的请求为 settings.offsetTimeMs 和 settings.walltime 属性指定了值，liveCuepoints.insert 方法会返回此错误。请求可以同时省略这两个属性，也可以为这两个属性之一指定值。

    此外，liveStreams.update 方法不再支持与 liveStreams.insert 方法支持的 cdnRequired 错误类似的错误。

2013 年 5 月 10 日

此更新包含以下更改：

2013 年 5 月 2 日

此更新包含以下更改：

2013 年 3 月 27 日

此更新包含以下更改：

  • liveBroadcast 资源中的以下属性已发生变化：

    • startWithSlateCuepoint 属性已重命名为 startWithSlate。
    • enableArchive 属性已重命名为 recordFromStart。
    • slateSettings 对象已被弃用，并从文档中移除。与 slateSettings 对象或其属性相关的错误消息也已移除。最后，我们移除了使用入门指南中的“显示片单”部分。

  • 该 API 不再支持使用 liveCuepoints.insert 方法插入插播广告信息。我们已经更新了下列文档，以体现这一更改：

    • 首页、使用入门指南和直播生命周期教程中不再提及此功能。

    • liveCuepoint 资源的 settings.cueType 属性不再支持将 slate 用作属性值。（唯一支持的值是 ad。

    • liveCuepoint 资源的 settings.eventState 属性已被弃用，并从文档中移除。

2013 年 3 月 18 日

此更新包含以下更改：

  • 该 API 的所有错误消息均已更新，以更清楚地说明可能出现的错误，并在可能的情况下提供有关如何修正这些错误的指导。

  • 该 API 现在可能会返回多个新错误。下表列出了相应错误以及可能会返回该错误的 API 方法：

  • liveStream 资源文档已更新，以反映多播和 WebM 不受支持的提取方法，如之前所述。cdn.format 属性的格式列表已相应更新，并且资源文档中已移除 cdn.multicastIngestionInfo 对象及其子属性。此外，http 已从支持的 cdn.ingestionType 值列表中移除。