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 现在还支持一项以固定时间间隔自动在广播中插入广告插播时间点的功能。

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

  • 中贴片广告插播时间点之间的间隔长度。
  • 广告插入点的投放时间策略。可以为所有观看者同时插入广告插入点，或者广告插入点的时间可能会因观看者而异。后一种策略使 YouTube 能够以更高的速率调度广告插入点，从而让观看者在有资格接收广告插入点时接收广告插入点。
  • 中贴片广告的不显示的时段；对于此功能，广播所有者指定暂停插入中贴片广告，直到特定时间为止。

本文档反映了以下 API 更改以支持此功能：

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

2023 年 8 月 1 日

此更新包含以下更改：

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

    • snippet.title
    • status.privacyStatus

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

2022 年 11 月 1 日

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

    更新了多个指南，以反映这一新方法的可用性。

  • 注意：这是弃用公告。

    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 内容指南已更新，但进行了一些更改：

此外，新的提取协议比较还列出了 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 响应。此微件还提供了一个全屏视图，其中显示了完整代码示例，这些示例会动态更新以使用您输入的范围和值。

    • 常见用例部分介绍了页面上介绍的方法的一个或多个常见用例。例如，您可以调用 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 响应不再包含已于 2017 年初弃用的 fanFundingEvents 这一事实。

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 工程和开发者博客上详细介绍了新发布的 YouTube API 服务的《服务条款》（以下简称“更新后的条款”），其中对当前《服务条款》提供了丰富的更新内容。除了将于 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) 法律，Google 必须向欧盟境内的最终用户提供某些披露信息并征得他们的同意。因此，对于欧盟境内的最终用户，您必须遵守欧盟地区用户意见征求政策。我们已在 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 音频具有两个以上的声道，但仅支持一个（单声道）或两个（立体声）声道。请更正声道数。
    frameRateHigh 当前的帧速率过高。请将帧速率设为 %(framerate)s fps 或更低。

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

  • 新增错误和已更新的错误

    • 除了为上面列出的新资源定义的错误外，该 API 还支持下列新错误：

      错误详情
      liveBroadcasts.update
      HTTP 响应代码forbidden (403)
      原因closedCaptionsTypeModificationNotAllowed
      说明只有当广播处于 created 或 ready 状态时，才能修改 contentDetails.closedCaptionsType 值。
      liveBroadcasts.update
      HTTP 响应代码invalidValue (400)
      原因invalidEnableClosedCaptions
      说明在 liveBroadcast 资源中，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 上开始以 60fps 的帧速率开始直播，YouTube 还会在不支持高帧速率观看的设备上以 30fps 的帧速率提供直播视频。

    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 资源不再包含 contentDetails.enableDvr 和 contentDetails.enableEmbed 属性说明中提到的 enableArchive 属性。

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

  • liveCuepoint 资源的新 settings.walltime 属性用于指定应插入广告插入点的日期和时间。如果请求尝试插入为此属性和 settings.offsetTimeMs 属性指定值的广告插入点，则 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。

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

  • 该 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 方法插入插播可选广告。我们已经更新了下列文档，以体现这一更改：

2013 年 3 月 18 日

此更新包含以下更改：

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

  • API 现在可能会返回几个新错误。以下列表指明了具体错误以及可能返回该错误的 API 方法：

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