LiveBroadcasts

该 API 现在支持将直播标记为“面向儿童的内容”，并且 liveBroadcast 资源现在包含一个用于标识相应直播的“面向儿童的内容”状态的属性。YouTube API 服务的《服务条款》和《开发者政策》也于 2020 年 1 月 10 日更新。如需了解详情，请参阅 YouTube Live Streaming API 服务和 YouTube API 服务条款的修订历史记录。

liveBroadcast 资源表示将在 YouTube 上通过实时视频进行直播的活动。

方法

该 API 支持以下针对 liveBroadcasts 资源的方法：

list

返回与 API 请求参数匹配的 YouTube 广播列表。 立即试用。

insert

创建广播。 立即试用。

update

更新广播。例如，您可以修改 liveBroadcast 资源的 contentDetails 对象中定义的广播设置。立即试用。

delete

删除广播。 立即试用。

绑定

将 YouTube 广播与直播绑定，或移除广播与直播之间的现有绑定。一个广播只能绑定到一个视频流，但一个视频流可以绑定到多个广播。 立即试用。

transition

更改 YouTube 直播的状态，并启动与新状态关联的所有进程。例如，当您将广播的状态转换为 testing 时，YouTube 会开始将视频传输到相应广播的监控流。在调用此方法之前，您应确认与广播绑定的直播的 status.streamStatus 属性值为 active。立即试用。

cuepoint

在直播中插入提示点。提示点可能会触发广告插播时间点。

资源表示法

以下 JSON 结构显示了 liveBroadcasts 资源的格式：

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "categoryId": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean,
    "availabilityConfig": {
      "globalConfig": {
        "excludedRegionCodes": [
          string
        ],
        "interval": {
          "startTime": datetime,
          "endTime": datetime
        }
      },
      "regionsConfig": {
        "regionIntervals": [
          {
            "regionCode": string,
            "interval": {
              "startTime": datetime,
              "endTime": datetime
            }
          }
        ]
      }
    }
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "adsMonetizationStatus": string,
    "eligibleForAdsMonetization": boolean,
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "ytOptimizedCuepointConfig": string,
      "creatorCuepointConfig": {
        "scheduleStrategy": string,
        "repeatIntervalSecs": unsigned integer
      }
    }
  }
}

属性

下表定义了此资源中显示的属性：

属性
kind	string 用于标识 API 资源的类型。该值为 youtube#liveBroadcast。
etag	etag 相应资源的 ETag。
id	string YouTube 为唯一标识广播而分配的 ID。
snippet	object snippet 对象包含有关活动的基本详细信息，包括活动的标题、说明、开始时间和结束时间。
snippet.publishedAt	datetime 直播添加到 YouTube 直播安排中的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.channelId	string YouTube 用于唯一标识发布广播的频道的 ID。
snippet.title	string 广播的标题。请注意，广播代表一个 YouTube 视频。您可以通过修改广播资源或设置相应视频资源的 title 字段来设置此字段。
snippet.description	string 广播的说明。与 title 一样，您可以通过修改广播资源或设置相应视频资源的 description 字段来设置此字段。
snippet.categoryId	string 与广播相关联的 YouTube 视频类别。您可以使用 videoCategories.list 方法检索类别列表。
snippet.thumbnails	object 与广播相关联的缩略图的映射。对于此对象中的每个嵌套对象，键是缩略图的名称，值是包含有关缩略图的其他信息的对象。
snippet.thumbnails.(key)	object 有效键值包括： default - 默认缩略图。视频（或引用视频的资源，例如播放列表项或搜索结果）的默认缩略图宽度为 120 像素，高度为 90 像素。频道的默认缩略图尺寸为 88 像素（宽）x 88 像素（高）。 medium - 缩略图的更高分辨率版本。对于视频（或引用视频的资源），此图片的宽度为 320 像素，高度为 180 像素。对于频道，此图片的宽度和高度均为 240 像素。 high - 缩略图图片的高分辨率版本。对于视频（或引用视频的资源），此图片的宽度为 480 像素，高度为 360 像素。对于频道，此图片的宽度和高度均为 800 像素。 standard - 比 high 分辨率的缩略图分辨率更高。此图片适用于某些视频以及引用视频的其他资源，例如播放列表项或搜索结果。此图片的宽度为 640 像素，高度为 480 像素。 maxres - 缩略图图片的高分辨率版本。此图片大小适用于某些视频以及引用视频的其他资源，例如播放列表项或搜索结果。此图片的宽度为 1280 像素，高度为 720 像素。 fhd - 缩略图的全高清 (1080p) 版本。此图片大小适用于部分视频。此图片的宽度为 1920 像素，高度为 1080 像素。 qhd - 缩略图的 2K 分辨率 (1440p) 版本。此图片大小适用于部分视频。此图片的宽度为 2560 像素，高度为 1440 像素。 uhd - 缩略图图片的超高分辨率 (4K) 版本。此图片大小适用于部分视频。此图片的宽度为 3840 像素，高度为 2160 像素。
snippet.thumbnails.(key).url	string 图片的网址。
snippet.thumbnails.(key).width	unsigned integer 图片的宽度。
snippet.thumbnails.(key).height	unsigned integer 图片的高度。
snippet.scheduledStartTime	datetime 广播计划开始的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。创作者工作室支持创建广播，而无需安排开始时间。在这种情况下，频道所有者开始直播时，直播活动就会开始。对于这些广播，datetime 值对应于 Unix 纪元时间零，并且无法使用 API 或在 Creator Studio 中更改此值。
snippet.scheduledEndTime	datetime 广播计划结束的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。如果 liveBroadcast 资源未为此属性指定值，则广播将安排为无限期继续。同样，如果您未为此属性指定值，YouTube 会将广播视为无限期进行。
snippet.actualStartTime	datetime 广播实际开始的日期和时间。只有在广播状态为 live 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.actualEndTime	datetime 广播实际结束的日期和时间。只有在广播状态为 complete 时，此信息才可用。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
snippet.isDefaultBroadcast	boolean 此属性将于 2020 年 9 月 1 日或之后弃用。届时，当频道启用直播功能后，YouTube 将停止创建默认直播和默认广播。如需了解详情，请参阅弃用公告。 此属性用于指明相应广播是否为默认广播。 默认直播的工作原理 当 YouTube 频道启用直播功能后，YouTube 会为该频道创建默认直播和默认广播。直播流定义了频道所有者向 YouTube 发送实时视频的方式，而广播则是观看者观看默认直播流的方式。频道所有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法来识别这些资源。 当频道开始向其默认直播流传送视频时，该视频会显示在频道的默认广播中。直播结束后，YouTube 会将完成的直播转换为 YouTube 视频，并为该视频分配一个 YouTube 视频 ID。 转换完成后，该视频会显示在频道已上传视频的列表中。直播结束后，视频不会立即提供，延迟时间与直播的实际时长有关。
snippet.liveChatId	string 相应广播的 YouTube 实时聊天 ID。借助此 ID，您可以使用 liveChatMessage 资源的方法来检索、插入或删除聊天消息。您还可以添加或移除聊天管理员、禁止用户参与实时聊天，或移除现有禁令。
status	object status 对象包含有关活动状态的信息。
status.lifeCycleStatus	string 广播的状态。可以使用 API 的 liveBroadcasts.transition 方法更新状态。 此属性的有效值为： complete - 广播已结束。 created - 广播设置不完整，因此无法转换为 live 或 testing 状态，但已创建且在其他方面有效。 live - 广播处于有效状态。 liveStarting - 广播正在过渡到 live 状态。 ready - 广播设置已完成，广播可以过渡到 live 或 testing 状态。 revoked - 此广播已被管理员移除。 testStarting - 广播正在过渡到 testing 状态。 testing - 广播仅对合作伙伴可见。
status.privacyStatus	string 直播的隐私权状态。请注意，直播仅代表一个 YouTube 视频，因此隐私设置与视频支持的隐私设置相同。此外，您还可以通过修改广播资源或设置相应视频资源的 privacyStatus 字段来设置此字段。 此属性的有效值为： private public unlisted
status.recordingStatus	string 广播的记录状态。 此属性的有效值包括： notRecording recorded recording
status.madeForKids	boolean 此值表示相应广播是否指定为面向儿童的内容。此属性值是只读的。
status.selfDeclaredMadeForKids	boolean 在 liveBroadcasts.insert 请求中，频道所有者可以使用此属性将广播指定为面向儿童的内容。在 liveBroadcasts.list 请求中，仅当频道所有者授权了 API 请求时，才会返回相应属性值。
contentDetails	object contentDetails 对象包含有关活动视频内容的信息，例如内容是否可以在嵌入式视频播放器中显示，或者是否会进行归档，以便在活动结束后观看。
contentDetails.boundStreamId	string 此值可唯一标识与广播绑定的 live stream。
contentDetails.boundStreamLastUpdateTimeMs	datetime boundStreamId 所引用的直播上次更新的日期和时间。
contentDetails.monitorStream	object monitorStream 对象包含有关监控视频流的信息，广播方可以使用这些信息在公开显示广播视频流之前查看活动内容。
contentDetails.monitorStream.enableMonitorStream	boolean 此值用于确定是否为广播启用监控流。如果启用了监控直播，YouTube 会通过仅供广播方使用的特殊直播流广播活动内容。广播公司可以使用该视频流来查看活动内容，还可以确定插入提示点的最佳时间。 如果您打算为直播设置 testing 阶段，或者希望为活动设置直播延迟，则需要将此值设置为 true。此外，如果此属性的值为 true，则您必须先将广播转换为 testing 状态，然后才能将其转换为 live 状态。（如果该属性的值为 false，则广播不能具有 testing 阶段，因此您可以将广播直接过渡到 live 状态。） 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。 重要提示：直播处于 testing 或 live 状态后，便无法更新此属性。
contentDetails.monitorStream.broadcastStreamDelayMs	unsigned integer 如果您已将 enableMonitorStream 属性设置为 true，则此属性用于确定直播延迟的时长。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 0。此值表示直播没有直播延迟。注意：广播处于 testing 或 live 状态后，此属性便无法更新。
contentDetails.monitorStream.embedHtml	string 用于嵌入播放器（播放监控视频流）的 HTML 代码。
contentDetails.enableEmbed	boolean 此设置用于指明是否可以在嵌入式播放器中播放直播视频。如果您选择归档视频（使用 enableArchive 属性），此设置也会应用于归档的视频。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。 注意：直播处于 testing 或 live 状态后，此属性便无法更新。
contentDetails.enableDvr	boolean 此设置用于确定观看者在观看视频时是否可以访问 DVR 控件。借助 DVR 控件，观看者可以暂停、快退或快进内容，从而控制视频播放体验。此属性的默认值为 true。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。 重要提示：如果您希望在广播结束后立即提供播放功能，则必须将该值设置为 true，同时将 enableArchive 属性的值设置为 true。此外，广播一旦处于 testing 或 live 状态，就无法更新此属性。
contentDetails.recordFromStart	boolean 此设置用于指示 YouTube 是否会在活动状态变为直播后自动开始录制直播。 此属性的默认值为 true，只有在广播频道允许为直播停用录制功能时，才能将其设置为 false。 如果您的频道没有停用录制的权限，并且您尝试插入 recordFromStart 属性设置为 false 的广播，则 API 会返回 Forbidden 错误。此外，如果您的频道没有该权限，并且您尝试更新广播以将 recordFromStart 属性设置为 false，则 API 将返回 modificationNotAllowed 错误。 当您 update a broadcast 时，如果您的 API 请求在 part 参数值中包含 contentDetails 部分，则必须设置此属性。不过，当您 insert a broadcast 时，该属性是可选的，默认值为 true。 重要提示：如果您希望在广播结束后立即提供播放内容，还必须将 enableDvr 属性的值设置为 true。如果您将此属性的值设为 true，但未将 enableDvr 属性也设为 true，则归档的视频可能需要大约一天的时间才能开始播放。 注意：直播处于 testing 或 live 状态后，此属性便无法更新。
contentDetails.enableClosedCaptions	boolean 此属性已于 2015 年 12 月 17 日弃用。请改用 contentDetails.closedCaptionsType 属性。 此设置用于指示是否为此广播启用 HTTP POST 字幕。对于已在使用此属性的 API 客户端： 将属性值设置为 true 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsHttpPost。 将属性值设置为 false 等同于将 contentDetails.closedCaptionsType 属性设置为 closedCaptionsDisabled。
contentDetails.closedCaptionsType	string 注意：此属性会替换 contentDetails.enableClosedCaptions 属性。 此属性用于指明您的广播是否启用了字幕，如果启用了，您提供的是哪种类型的字幕： closedCaptionsDisabled：直播的字幕已停用。 closedCaptionsHttpPost：您将使用 HTTP POST 将字幕发送到与直播相关联的提取网址。 closedCaptionsEmbedded：字幕将使用 EIA-608 和/或 CEA-708 格式在视频流中进行编码。
contentDetails.projection	string 相应广播的投影格式。该属性的默认值为 rectangular。 该属性的有效值包括： 360 rectangular
contentDetails.enableLowLatency	boolean 指示是否应为此广播进行编码，以实现低延迟流式传输。低延迟直播可以缩短观看直播的用户看到视频所需的时间，但也会影响直播观看者的分辨率。
contentDetails.latencyPreference	string 表示要为此广播使用哪个延迟时间设置。此属性可用于代替不支持 ultraLow 的 enableLowLatency。 低延迟直播可缩短观看直播的用户看到视频所需的时间，但也会影响播放流畅度。 超低延迟直播可进一步缩短观看者看到视频所需的时间，从而更轻松地与观看者互动，但超低延迟不支持字幕，也不支持高于 1080p 的分辨率。 此属性的有效值为： normal low ultraLow
contentDetails.enableAutoStart	boolean 表示当您在绑定的 live stream 上开始直播视频时，此直播是否应自动开始。
contentDetails.enableAutoStop	boolean 表示此广播是否应在频道所有者停止在绑定视频流上播放视频大约一分钟后自动停止。
contentDetails.availabilityConfig	object 直播的可用性配置。用于设置特定地区的可用性或屏蔽特定地区。此标志是可选标志，如果未设置，则不会强制执行。
contentDetails.availabilityConfig.globalConfig	object 直播的全球播放配置。该视频可在所有地区播放，但 excludedRegionCodes 列表中指定的地区除外。
contentDetails.availabilityConfig.globalConfig.excludedRegionCodes	list (string) 视频遭禁播的地区列表。
contentDetails.availabilityConfig.globalConfig.interval	object 视频在所有未被屏蔽的区域可供观看的默认时间窗口。注意：此属性不支持即将开始或正在进行的直播。
contentDetails.availabilityConfig.globalConfig.interval.startTime	datetime 视频可供观看的日期和时间。如果未指定，则表示视频已可供观看。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
contentDetails.availabilityConfig.globalConfig.interval.endTime	datetime 视频停止可供观看的日期和时间。如果未指定，则视频将永久有效。指定的开始时间和结束时间不能是 5 年以后的时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
contentDetails.availabilityConfig.regionsConfig	object 直播的地区提供情况配置。此视频只能在指定地区播放。
contentDetails.availabilityConfig.regionsConfig.regionIntervals	list (object) 视频可供观看的地区和时间段的列表。如果多次指定某个区域，则使用所有区间的并集。
contentDetails.availabilityConfig.regionsConfig.regionIntervals.regionCode	string 视频可播放的地区。
contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval	object 视频在指定区域可供观看的时间窗口。注意：此属性不支持即将开始或正在进行的直播。
contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval.startTime	datetime 视频在指定地区上架的日期和时间。如果未指定，则表示视频已可供观看。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
contentDetails.availabilityConfig.regionsConfig.regionIntervals.interval.endTime	datetime 视频在指定地区停止提供的日期和时间。如果未指定，则视频将永久有效。指定的开始时间和结束时间不能是 5 年以后的时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
statistics	object statistics 对象包含与直播相关的统计信息。这些统计数据的值可能会在直播期间发生变化，并且只能在直播期间检索。
statistics.totalChatCount	unsigned long 与广播相关联的实时聊天消息总数。如果广播对用户可见、启用了实时聊天功能且至少包含一条消息，则会显示相应属性及其值。请注意，直播结束后，此属性不会指定值。因此，此属性不会标识已完成直播的归档视频的聊天消息数量。
monetizationDetails	object monetizationDetails 对象包含有关视频流创收详细信息的信息，例如广告自动投放功能是否已开启，或者中贴片广告插播是否已延迟。 重要提示：如要为视频启用自动广告，频道必须符合视频创收条件。广播的创收设置（例如启用创收功能或广告自动投放器，即“让 YouTube 为您插入中贴片广告”或“按设定的频次安排中贴片广告”）可以通过 API 或在 YouTube 工作室中设置，具体是在创建广播时或在直播期间修改广播时进行设置。
monetizationDetails.adsMonetizationStatus	string 此属性用于指明视频广播是否已启用中贴片广告。有效值为 on 和 off。
monetizationDetails.eligibleForAdsMonetization	string 此属性用于指明视频广播是否符合投放中贴片广告的条件。直播可能因各种原因而不符合创收条件，例如存在版权主张或频道未设置创收。
monetizationDetails.cuepointSchedule	object cuepointSchedule 对象用于指定广播的广告自动化设置。
monetizationDetails.cuepointSchedule.enabled	boolean 此值用于确定是否在广播中自动插播广告。如果值为 true，YouTube 会自动在直播中插入中贴片广告。 广告的投放时间表将由 monetizationDetails.cuepointSchedule 对象中其他字段的值决定。
monetizationDetails.cuepointSchedule.pauseAdsUntil	datetime 此值指定 YouTube 不应在指定日期和时间之前在广播中插入中贴片广告。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。该值必须设置为未来的日期时间，才能暂停广告；该字段值也可以设置为过去的日期时间或空值，以取消暂停广告。
monetizationDetails.cuepointSchedule.ytOptimizedCuepointConfig	string 此字段用于指定为自动插入的广告提示点选择的选项。该字段可以指定以下三种模式之一： LOW：收入潜力较低，观看者受到的干扰较少 MEDIUM：收入潜力中等，平衡了观看者的体验 HIGH：收入潜力更高，观看者受到的干扰较多
monetizationDetails.cuepointSchedule.creatorCuepointConfig	object creatorCuepointConfig 对象用于指定广告自动播放器选项，创作者可选择中贴片广告的展示方式。
monetizationDetails.cuepointSchedule.creatorCuepointConfig.scheduleStrategy	string 此值用于指定 YouTube 在安排 CuePoint 时应遵循的策略。有效值包括： CONCURRENT：所有观看者在同一时间看到插播点 NON_CONCURRENT：为不同的观看者安排在不同时间的插播点。这种方法可提高广告展示频率，让观看者在符合条件时收到提示点。
monetizationDetails.cuepointSchedule.creatorCuepointConfig.repeatIntervalSecs	unsigned integer 此值用于指定广播期间自动插播广告的时间间隔（以秒为单位）。例如，如果该值为 360，YouTube 可以在每 6 分钟间隔插入中贴片广告提示点。 注意： 该值用于指定连续 cuepoint 的开始时间之间的时间。也就是说，间隔不是从一个提示点的结束时间到下一个提示点的开始时间来衡量的。 为与 YouTube 工作室设置保持一致，此值是 6 分钟的倍数，范围为 6 分钟到 30 分钟。更新请求中在此范围内的任何整数（即使有效）都将向下舍入到最接近的 6 分钟倍数。