YouTube Live Streaming API - 修订历史记录

本页面列出了 YouTube Live Streaming API 变更和文档更新。

2026 年 10 月 12 日

此更新包含以下更改：

2026 年 8 月 18 日

此更新包含以下更改：

  • liveBroadcasts.update 方法的文档已更新，其中包含与变现相关的新错误：preconditionFailed (412)（原因：videoNotEligibleForAdsMonetization）和 backendError (503)（原因：backendError）。

2026 年 8 月 17 日

此更新包含以下更改：

  • 借助 liveBroadcast 资源的新 snippet.categoryId 属性，您可以设置、更新和检索与直播相关联的视频类别。

2026 年 7 月 20 日

此更新包含以下更改：

2026 年 7 月 9 日

此更新包含以下更改：

2026 年 6 月 1 日

此更新包含以下更改：

  • 通过 liveBroadcast 资源的 contentDetails.availabilityConfig 属性，您可以为直播指定地理位置限制，以便管理直播活动的区域可用性。

2026 年 3 月 26 日

此更新包含以下更改：

2026 年 1 月 12 日

该 API 现在支持为直播启用中贴片广告和自动插入中贴片广告。

只要直播符合中贴片广告的投放条件，直播所有者就可以选择为直播启用中贴片广告。所有者还可以随时为直播关闭中贴片广告。

如果直播已启用中贴片广告，则直播所有者可以选择启用自动中贴片广告插入功能。他们还可以随时为直播关闭自动广告。

直播所有者启用自动广告后，可以选择以下选项之一：

  • 让 YouTube 优化中贴片广告插入。此选项支持三种模式：
    • 低：收入潜力较低，观看者受到的干扰较少
    • 中：收入潜力中等，平衡了观看者的体验
    • 高：收入潜力更高，观看者受到的干扰较多
  • 手动配置中贴片广告插入策略和间隔。在这种情况下，所有者必须设置两个参数：
    1. 广告插入点的安排策略。您可以为所有观看者同时插入广告提示点，也可以针对不同的观看者在不同的时间插入广告提示点。后一种策略使 YouTube 能够以更高的频率安排广告插播时间点，从而让观看者在符合条件时收到广告插播时间点。
    2. 中贴片广告插播时间点之间的间隔时长。

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

  • liveBroadcast 资源的 monetizationDetails 对象包含用于启用中贴片广告和自动广告配置的字段。
  • update 方法可用于启用或停用中贴片广告。该方法还可用于为直播设置自动广告。该文档指出了在更新直播的创收和自动广告设置时可能出现的几个新错误。

2025 年 7 月 14 日

更新了 liveChatMessages.streamList 方法的说明，以提供有关 streamList 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 方法现已弃用。对 liveCuepoints.insert 方法的支持将于 2023 年 5 月 1 日或之后移除。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 参考文档，以便更好地解释每种方法的常见应用场景，并通过 APIs Explorer 微件提供动态、高质量的代码示例。如需查看示例，请参阅 liveBroadcasts.list 方法的文档。现在，介绍 API 方法的页面上有两个新元素：

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

    • 常见用例部分介绍了页面上说明的方法的一个或多个常见用例。例如，您可以调用 liveBroadcasts.list 方法来检索有关特定直播的数据，或检索有关当前用户的直播的数据。

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

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

  • 代码示例页面也采用了新界面，提供上述所有相同功能。借助该工具，您可以探索不同方法的应用场景、将值加载到 APIs Explorer 中，以及打开全屏 APIs 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 日生效的更新后的条款之外，此次更新还包含多份支持文档，旨在帮助解释开发者必须遵守的政策。

    更新后条款的修订历史记录中介绍了整套新文档。此外，未来对更新后的条款或这些支持文档所做的更改也会在该修订历史记录中进行说明。

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 对 1440p 直播（每秒 30 帧或 60 帧）的支持。

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

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

  • liveCuepoint 资源的新 settings.walltime 属性指定了应插入广告插入点的时间。如果请求尝试插入一个同时为此属性和 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 值列表中移除。