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 参考文档，以便更好地说明每种方法的常见用例，并通过 API Explorer widget 提供动态的高质量代码示例。如需查看示例，请参阅 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 已弃用粉丝打赏功能，并将于 2017 年 2 月 28 日停用粉丝打赏 API。自该日期起：

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
      说明在 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[] 对象会列出影响视频直播的问题。新文档直播资源配置问题列出了 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 对象及其子属性已从资源的文档中移除。此外，还从支持的 cdn.ingestionType 值列表中移除了 http。